# zju-fast-lab/dftpav architecture

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

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

## Overview

##### Project Type and Purpose
- This is a full-stack, ROS-based spatial-temporal trajectory planning system for car-like robots.

##### High-Level Components
a. User Interface & Orchestration
- RViz (2D Nav Goal)
- run.sh / ROS launch files
- ROS Master (topics/services registry)
b. Perception & Map Management
- semantic_map_manager (loads lane networks, traffic signals via JSON, nanoflann, ray casting)
- vehicle_msgs (custom ROS message definitions for map, obstacles, state)
c. Route & Behavior Planning
- route_planner (global path through waypoints)
- behavior_planner (decides lane changes, speed profiles using IDM, MOBIL)
d. Trajectory Planning Core
- traj_planner (MinCo-based optimizer)
- External planners:
– ssc_planner (Space-State Corridor planner)
– eudm_planner (Euclidean Distance Minimization)
- Config via protobuf (.proto + .pb.txt)
- CorridorBuilder2d, kino_astar for initial guess
- traj_server_ros (node wrapper publishing PolyTraj msg)
e. Vehicle Model & Simulation
- vehicle_model (kinematic/dynamic models, ODEINT integration)
- phy_simulator (renders physics, ROS adapter, rviz)
- forward_simulator & motion_predictor (fast multi-modal predictor)
- aux_tools (terminal server, scripts)
f. Utilities & Toolchain
- DecompROS (decomposition utilities)
- catkin_simple (build helper)
- QGIS projects (GeoJSON & shapefiles)
- Third-party libs: ODEINT (numerical integration), OOQP/NLOPT (QP solver), Google Glog, Protocol Buffers

##### Relationships & Data Flow
1. User sets 2D Nav Goal in RViz → publishes to `/move_base_simple/goal`.
2. semantic_map_manager subscribes to map topics, publishes road network & obstacle sets.
3. route_planner subscribes to map + goal → publishes a global path.
4. behavior_planner consumes global path + dynamic obstacles → outputs a lane-speed decision.
5. traj_planner (and optional ssc/eudm planners) takes behavior plan + map → optimizes spatial-temporal trajectory → publishes PolyTraj msg.
6. vehicle_msgs encodes trajectory & control signals → vehicle_model simulates dynamics → phy_simulator visualizes and may publish updated state/obstacles back on topics.
7. Loop continues until goal reached.

##### Architectural Patterns & Principles
- Layered / pipeline architecture: Perception → Global Planning → Behavior → Local Trajectory → Execution/Simulation
- Publish–Subscribe (ROS topics) decouples components
- Modular plugin style: each planner (ssc, eudm, kino_astar) is a drop-in module under `Sim/util` or `src/Plan`
- Config-driven: protobufs for parameter sets, JSON for map data
- Separation of concerns: visualization separated (traj_visualizer, phy_simulator/rviz), core logic in C++ libraries

##### Technologies & Frameworks
- ROS (communication, launch, catkin)
- CMake / catkin_simple
- Protocol Buffers (.proto → config)
- Eigen, Boost.ODEINT, Glog, OOQP, NLOPT
- nanoflann, roguelike_ray_casting for spatial indexing
- RViz for visualization, QGIS for map pre-processing

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User/UI Layer
    subgraph "User/UI Layer"
        direction TB
        RViz["RViz (2D Nav Goal)"]:::ui
        RunSH["run.sh"]:::ui
        LaunchInt["Planning Launch Files"]:::ui
        LaunchSim["Physics Simulation Launch Files"]:::ui
    end

    %% Perception & Map Layer
    subgraph "Perception & Map Layer"
        direction TB
        SMM["semantic_map_manager"]:::perception
        nanoflann["nanoflann"]:::thirdparty
        raycast["roguelike_ray_casting"]:::thirdparty
        Msgs["vehicle_msgs"]:::data
    end

    %% Planning Layer
    subgraph "Planning Layer"
        direction TB

        subgraph "Global Planning"
            RP["route_planner"]:::planning
        end
        subgraph "Behavior Planning"
            BP["behavior_planner"]:::planning
        end
        subgraph "Local Trajectory Planning"
            TP["traj_planner"]:::trajectory
            SSC["ssc_planner"]:::trajectory
            EUDM["eudm_planner"]:::trajectory
            MinCoCfg["minco_config.pb.txt"]:::data
            SSCfg["ssc_config.pb.txt"]:::data
            EUDMCfg["eudm_config.pb.txt"]:::data
            KinoAstar["kino_astar.h"]:::data
            Corridor2d["CorridorBuilder2d.hpp"]:::data
            TrajServer["traj_server_ros.h"]:::data
        end
    end

    %% Execution & Simulation Layer
    subgraph "Execution & Simulation Layer"
        direction TB
        VM["vehicle_model"]:::execution
        PS["phy_simulator"]:::execution
        FS["forward_simulator"]:::execution
        MP["motion_predictor"]:::execution
        Aux["aux_tools"]:::util
    end

    %% Utilities & Toolchain
    subgraph "Utilities & Toolchain"
        direction TB
        Decomp["DecompROS"]:::util
        Catkin["catkin_simple"]:::util
        QGIS["qgis_projects"]:::util
    end

    %% Data Flows
    RViz -->|"/move_base_simple/goal"| SMM
    SMM -->|"road network & obstacles"| RP
    RP -->|"global_path"| BP
    BP -->|"behavior_plan"| TP
    TP -->|"PolyTraj msg"| VM
    VM -->|"ControlSignal"| PS
    PS -->|"updated_state/obstacles"| SMM

    %% Optional planners
    BP --> TP
    TP --> SSC
    TP --> EUDM

    %% Click Events
    click RunSH "https://github.com/zju-fast-lab/dftpav/blob/main/run.sh"
    click LaunchInt "https://github.com/zju-fast-lab/dftpav/tree/main/src/Sim/app/planning_integrated/launch"
    click LaunchSim "https://github.com/zju-fast-lab/dftpav/tree/main/src/Sim/core/phy_simulator/launch"
    click SMM "https://github.com/zju-fast-lab/dftpav/tree/main/src/Sim/core/semantic_map_manager"
    click nanoflann "https://github.com/zju-fast-lab/dftpav/tree/main/src/Sim/core/semantic_map_manager/thirdparty/nanoflann"
    click raycast "https://github.com/zju-fast-lab/dftpav/tree/main/src/Sim/core/semantic_map_manager/thirdparty/roguelike_ray_casting"
    click Msgs "https://github.com/zju-fast-lab/dftpav/tree/main/src/Sim/core/vehicle_msgs"
    click RP "https://github.com/zju-fast-lab/dftpav/tree/main/src/Sim/core/route_planner"
    click BP "https://github.com/zju-fast-lab/dftpav/tree/main/src/Sim/core/behavior_planner"
    click TP "https://github.com/zju-fast-lab/dftpav/tree/main/src/Plan/traj_planner"
    click MinCoCfg "https://github.com/zju-fast-lab/dftpav/blob/main/src/Plan/traj_planner/config/minco_config.pb.txt"
    click KinoAstar "https://github.com/zju-fast-lab/dftpav/blob/main/src/Plan/traj_planner/include/path_searching/kino_astar.h"
    click Corridor2d "https://github.com/zju-fast-lab/dftpav/blob/main/src/Plan/traj_planner/include/plan_utils/CorridorBuilder2d.hpp"
    click TrajServer "https://github.com/zju-fast-lab/dftpav/blob/main/src/Plan/traj_planner/include/plan_utils/traj_server_ros.h"
    click SSC "https://github.com/zju-fast-lab/dftpav/tree/main/src/Sim/util/ssc_planner"
    click SSCfg "https://github.com/zju-fast-lab/dftpav/blob/main/src/Sim/util/ssc_planner/config/ssc_config.pb.txt"
    click EUDM "https://github.com/zju-fast-lab/dftpav/tree/main/src/Sim/util/eudm_planner"
    click EUDMCfg "https://github.com/zju-fast-lab/dftpav/blob/main/src/Sim/util/eudm_planner/config/eudm_config.pb.txt"
    click VM "https://github.com/zju-fast-lab/dftpav/tree/main/src/Sim/core/vehicle_model"
    click PS "https://github.com/zju-fast-lab/dftpav/tree/main/src/Sim/core/phy_simulator"
    click FS "https://github.com/zju-fast-lab/dftpav/tree/main/src/Sim/core/forward_simulator"
    click MP "https://github.com/zju-fast-lab/dftpav/tree/main/src/Sim/core/motion_predictor"
    click Aux "https://github.com/zju-fast-lab/dftpav/tree/main/src/Sim/aux_tools"
    click Decomp "https://github.com/zju-fast-lab/dftpav/tree/main/src/Plan/utils/DecompROS"
    click Catkin "https://github.com/zju-fast-lab/dftpav/tree/main/src/Plan/utils/catkin_simple"
    click QGIS "https://github.com/zju-fast-lab/dftpav/tree/main/src/Sim/toolchain/qgis_projects"

    %% Styles
    classDef ui fill:#CFE2F3,stroke:#333,stroke-width:1px
    classDef perception fill:#D9EAD3,stroke:#333,stroke-width:1px
    classDef planning fill:#FFF2CC,stroke:#333,stroke-width:1px
    classDef trajectory fill:#F4CCCC,stroke:#333,stroke-width:1px
    classDef execution fill:#FCE5CD,stroke:#333,stroke-width:1px
    classDef util fill:#EAD1DC,stroke:#333,stroke-width:1px
    classDef data fill:#C9DAF8,stroke:#333,stroke-width:1px
    classDef thirdparty fill:#EAD1DC,stroke:#333,stroke-width:1px
```
