Version: 1.0.0
Date: September 2025
Status: Production Ready
Mission Type: 4 (SWARM_TRAJECTORY)
The Swarm Trajectory Feature enables coordinated drone swarm missions where top leaders follow pre-defined waypoint trajectories while followers maintain precise formations using configured offsets. This creates sophisticated swarm choreography with minimal user input.
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Frontend UI │────│ Backend API │────│ Processing │
│ (React + CSS) │ │ (Flask REST) │ │ Pipeline │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │
▼ ▼
┌─────────────────┐ ┌─────────────────┐
│ File Storage │ │ Mission Exec │
│ (CSV + Plots) │ │ (drone_show) │
└─────────────────┘ └─────────────────┘
Lead Drone Processing (Global Coordinates Only):
Follower Processing (Respects swarm.csv Configuration):
body_coord=1): Forward/Right relative to lead drone’s heading
# offset_n=5m Forward, offset_e=3m Right → rotated by lead drone's yaw
# Maintains formation relative to heading direction
body_coord=0): Fixed North/East geographic directions
# offset_n=5m North, offset_e=3m East → fixed geographic formation
# Formation maintains geographic orientation regardless of heading
Final Output: All drones receive global lat/lon/alt trajectories for mission execution.
KML Export Features:
Cluster-based UI Organization:
Usage: Expand trajectory previews to see cluster formations, download KML files for any drone, view in Google Earth for immersive 3D visualization.
graph LR
A[Mission Planning Tool] --> B[Export CSV Waypoints]
B --> C[Save as 'Drone X.csv' format]
CSV Format Required:
Name,Latitude,Longitude,Altitude_MSL_m,TimeFromStart_s,EstimatedSpeed_ms,Heading_deg,HeadingMode
Waypoint 1,35.69466817,51.28617904,1300.00,10.0,8.0,25.8,auto
Waypoint 2,35.72774031,51.30590792,1370.00,520.0,8.0,144.7,auto
functions/)functions/
├── swarm_analyzer.py # Parse swarm structure, find lead drones
├── swarm_global_calculator.py # Calculate follower positions
├── swarm_trajectory_smoother.py # Smooth waypoint trajectories
├── swarm_trajectory_processor.py # Main orchestration
└── swarm_plotter.py # Generate visualization plots
gcs-server/)gcs-server/
├── swarm_trajectory_routes.py # REST API endpoints
└── app.py # Route registration
app/dashboard/drone-dashboard/src/)src/
├── pages/SwarmTrajectory.js # Main UI component
├── styles/SwarmTrajectory.css # Modern styling
└── constants/droneConstants.js # Mission type constants
├── src/enums.py # Mission enum definition
├── src/drone_setup.py # Mission handler
└── swarm_trajectory_mission.py # Execution script
analyze_swarm_structure(swarm_data=None)Parses swarm configuration to identify leader-follower relationships.
Returns:
{
'top_leaders': [1, 2, 23], # HW IDs of top leaders
'hierarchies': {1: [3,4,5], 2: [6,7]}, # Leader -> followers mapping
'swarm_config': {...} # Full drone configurations
}
process_swarm_trajectories()Main processing pipeline that orchestrates the entire workflow.
Process:
smooth_trajectory_with_waypoints(waypoints_df, dt=0.05)Converts waypoint trajectories to smooth interpolated paths.
Input: CSV waypoints
Output: Smooth trajectory at 0.05s intervals with velocities/accelerations
shapes/ (or shapes_sitl/ for simulation)
└── swarm_trajectory/
├── raw/ # Uploaded lead drone trajectories
│ ├── Drone 1.csv
│ ├── Drone 2.csv
│ └── ...
├── processed/ # Generated drone trajectories
│ ├── Drone 1.csv
│ ├── Drone 2.csv
│ └── ...
└── plots/ # Visualization plots
├── drone_X_trajectory.jpg # Individual drone plots
├── cluster_leader_X.jpg # Cluster formations
├── combined_swarm.jpg # Complete swarm view
└── (KML files generated on-demand, no storage needed)
Name,Latitude,Longitude,Altitude_MSL_m,TimeFromStart_s,EstimatedSpeed_ms,Heading_deg,HeadingMode
Waypoint 1,35.694668,51.286179,1300.0,10.0,8.0,25.8,auto
t,lat,lon,alt,vx,vy,vz,ax,ay,az,yaw,mode,ledr,ledg,ledb
10.0,35.694668,51.286179,1300.0,0.0001,0.00003,0.211,0.0,0.0,0.0,25.8,70,255,0,0
/api/swarm/GET /leadersGet swarm leaders and upload status.
Response:
{
"success": true,
"leaders": [1, 2],
"hierarchies": {"1": 3, "2": 2},
"uploaded_leaders": [1],
"simulation_mode": false
}
POST /trajectory/upload/<leader_id>Upload trajectory CSV for specific leader.
Request: multipart/form-data with CSV file
Response: Success/error message
POST /trajectory/processProcess all uploaded trajectories.
Response:
{
"success": true,
"processed_drones": 5,
"statistics": {"leaders": 2, "followers": 3, "errors": 0}
}
GET /trajectory/statusGet processing status and file counts.
POST /trajectory/clearClear all trajectory files.
GET /trajectory/download/<drone_id>Download processed trajectory CSV for specific drone.
GET /trajectory/download-kml/<drone_id>Download KML file for Google Earth visualization.
Response: KML file with time-based animation and 3D terrain visualization.
src/params.py)# Swarm Trajectory Mode Configuration
swarm_trajectory_dt = 0.05 # Interpolation timestep (seconds)
swarm_trajectory_max_speed = 20.0 # Maximum speed limit (future use)
# LED Colors (RGB)
swarm_leader_led_color = (255, 0, 0) # Red for leaders
swarm_follower_led_color = (0, 255, 0) # Green for followers
# Error handling
swarm_missing_leader_strategy = 'skip' # 'skip' or 'error'
swarm_trajectory_mission.py_execute_swarm_trajectory() in drone_setup.pyfollow=0get_swarm_trajectory_folders()ls -la shapes/swarm_trajectory/main-candidategcs-server/ outputLast Updated: September 6, 2025
Next Review: October 2025
Maintained By: MAVSDK Drone Show Development Team