How utiasdsl/amswarmx works
Project Type and Purpose
• AMSwarmX is a ROS‐based swarm coordination package for multi-UAV planning and simulation.
• It integrates obstacle decomposition, grid-based planning, trajectory optimization, and RViz/Gazebo visualization to emulate and test safe multi-agent navigation in complex environments.
File Structure Analysis
• Top-level:
• amswarmx/ — main ROS package
· include/ & src/ — core C++ implementation of planning, optimization, and utilities
· launch/ — ROS launch files (Gazebo simulation, RViz configs, bag playback)
· params/ & data/ — YAML/TXT config for planner parameters and simulation settings
· crazyflie/ — Gazebo model definition (meshes + SDF) for UAV agent
· world/ — environment descriptions (.bt files) for Gazebo
· media/ — example GIFs of demo runs
• thirdparty/ — embedded dependencies (DecompUtil, jps3d, ROS message and plugin packages, graph_rviz_plugin, catkin_simple, etc.)
Key Insights from README
• Builds on ROS Melodic/Noetic, Octomap, dynamic-edt-3d, Eigen3
• Two-stage build: thirdparty libs → amswarmx
• Run via roslaunch amswarmx simulation.launch to start Gazebo + Octomap server + AMSwarmX nodes + RViz
Main Components
a. Simulation & Perception
• Gazebo simulator (world definitions + crazyflie model)
• Octomap server (3D occupancy map)
• dynamic-edt-3d (Euclidean Distance Transform)
b. Obstacle Decomposition
• DecompUtil library (implicit non-convex decomposition)
• decomp_ros_utils (visualization of polyhedra/ellipsoids in RViz)
c. Planning & Optimization
• jps3d-based grid planner (distance map or JPS)
• Anchor/goal selection module
• Polar and position variable solvers (nonconvex decomposition based)
• Trajectory optimizer (runs on ROS topics)
d. Coordination & Control
• run_am_swarm ROS node (or runner wrapper) orchestrates all modules, subscribes/publishes to dynamic_msgs topics (FullState, TrajectoryArray, ObstacleArray, SFC, RSFC, etc.)
e. Visualization & Interaction
• RViz with graph_rviz_plugin panels for real-time trajectory, state, constraint visualization
• ROS topic playback (rosbag) for replay
Relationships & Data Flows
• Gazebo → publishes /octomap_full → Octomap server → outputs occupancy map
• Occupancy map → fed to DecompUtil → generates convex regions → passed to run_am_swarm
• run_am_swarm:
· invokes grid_planner → candidate waypoints
· invokes trajectory_optimizer → optimized paths
· publishes TrajectoryArray → controllers / visualization
• ROS Master coordinates nodes; dynamic_msgs define the message contracts
• RViz & graph_rviz_plugin subscribe to topics for live plotting
• User adjusts YAML configs (config_am_swarm.yaml) and launch files to tailor environments
Architectural Patterns & Principles
• Modular ROS nodes (one node per functional block)
• Clear separation: perception, decomposition, planning, optimization, visualization
• Plugin / thirdparty extensibility via catkin_simple and package.xml
• Data-driven configuration (params folder + dynamic_msgs)
What
• Labels: node names, library names, topic/message names
• Annotations: indicate config files (e.g., config_am_swarm.yaml) feeding parameters into nodes