# zju-fast-lab/visplanner architecture

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

- Interactive diagram: https://gitdiagram.com/zju-fast-lab/visplanner
- Repository: https://github.com/zju-fast-lab/visplanner

## Overview

##### Project Type and Purpose
- visPlanner is a ROS‑based full‑stack robotics framework for visibility‑aware trajectory planning in aerial tracking.
- It combines a multi‑package planner (`src/planner`) and a UAV simulator suite (`src/uav_simulator`), exposing ROS nodes/services/topics for end‑to‑end simulation, sensing, planning, and control.

##### High‑Level Architecture Components
a. ROS Middleware
- Central communication backbone (topics, services, actions).
- Manages message passing between planner, detector, simulator, controller.
b. Planner Suite (`src/planner`)
- plan_manage: orchestration node (`ego_planner_node`, FSM, `planner_manager`).
- bezier_predict: target motion prediction (CUDA‐optional).
- bspline_opt: trajectory optimizer (gradient/LBFGS).
- path_searching: coarse path generation (D* / dyn A*).
- plan_env: environment model (grid map, raycasting).
- drone_detect: vision‐based target detection node.
- traj_utils: common messages (Bspline, MultiBsplines) & visualization.
- rosmsg_tcp_bridge: bridge between ROS and external TCP interfaces.
c. UAV Simulator Suite (`src/uav_simulator`)
- so3_quadrotor_simulator: physics engine (Boost.odeint dynamics).
- so3_control: low‑level SO(3) controller nodelet.
- fake_drone: simple odom emulator.
- local_sensing: GPU‑accelerated depth/pointcloud simulator.
- map_generator, mockamap, multi_map_server: environment/map services.
- odom_visualization, pose_utils, rviz_plugins: visualization and utilities.
- quadrotor_msgs: custom ROS message definitions for UAV.
- waypoint_generator: scripted waypoint publisher.

##### Interaction and Data Flow
1. User via RViz → 3D Nav Goal topic → plan_manage node
2. plan_manage triggers path_searching → returns coarse waypoints
3. plan_manage calls bezier_predict (predictor) → future target state
4. plan_manage calls bspline_opt → optimized trajectory under visibility constraints
5. plan_manage publishes trajectory (Bspline.msg) to controller topic
6. so3_control nodelet → computes low‑level motor commands → publishes to simulator
7. so3_quadrotor_simulator → simulates physics → publishes Odometry.msg
8. local_sensing → simulates depth/pointcloud → publishes sensor topics
9. plan_env → subscribes to map & sensor topics → updates occupancy grid
10. drone_detect → subscribes to camera/image topics → publishes target pose
11. rosmsg_tcp_bridge → optionally bridges planner topics to external clients

##### Key Architectural Patterns
- Modular ROS nodes: each package encapsulates a well‑defined capability.
- Publish/subscribe for asynchronous data flow.
- Service/action calls for synchronous optimization routines.
- Separation of concerns: planning, prediction, control, simulation, sensing.
- Use of plugin patterns in so3_control (nodelet) and rviz_plugins.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Interface
    RViz["RViz (3D Nav Goal)"]:::external

    %% Planner Layer
    subgraph "Planner Layer"
        direction TB
        PM["plan_manage\n(ego_planner_node, FSM)"]:::planning
        PS["path_searching\n(D*/dyn A*)"]:::planning
        BP["bezier_predict\n(target motion prediction)"]:::planning
        BS["bspline_opt\n(trajectory optimization)"]:::planning
        PE["plan_env\n(grid map, raycasting)"]:::planning
        DD["drone_detect\n(target detection)"]:::planning
    end

    %% Control Layer
    subgraph "Control Layer"
        direction TB
        SC["so3_control\n(SO(3) controller)"]:::control
        FD["fake_drone\n(odom emulator)"]:::control
    end

    %% Simulation & Sensing Layer
    subgraph "Simulation & Sensing"
        direction TB
        SQ["so3_quadrotor_simulator\n(physics engine)"]:::simulation
        LS["local_sensing\n(depth/pointcloud)"]:::simulation
        MG["map_generator"]:::simulation
        MA["mockamap"]:::simulation
        MMS["multi_map_server"]:::simulation
    end

    %% Utilities & Bridges
    subgraph "Utilities & Bridges"
        direction TB
        TU["traj_utils\n(shared msgs & viz)"]:::utils
        QM["quadrotor_msgs"]:::utils
        RTB["rosmsg_tcp_bridge"]:::utils
        RVP["rviz_plugins"]:::utils
        OV["odom_visualization"]:::utils
        PU["pose_utils"]:::utils
        WG["waypoint_generator"]:::utils
    end

    %% Data Flows
    RViz -->|"3D Nav Goal topic"| PM
    PM -->|"/plan_search (svc)"| PS
    PM -->|"/predict (svc)"| BP
    PM -->|"/optimize (svc)"| BS
    PM -->|"trajectory (Bspline.msg)"| SC
    DD -->|"target pose (PoseStamped)"| PM
    SC -->|"motor cmd topic"| SQ
    SQ -->|"Odometry.msg"| PE
    SQ -->|"Odometry.msg"| SC
    LS -->|"PointCloud2"| PE
    PE -->|"occupancy grid topic"| PM
    PE -->|"occupancy grid topic"| BP
    PE -->|"occupancy grid topic"| BS
    TU -->|"/traj msgs"| PM
    RTB -->|"bridge topics"| PM

    %% Feedback Loop
    SQ --> LS
    LS --> PE
    PE --> PM
    PM --> SQ

    %% Click Events
    click PM "https://github.com/zju-fast-lab/visplanner/tree/main/src/planner/plan_manage"
    click BP "https://github.com/zju-fast-lab/visplanner/tree/main/src/planner/bezier_predict"
    click BS "https://github.com/zju-fast-lab/visplanner/tree/main/src/planner/bspline_opt"
    click PS "https://github.com/zju-fast-lab/visplanner/tree/main/src/planner/path_searching"
    click PE "https://github.com/zju-fast-lab/visplanner/tree/main/src/planner/plan_env"
    click DD "https://github.com/zju-fast-lab/visplanner/tree/main/src/planner/drone_detect"
    click TU "https://github.com/zju-fast-lab/visplanner/tree/main/src/planner/traj_utils"
    click RTB "https://github.com/zju-fast-lab/visplanner/tree/main/src/planner/rosmsg_tcp_bridge"
    click SQ "https://github.com/zju-fast-lab/visplanner/tree/main/src/uav_simulator/so3_quadrotor_simulator"
    click SC "https://github.com/zju-fast-lab/visplanner/tree/main/src/uav_simulator/so3_control"
    click FD "https://github.com/zju-fast-lab/visplanner/tree/main/src/uav_simulator/fake_drone"
    click LS "https://github.com/zju-fast-lab/visplanner/tree/main/src/uav_simulator/local_sensing"
    click MG "https://github.com/zju-fast-lab/visplanner/tree/main/src/uav_simulator/map_generator"
    click MA "https://github.com/zju-fast-lab/visplanner/tree/main/src/uav_simulator/mockamap"
    click MMS "https://github.com/zju-fast-lab/visplanner/tree/main/src/uav_simulator/Utils/multi_map_server"
    click OV "https://github.com/zju-fast-lab/visplanner/tree/main/src/uav_simulator/Utils/odom_visualization"
    click PU "https://github.com/zju-fast-lab/visplanner/tree/main/src/uav_simulator/Utils/pose_utils"
    click RVP "https://github.com/zju-fast-lab/visplanner/tree/main/src/uav_simulator/Utils/rviz_plugins"
    click QM "https://github.com/zju-fast-lab/visplanner/tree/main/src/uav_simulator/Utils/quadrotor_msgs"
    click WG "https://github.com/zju-fast-lab/visplanner/tree/main/src/uav_simulator/Utils/waypoint_generator"

    %% Styles
    classDef planning fill:#ADD8E6,stroke:#000
    classDef simulation fill:#90EE90,stroke:#000
    classDef control fill:#FFA500,stroke:#000
    classDef utils fill:#D3D3D3,stroke:#000
    classDef external fill:#F0E68C,stroke:#000,stroke-dasharray: 5 5
```
