Urban Mobility MARL WebSocket - Struct API Documentation

Overview

The Urban Mobility MARL (Multi-Agent Reinforcement Learning) WebSocket API provides real-time control and interaction with dynamic urban mobility simulations. This system enables you to create, modify, and observe complex multi-agent scenarios involving pedestrians, vehicles, and environmental stimuli in real-time.

Key Features

Real-time Agent Control: Dynamically add, remove, and modify agents during simulation
Multi-Agent Types: Support for pedestrians, vehicles, and public transport
Environmental Stimuli: Add emergency scenarios like evacuations or disasters
Pathfinding: Intelligent routing using real-world road networks
Geospatial Integration: Uses actual geographic data and elevation models
Scalable: Handle thousands of agents simultaneously

Connection

Connect to the WebSocket endpoint to start interacting with the MARL system:

ws://api.vects.ai:8001/ws/marl_state

The WebSocket server runs on port 8001 by default. For production environments, use the secure WebSocket protocol (wss://) when available.

Agent Types

The system supports multiple agent types, each with unique behaviors:

Type ID	Name	Description
`0`	Pedestrian	Individual walking agents with basic pathfinding
`1`	Vehicle	Cars, trucks, and other road vehicles following traffic rules
`2`	Public Transport	Buses, trains, and other mass transit (planned feature)

Simulation Flow

1. Connection & Initialization

const ws = new WebSocket('ws://api.vects.ai:8001/ws/marl_state');

ws.onopen = function() {
    console.log('Connected to MARL WebSocket');
    
    // Request initial agent population
    ws.send(JSON.stringify({
        type: 'request_initial_agents',
        payload: {
            focus_latitude: 37.7749,
            focus_longitude: -122.4194
        }
    }));
};

2. Receive Agent Data

ws.onmessage = function(event) {
    const message = JSON.parse(event.data);
    
    switch(message.type) {
        case 'add_agent':
            addAgentToScene(message.payload);
            break;
        case 'initial_population_complete':
            console.log(`Loaded ${message.payload.count} agents`);
            break;
        // Handle other message types...
    }
};

3. Dynamic Interaction

// Request new path for an agent
function requestNewPath(agentId) {
    ws.send(JSON.stringify({
        type: 'request_new_path',
        payload: {
            agent_id: agentId
        }
    }));
}

// Activate emergency stimulus
function activateEmergency(lat, lng) {
    ws.send(JSON.stringify({
        type: 'set_stimulus',
        payload: {
            active: true,
            location: [lat, lng]
        }
    }));
}

Agent Properties

Each agent contains comprehensive data for realistic simulation:

Basic Properties

ID: Unique identifier (sim_agent_123)
Position: Geographic coordinates [latitude, longitude]
Velocity: Movement vector [dLat, dLng]
Type: Agent type (0=pedestrian, 1=vehicle)
Goal: Target destination coordinates

Behavioral Properties

Path: Array of waypoint coordinates for vehicles
Fleeing Status: Whether agent is responding to emergency stimulus
State: Current behavioral state (walking, driving, waiting, etc.)

Visual Properties

Model References: 3D model URLs and animation data
Attributes: Customizable properties for appearance and behavior

Geospatial Features

Real-World Data Integration

OpenStreetMap: Road networks and building footprints
Elevation Models: Terrain height data for realistic positioning
Geographic Bounds: Configurable simulation areas

Coordinate Systems

Input/Output: Geographic coordinates (WGS84)
Internal Processing: Projected coordinates for performance
3D Positioning: Includes elevation data for vertical accuracy

Performance Considerations

Scalability

Agent Limits: Up to 1,000 agents per simulation (configurable)
Update Frequency: Real-time updates with minimal latency
Memory Management: Efficient spatial indexing and culling

Network Optimization

Message Batching: Multiple updates combined when possible
Compression: JSON payload optimization
Connection Management: Automatic reconnection and heartbeat

Use Cases

Emergency Response Planning

Simulate evacuation scenarios with dynamic obstacles and changing conditions:

// Create emergency evacuation scenario
ws.send(JSON.stringify({
    type: 'set_stimulus',
    payload: {
        active: true,
        location: [37.7749, -122.4194] // Emergency location
    }
}));

Traffic Flow Analysis

Study traffic patterns and congestion with realistic vehicle behavior:

// Request initial population focused on traffic intersection
ws.send(JSON.stringify({
    type: 'request_initial_agents',
    payload: {
        focus_latitude: 37.7849,
        focus_longitude: -122.4094
    }
}));

Urban Planning

Test infrastructure changes and their impact on mobility:

// Monitor agent paths to analyze route efficiency
ws.onmessage = function(event) {
    const message = JSON.parse(event.data);
    if (message.type === 'new_path') {
        analyzeRouteEfficiency(message.payload.path_coords);
    }
};

Crowd Dynamics

Study pedestrian flow in public spaces and events:

// Focus simulation on pedestrian-heavy area
ws.send(JSON.stringify({
    type: 'request_initial_agents',
    payload: {
        focus_latitude: 37.7849,  // Union Square
        focus_longitude: -122.4094
    }
}));

Integration Examples

Three.js Visualization

import * as THREE from 'three';

class MARLVisualizer {
    constructor() {
        this.scene = new THREE.Scene();
        this.agents = new Map();
        this.ws = new WebSocket('ws://api.vects.ai:8001/ws/marl_state');
        
        this.ws.onmessage = (event) => {
            this.handleMessage(JSON.parse(event.data));
        };
    }
    
    handleMessage(message) {
        switch(message.type) {
            case 'add_agent':
                this.addAgent(message.payload);
                break;
            case 'new_path':
                this.updateAgentPath(message.payload);
                break;
            case 'update_flee_status':
                this.updateFleeStatus(message.payload);
                break;
        }
    }
    
    addAgent(agentData) {
        const geometry = agentData.type === 1 ? 
            new THREE.BoxGeometry(2, 1, 4) :  // Vehicle
            new THREE.CylinderGeometry(0.3, 0.3, 1.7); // Pedestrian
            
        const material = new THREE.MeshBasicMaterial({
            color: agentData.is_fleeing ? 0xff0000 : 0x00ff00
        });
        
        const mesh = new THREE.Mesh(geometry, material);
        
        // Convert lat/lng to scene coordinates
        const position = this.geoToScene(agentData.position);
        mesh.position.set(position.x, position.y, position.z);
        
        this.scene.add(mesh);
        this.agents.set(agentData.id, mesh);
    }
}

Unity Integration

using System;
using UnityEngine;
using WebSocketSharp;
using Newtonsoft.Json;

public class MARLController : MonoBehaviour 
{
    private WebSocket ws;
    private Dictionary<string, GameObject> agents = new Dictionary<string, GameObject>();
    
    void Start() 
    {
        ws = new WebSocket("ws://api.vects.ai:8001/ws/marl_state");
        
        ws.OnMessage += (sender, e) => {
            var message = JsonConvert.DeserializeObject<MARLMessage>(e.Data);
            HandleMessage(message);
        };
        
        ws.Connect();
        
        // Request initial agents
        var request = new {
            type = "request_initial_agents",
            payload = new {
                focus_latitude = 37.7749,
                focus_longitude = -122.4194
            }
        };
        
        ws.Send(JsonConvert.SerializeObject(request));
    }
    
    void HandleMessage(MARLMessage message) 
    {
        switch(message.type) 
        {
            case "add_agent":
                CreateAgent(message.payload);
                break;
            case "new_path":
                UpdateAgentPath(message.payload);
                break;
        }
    }
}

Error Handling

Connection Issues

ws.onerror = function(error) {
    console.error('WebSocket error:', error);
    // Implement reconnection logic
    setTimeout(() => {
        connectToMARL();
    }, 5000);
};

ws.onclose = function(event) {
    console.log('WebSocket closed:', event.code, event.reason);
    // Handle graceful shutdown or reconnection
};

Message Validation

function validateMessage(message) {
    if (!message.type || !message.payload) {
        console.error('Invalid message format:', message);
        return false;
    }
    return true;
}

Next Steps

Learn about Client Messages you can send to the server
Understand Server Messages you’ll receive
Explore Risk Analysis integration for enhanced simulations
Check out Simulation APIs for pre-generated scenarios

​Overview

​Key Features

​Connection

​Agent Types

​Simulation Flow

​1. Connection & Initialization

​2. Receive Agent Data

​3. Dynamic Interaction

​Agent Properties

​Basic Properties

​Behavioral Properties

​Visual Properties

​Geospatial Features

​Real-World Data Integration

​Coordinate Systems

​Performance Considerations

​Scalability

​Network Optimization

​Use Cases

​Emergency Response Planning

​Traffic Flow Analysis

​Urban Planning

​Crowd Dynamics

​Integration Examples

​Three.js Visualization

​Unity Integration

​Error Handling

​Connection Issues

​Message Validation

​Next Steps

Overview

Key Features

Connection

Agent Types

Simulation Flow

1. Connection & Initialization

2. Receive Agent Data

3. Dynamic Interaction

Agent Properties

Basic Properties

Behavioral Properties

Visual Properties

Geospatial Features

Real-World Data Integration

Coordinate Systems

Performance Considerations

Scalability

Network Optimization

Use Cases

Emergency Response Planning

Traffic Flow Analysis

Urban Planning

Crowd Dynamics

Integration Examples

Three.js Visualization

Unity Integration

Error Handling

Connection Issues

Message Validation

Next Steps