# utiasdsl/amswarmx architecture

> Architecture diagram of the GitHub repository utiasdsl/amswarmx, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/utiasdsl/amswarmx
- Repository: https://github.com/utiasdsl/amswarmx

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Simulation & Perception"
        Gazebo[/"Gazebo Simulator"/]:::simulation
        Octomap["Octomap Server"]:::simulation
        DynamicEDT["dynamic-edt-3d"]:::simulation
    end
    Gazebo -->|"/octomap_full"| Octomap
    Octomap -->|"occupancy map"| DynamicEDT

    subgraph "Obstacle Decomposition"
        DU["DecompUtil Library"]:::decomp
        decompViz["decomp_ros_utils"]:::decomp
    end
    DynamicEDT -->|"distance field"| DU
    DU -->|"convex regions"| decompViz

    subgraph "Planning"
        GP["Grid-based Planner"]:::planning
        AG["Anchor/Goal Selection"]:::planning
    end
    decompViz -->|"regions"| GP
    GP -->|"waypoints"| AG

    subgraph "Optimization"
        PSol["Polar Variable Solver"]:::optimization
        PosSol["Position Variable Solver"]:::optimization
        TO["Trajectory Optimizer"]:::optimization
    end
    AG -->|"anchors/goals"| PSol
    PSol --> PosSol
    PosSol -->|"initial traj"| TO

    subgraph "Ox & Utility"
        OUtils["Obstacle Utilities"]:::utility
        TUtils["Trajectory Utilities"]:::utility
    end
    DU --> OUtils
    TO --> TUtils

    subgraph "Coordination"
        Run["run_am_swarm Node"]:::coord
        Main["main_am_swarm"]:::coord
    end
    GP --> Run
    TO --> Run
    decompViz --> Run
    Run -->|"TrajectoryArray"| Controllers["Controllers"]:::external
    Run -->|"FullState"| decompViz

    subgraph "Visualization"
        RViz["RViz + graph_rviz_plugin"]:::vis
        Rosbag["Rosbag Playback"]:::vis
    end
    Run --> RViz
    Run --> Rosbag

    subgraph "Config & Data"
        Config["config_am_swarm.yaml"]:::config
        Data["Simulation Data Outputs"]:::data
    end
    Config --> Run
    Run --> Data

    JPS["JPS3D Library"]:::external
    DM["dynamic_msgs Definitions"]:::external
    JPS --> GP
    DM --> Run

    click Gazebo "https://github.com/utiasdsl/amswarmx/tree/master/amswarmx/world"
    click Octomap "https://github.com/utiasdsl/amswarmx/blob/master/amswarmx/launch/simulation.launch"
    click DU "https://github.com/utiasdsl/amswarmx/tree/master/thirdparty/DecompUtil"
    click decompViz "https://github.com/utiasdsl/amswarmx/tree/master/thirdparty/decomp_ros_utils"
    click GP "https://github.com/utiasdsl/amswarmx/blob/master/amswarmx/include/amswarmx/run_grid_planner.hpp"
    click GP "https://github.com/utiasdsl/amswarmx/blob/master/amswarmx/src/amswarmx/run_grid_planner.cpp"
    click AG "https://github.com/utiasdsl/amswarmx/blob/master/amswarmx/include/amswarmx/select_anchor_goal.hpp"
    click AG "https://github.com/utiasdsl/amswarmx/blob/master/amswarmx/src/amswarmx/select_anchor_goal.cpp"
    click PSol "https://github.com/utiasdsl/amswarmx/blob/master/amswarmx/include/amswarmx/solve_polar_var.hpp"
    click PSol "https://github.com/utiasdsl/amswarmx/blob/master/amswarmx/src/amswarmx/solve_polar_var.cpp"
    click PosSol "https://github.com/utiasdsl/amswarmx/blob/master/amswarmx/include/amswarmx/solve_position_var.hpp"
    click PosSol "https://github.com/utiasdsl/amswarmx/blob/master/amswarmx/src/amswarmx/solve_position_var.cpp"
    click TO "https://github.com/utiasdsl/amswarmx/blob/master/amswarmx/include/amswarmx/run_trajectory_optimizer.hpp"
    click TO "https://github.com/utiasdsl/amswarmx/blob/master/amswarmx/src/amswarmx/run_trajectory_optimizer.cpp"
    click OUtils "https://github.com/utiasdsl/amswarmx/blob/master/amswarmx/include/amswarmx/obstacles_utils.hpp"
    click OUtils "https://github.com/utiasdsl/amswarmx/blob/master/amswarmx/src/amswarmx/obstacles_utils.cpp"
    click TUtils "https://github.com/utiasdsl/amswarmx/blob/master/amswarmx/include/amswarmx/trajectory_utils.hpp"
    click TUtils "https://github.com/utiasdsl/amswarmx/blob/master/amswarmx/src/amswarmx/trajectory_utils.cpp"
    click Run "https://github.com/utiasdsl/amswarmx/blob/master/amswarmx/include/runner/run_am_swarm.hpp"
    click Run "https://github.com/utiasdsl/amswarmx/blob/master/amswarmx/src/runner/run_am_swarm.cpp"
    click Main "https://github.com/utiasdsl/amswarmx/blob/master/amswarmx/src/main_am_swarm.cpp"
    click Rosbag "https://github.com/utiasdsl/amswarmx/blob/master/amswarmx/launch/play_bag.launch"
    click RViz "https://github.com/utiasdsl/amswarmx/tree/master/amswarmx/launch/rviz_config/"
    click Config "https://github.com/utiasdsl/amswarmx/blob/master/amswarmx/params/config_am_swarm.yaml"
    click Data "https://github.com/utiasdsl/amswarmx/tree/master/amswarmx/data"
    click JPS "https://github.com/utiasdsl/amswarmx/tree/master/thirdparty/jps3d"
    click DM "https://github.com/utiasdsl/amswarmx/tree/master/thirdparty/dynamic_msgs"

    classDef simulation fill:#AED6F1,stroke:#21618C,color:#1B4F72
    classDef decomp fill:#ABEBC6,stroke:#196F3D,color:#145A32
    classDef planning fill:#A9DFBF,stroke:#27AE60,color:#145A32
    classDef optimization fill:#FAD7A0,stroke:#D68910,color:#7E5109
    classDef coord fill:#F5B7B1,stroke:#C0392B,color:#78281F
    classDef vis fill:#D7BDE2,stroke:#8E44AD,color:#512E5F
    classDef config fill:#F2D7D5,stroke:#C0392B,color:#78281F
    classDef data fill:#EAECEE,stroke:#7B7D7D,color:#2C3E50
    classDef utility fill:#FCF3CF,stroke:#B7950B,color:#7D6608
    classDef external fill:#E5E7E9,stroke:#A6ACAF,color:#1C2833
```
