AeroMesh 3D is an autonomous multi-agent drone swarm coordination and digital twin platform built for high-performance telemetry streaming and safety-critical path planning. It pairs a highly concurrent backend routing engine with an interactive, browser-based 3D cockpit.
- Concurrent Swarm Simulator: A backend simulation engine running in FastAPI that maintains state for 10+ drones at a telemetry broadcast rate of 20Hz.
- Artificial Potential Field (APF) Pathfinding: Real-time 3D vector-field navigation using numpy, computing attractive forces (towards target) and repulsive forces (away from obstacles and other drones).
- Altitude-Layered Swarm Formations: Deconflicts crowded spaces and goal configurations by organizing drones into layered altitude bands and a circular orbit pattern.
- Tangential Bypass (Vortex Fields): Avoids traditional APF local minima by dynamically steering drones horizontally along the tangent of blocking obstacles/drones.
- Interactive 3D Cockpit: Built with Next.js, React Three Fiber (R3F), and Three.js. Supports:
- Interactive grid viewport where operators can click to update the swarm's target goal.
- Dynamic obstacle spawning, movement, and deletion directly in 3D.
- Live parameter adjustments (swarm size, speed, flight altitude) via a premium dark-themed dashboard.
- Flight path tracking with custom historical drone trails.
AeroMesh 3D consists of two main components:
app/main.py: Entry point exposing HTTP REST endpoints (/api/target,/api/obstacles,/api/parameters,/api/reset) and a WebSocket broadcast server (/ws/telemetry).app/simulation.py: Advancing drone physics vectors (battery decay, velocity calculation, altitude-layered formations, safety constraints).app/apf.py: 3D vector calculations for attractive, repulsive, and tangential vortex forces.
src/app/page.tsx: Main dashboard state management, parameter synchronizing on mount, and trail tracking.src/components/Viewport.tsx: React Three Fiber Canvas with 3D meshes representing drones (glow, selection rings), obstacles (semi-transparent spheres), targets (animated beacons), and floor raycasting.src/components/Sidebar.tsx: High-fidelity dark side panel containing parameter controls and obstacle tools.src/components/Hud.tsx: Real-time HUD showing connection status, drone list (coordinates, battery bars, operational state), target coordinates, and obstacle lists.
- Python 3.12+ (tested with Python 3.14)
- Node.js 18+
cd backend
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --host 127.0.0.1 --port 8000cd frontend
npm install
npm run devOpen http://localhost:3000 in your browser.
The system is equipped with automated E2E tests verifying safety constraints, routing, and frequency targets.
Validates REST APIs and checks that the WebSocket telemetry broadcast is stable at >= 18Hz.
cd backend
source .venv/bin/activate
python verify_m1.pySpawns 10 drones, configures a target goal, dynamically places multiple obstacles directly blocking the swarm's corridor, and commands them to fly. Asserts that:
- All 10 drones successfully reach the goal.
- Drones maintain a minimum distance of
>= 0.5units to all obstacles at all times. - Drones maintain a minimum distance of
>= 0.5units to all other drones at all times. - Zero collision violations occur.
cd backend
source .venv/bin/activate
python test_routing_e2e.pyThe UI styling is built fully in dark mode adhering to the project's tokens:
- Canvas Base:
#090909 - Surface Panels:
#141414(Surface 1),#1c1c1c(Surface 2) - Accent Blue:
#0099ff - Hairlines:
#262626 - Glow Elements: Blue-emissive meshes and real-time point light sources.
- Buttons: Rounded pills following the premium layout guidelines.