Bi-space Viewer

A web-based viewer for bi-grids (one class of bi-spatial structures). It provides an interactive 3D environment for exploring and debugging bi-grid models.

Features

• Visualization

  • Load sample models
  • Upload custom XMI files
  • Generate grids via the bigrid-provider-service
  • Fetch from a CDO repository

• Live Monitoring

  • Visualize simulated or physical agents as colored blocks

• 3D Navigation

  • Free-flight camera

Screenshots

Getting Started

Run the Web Application

$ nvm install node --lts
$ nvm use --lts 
$ npm install
$ npm run dev

Open the browser at: http://localhost:5173/

Press ESC to leave the 3D view and take back control.

Block World Commands

• Setup: Install MQTT Server: https://www.atlantic.net/dedicated-server-hosting/how-to-install-mosquitto-mqtt-server-on-ubuntu-24-04/
• Allow anonymous access + Protocol Websockets
• Default URL: mqtt://localhost:1883 and ws://localhost:9090

JSON Message:

• action: name of the action
• params:
  • key: block coordinates [x, y, z]
  • color: any valid hex color value

Start blinking a block

$ mosquitto_pub -t world/blocks -m '{
"action": "blink_start",
"params": { "color": "#ff0000", "key": [1,1,0] }
}'
$ mosquitto_pub -t world/blocks -m '{
"action": "blink_start",
"params": { "color": "#ff0000", "key": [2.50, 0.35, 0.00] }
}'

Stop blinking a block

$ mosquitto_pub -t world/blocks -m '{
"action": "blink_stop",
"params": { "key": [1,1,0] }
}'

Configuration

Enable World Model Generators: bigrid-provider-service

To enable model generation within the web interface, start the bigrid-provider-service:

https://github.com/UniAgent-Platform/bigrid-provider-service

After building the Docker image, run:

$ sudo docker run -p 8080:8080 bigrid-provider-service

The service will run in the background and expose its API on port 8080.

• Change URL+Port: vite.config.ts

CDO Model Repository

• Start the CDO server if you want to load models from a CDO repository. See here and here for example.

If these services are not running, some features may be unavailable, but the application will still start and all offline functionality will work normally.

Live Agent Position Monitoring

WebSocket

• Live monitoring of simulated or physical Crazyflie drone positions is supported via the cf.PyControl WebSocket integration: cf.PyControl WebSocket integration
• The controller publishes position updates over WebSocket, allowing the web application to visualize real-time drone movement inside the 3D environment.
• WebSocket Message Format (JSON):

{
  "message": "crazyflie_position",
  "value": "[x, y, z]"
}

• value: stringified array containing the drone’s estimated position in meters (x, y, z)

ROS2

• The ROS connector relies on Crazyswarm2 and the JAVA rosbridge. Check the tutorial here.

$ ros2 launch rosbridge_server rosbridge_websocket_launch.xml

FAQ

How to Create Bi-grids?

Use:

• bigrid-provider-service
• bigraphs.model-provider
• Bigraph Framework
• Bigellor

Create your own: The signature of bigrids is very simple and their usage as well. The file parsing logic lives in BigraphGridXMLParser.js.

Bi-grid Parser

• The renderer supports two bi-grid encodings:
  • Single-root (1): all Locale elements share a single root.
  • Multi-root (0): each Locale is attached to its own root.
  • Moreover, the coordinates can be encoded as "outer names" or as dedicated "CO-typed nodes" (coordinate nodes).
• The XMI parsing logic lives in BigraphGridXMLParser.js.
  It is self-contained and can be ported to other languages that need to read the same bi-grid format (XMI).

License

This Open Source software is released under the Apache 2.0 license.

---

Copyright © 2025 The UniAgent Developers and Contributors.
Main Developer: Dominik Grzelak Contributor: Tianxiong Zhang