# zju-fast-lab/ego-planner-swarm architecture

> Architecture diagram of the GitHub repository zju-fast-lab/ego-planner-swarm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zju-fast-lab/ego-planner-swarm
- Repository: https://github.com/zju-fast-lab/ego-planner-swarm

## Overview

##### Project type and purpose
- This is a ROS‐based, full‐stack multi‐agent (swarm) navigation system with two main domains:
a. Planner stack (“src/planner”) implementing local mapping, path search, trajectory optimization, multi‐robot planning, and detection.
b. Simulator stack (“src/uav_simulator”) providing sensor simulation, map servers, vehicle dynamics (fake or SO3), visualization, message definitions, and utilities.
- Purpose: decentralized, asynchronous quadrotor swarm navigation in unknown, cluttered environments using onboard resources only.

##### File structure
- Top‐level `src` splits into:
- planner/… packages: bspline_opt, drone_detect, path_searching, plan_env, plan_manage, rosmsg_tcp_bridge, traj_utils
- uav_simulator/… packages: Utils (multi_map_server, odom_visualization, pose_utils, quadrotor_msgs, rviz_plugins, uav_utils, waypoint_generator), local_sensing, map_generator, mockamap, so3_control, so3_quadrotor_simulator, fake_drone
- Each subfolder is a ROS package (CMakeLists.txt + package.xml) with nodes, headers, launch files, configs, and tests.
- Key patterns:
- ROS pub/sub and service/launch architecture
- Nodelet plugins for zero‐copy in local_sensing and SO3 control
- TCP bridge for inter‐drone communication
- Catkin workspace build scripts

##### README for additional insights
- The system uses Catkin (ROS1), Armadillo, optional CUDA for local_sensing, and optional physics‐based dynamics vs. fake_drone for scalability.
- Launch files orchestrate the full swarm (`swarm.launch`), single drone (`simple_run.launch`), RViz (`rviz.launch`), simulator only (`simulator.xml`), etc.
- The system is modular—users can swap GPU vs CPU sensor, fake vs physics simulator, enable or disable control nodelets.

##### Details
- 7 planner packages and 10+ simulator packages as separate components.
- Launch files that bring them together (e.g., `simple_run.launch`, `swarm.launch`, `simulator.xml`).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global ROS Master
    ROSMaster(("ROS Master")):::master

    %% UAV Agent Pipeline
    subgraph "UAV Agent Pipeline"
        direction TB
        LocalSensing["local_sensing_node"]:::planner
        PlanEnv["plan_env / grid_map"]:::planner
        PathSearch["dyn_a_star"]:::planner
        BsplineOpt["bspline_opt"]:::planner
        TrajUtils["traj_utils"]:::planner
        DroneDetect["drone_detect"]:::planner
        PlanManage["plan_manage (ego_replan_fsm)"]:::planner
        subgraph "Control & Simulation"
            direction TB
            FakeDrone["fake_drone"]:::simulator
            SO3Control["so3_control nodelet"]:::simulator
            SO3Sim["so3_quadrotor_simulator"]:::simulator
        end
    end

    %% Map Server
    subgraph "Map Services" 
        direction TB
        MultiMapServer["multi_map_server"]:::simulator
        MockaMap["mockamap"]:::simulator
        MapGenerator["map_generator"]:::simulator
    end

    %% Visualization & Utilities
    subgraph "Visualization & Utils"
        direction TB
        OdomViz["odom_visualization"]:::simulator
        RVizPlugins["rviz_plugins"]:::simulator
        UAVUtils["uav_utils"]:::simulator
        PoseUtils["pose_utils"]:::simulator
        QuadMsgs["quadrotor_msgs"]:::simulator
        WaypointGen["waypoint_generator"]:::simulator
    end

    %% Communication Bridge
    Bridge["rosmsg_tcp_bridge"]:::comm

    %% Connections
    ROSMaster -->|pub/sub registry| LocalSensing
    LocalSensing -->|"/depth_image,/pointcloud"| PlanEnv
    PlanEnv -->|occupancy grid| PathSearch
    PathSearch -->|raw path| BsplineOpt
    BsplineOpt -->|B-spline trajectory| TrajUtils
    DroneDetect -->|detections| PlanManage
    TrajUtils -->|"/Bspline"| PlanManage
    PlanEnv -->|neighbor states| PlanManage
    PlanManage -->|"/cmd_vel"| FakeDrone
    PlanManage -->|"/cmd_vel"| SO3Control
    SO3Control -->|control inputs| SO3Sim
    FakeDrone -->|"/odom"| PlanManage
    SO3Sim -->|"/odom"| PlanManage

    %% Map Services and Visualization
    MultiMapServer -->|global map topics| OdomViz
    MockaMap -->|mock map topics| OdomViz
    MapGenerator -->|procedural maps| MultiMapServer
    OdomViz -->|visual data| RVizPlugins
    QuadMsgs -->|message defs| LocalSensing
    UAVUtils -->|utility funcs| LocalSensing
    PoseUtils -->|pose msgs| LocalSensing
    WaypointGen -->|waypoints| PlanManage

    %% Communication Bridge connections
    PlanManage -->|state topics| Bridge
    Bridge -->|TCP streams| PlanManage

    %% Click Events
    click LocalSensing "https://github.com/zju-fast-lab/ego-planner-swarm/tree/master/src/uav_simulator/local_sensing"
    click PlanEnv "https://github.com/zju-fast-lab/ego-planner-swarm/tree/master/src/planner/plan_env"
    click PathSearch "https://github.com/zju-fast-lab/ego-planner-swarm/tree/master/src/planner/path_searching"
    click BsplineOpt "https://github.com/zju-fast-lab/ego-planner-swarm/tree/master/src/planner/bspline_opt"
    click TrajUtils "https://github.com/zju-fast-lab/ego-planner-swarm/tree/master/src/planner/traj_utils"
    click DroneDetect "https://github.com/zju-fast-lab/ego-planner-swarm/tree/master/src/planner/drone_detect"
    click PlanManage "https://github.com/zju-fast-lab/ego-planner-swarm/tree/master/src/planner/plan_manage"
    click Bridge "https://github.com/zju-fast-lab/ego-planner-swarm/tree/master/src/planner/rosmsg_tcp_bridge"
    click FakeDrone "https://github.com/zju-fast-lab/ego-planner-swarm/tree/master/src/uav_simulator/fake_drone"
    click SO3Control "https://github.com/zju-fast-lab/ego-planner-swarm/tree/master/src/uav_simulator/so3_control"
    click SO3Sim "https://github.com/zju-fast-lab/ego-planner-swarm/tree/master/src/uav_simulator/so3_quadrotor_simulator"
    click MultiMapServer "https://github.com/zju-fast-lab/ego-planner-swarm/tree/master/src/uav_simulator/Utils/multi_map_server"
    click MapGenerator "https://github.com/zju-fast-lab/ego-planner-swarm/tree/master/src/uav_simulator/map_generator"
    click MockaMap "https://github.com/zju-fast-lab/ego-planner-swarm/tree/master/src/uav_simulator/mockamap"
    click OdomViz "https://github.com/zju-fast-lab/ego-planner-swarm/tree/master/src/uav_simulator/Utils/odom_visualization"
    click RVizPlugins "https://github.com/zju-fast-lab/ego-planner-swarm/tree/master/src/uav_simulator/Utils/rviz_plugins"
    click UAVUtils "https://github.com/zju-fast-lab/ego-planner-swarm/tree/master/src/uav_simulator/Utils/uav_utils"
    click PoseUtils "https://github.com/zju-fast-lab/ego-planner-swarm/tree/master/src/uav_simulator/Utils/pose_utils"
    click QuadMsgs "https://github.com/zju-fast-lab/ego-planner-swarm/tree/master/src/uav_simulator/Utils/quadrotor_msgs"
    click WaypointGen "https://github.com/zju-fast-lab/ego-planner-swarm/tree/master/src/uav_simulator/Utils/waypoint_generator"

    %% Styles
    classDef planner fill:#cce5ff,stroke:#005cbf,color:#005cbf;
    classDef simulator fill:#d4edda,stroke:#155724,color:#155724;
    classDef comm fill:#ffeeba,stroke:#856404,color:#856404;
    classDef master fill:#f8d7da,stroke:#721c24,color:#721c24,stroke-dasharray: 5 5;
```
