# hkust-aerial-robotics/fuel architecture

> Architecture diagram of the GitHub repository hkust-aerial-robotics/fuel, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hkust-aerial-robotics/fuel
- Repository: https://github.com/hkust-aerial-robotics/fuel

## Overview

FUEL is a ROS-based UAV exploration framework. The principal workflow starts when an operator triggers exploration: the system incrementally updates a frontier information structure from the online map, plans frontier coverage, refines viewpoints, and generates trajectories for the vehicle. The repository also contains map/sensor simulation and trajectory optimization components. The README documents the high-level planning sequence; the available source excerpts do not establish every internal call, so unsampled implementation links are omitted.

Main entry points: [`fuel_planner/exploration_manager/src/fast_exploration_manager.cpp`](https://github.com/hkust-aerial-robotics/fuel/blob/main/fuel_planner/exploration_manager/src/fast_exploration_manager.cpp) (Coverage planning), [`fuel_planner/plan_manage/src/planner_manager.cpp`](https://github.com/hkust-aerial-robotics/fuel/blob/main/fuel_planner/plan_manage/src/planner_manager.cpp) (Trajectory planning), [`fuel_planner/exploration_manager/src/fast_exploration_fsm.cpp`](https://github.com/hkust-aerial-robotics/fuel/blob/main/fuel_planner/exploration_manager/src/fast_exploration_fsm.cpp) (Exploration control), [`fuel_planner/bspline_opt/src/bspline_optimizer.cpp`](https://github.com/hkust-aerial-robotics/fuel/blob/main/fuel_planner/bspline_opt/src/bspline_optimizer.cpp) (B-spline optimizer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_mapping["Mapping and perception"]
  node_map_ros["Map ingestion<br/>[map_ros.cpp]"]
  node_sdf[("SDF map<br/>[sdf_map.cpp]")]
  node_frontiers["Frontier structure"]
end

subgraph group_exploration["Exploration planning"]
  node_explore_fsm["Exploration control"]
  node_explore_manager["Coverage planning"]
  node_heading["Viewpoint refinement"]
  node_graph_search["Coverage search<br/>[graph_search.h]"]
  node_tsp["Tour solver<br/>[lkh_interface.cpp]"]
  node_path_search["Path search"]
end

subgraph group_trajectory["Trajectory generation"]
  node_planner_manager["Trajectory planning"]
  node_optimizer["B-spline optimizer"]
  node_bspline["B-spline representation"]
  node_polytraj["Polynomial trajectories"]
  node_traj_server["Trajectory execution<br/>[traj_server.cpp]"]
  node_visualization["Planning visualization"]
end

subgraph group_simulation["Simulation and vehicle"]
  node_map_sim["Map source<br/>[map_publisher.cpp]"]
  node_sensor["Local sensing"]
  node_quad_sim["Quadrotor dynamics<br/>[Quadrotor.cpp]"]
  node_control["SO3 control<br/>[SO3Control.cpp]"]
  node_position_command["Position command<br/>[PositionCommand.h]"]
end

node_operator(("Operator"))

node_operator -->|"starts exploration"| node_explore_fsm
node_map_sim -.->|"supplies environment"| node_sensor
node_sensor -.->|"provides observations"| node_map_ros
node_map_ros -->|"updates map"| node_sdf
node_sdf -->|"informs frontier search"| node_frontiers
node_explore_fsm -->|"requests coverage plan"| node_explore_manager
node_explore_manager -->|"uses frontier structure"| node_frontiers
node_explore_manager -->|"plans coverage paths"| node_graph_search
node_explore_manager -.->|"orders coverage"| node_tsp
node_explore_manager -->|"refines viewpoints"| node_heading
node_explore_manager -->|"requests trajectories"| node_planner_manager
node_planner_manager -.->|"searches paths"| node_path_search
node_planner_manager -.->|"optimizes trajectory"| node_optimizer
node_optimizer -->|"queries distances"| node_sdf
node_optimizer -.->|"optimizes spline"| node_bspline
node_planner_manager -.->|"generates trajectory"| node_polytraj
node_planner_manager -.->|"provides trajectory"| node_traj_server
node_traj_server -.->|"publishes commands"| node_position_command
node_position_command -.->|"drives vehicle"| node_quad_sim
node_quad_sim -.->|"models controlled vehicle"| node_control
node_explore_fsm -.->|"displays plans"| node_visualization

click node_map_sim "https://github.com/hkust-aerial-robotics/fuel/blob/main/uav_simulator/map_generator/src/map_publisher.cpp"
click node_sensor "https://github.com/hkust-aerial-robotics/fuel/blob/main/uav_simulator/local_sensing/src/depth_render_node.cpp"
click node_map_ros "https://github.com/hkust-aerial-robotics/fuel/blob/main/fuel_planner/plan_env/src/map_ros.cpp"
click node_sdf "https://github.com/hkust-aerial-robotics/fuel/blob/main/fuel_planner/plan_env/src/sdf_map.cpp"
click node_frontiers "https://github.com/hkust-aerial-robotics/fuel/blob/main/fuel_planner/active_perception/src/frontier_finder.cpp"
click node_explore_fsm "https://github.com/hkust-aerial-robotics/fuel/blob/main/fuel_planner/exploration_manager/src/fast_exploration_fsm.cpp"
click node_explore_manager "https://github.com/hkust-aerial-robotics/fuel/blob/main/fuel_planner/exploration_manager/src/fast_exploration_manager.cpp"
click node_heading "https://github.com/hkust-aerial-robotics/fuel/blob/main/fuel_planner/active_perception/src/heading_planner.cpp"
click node_graph_search "https://github.com/hkust-aerial-robotics/fuel/blob/main/fuel_planner/active_perception/include/active_perception/graph_search.h"
click node_tsp "https://github.com/hkust-aerial-robotics/fuel/blob/main/fuel_planner/utils/lkh_tsp_solver/src/lkh_interface.cpp"
click node_path_search "https://github.com/hkust-aerial-robotics/fuel/blob/main/fuel_planner/path_searching/src/kinodynamic_astar.cpp"
click node_planner_manager "https://github.com/hkust-aerial-robotics/fuel/blob/main/fuel_planner/plan_manage/src/planner_manager.cpp"
click node_optimizer "https://github.com/hkust-aerial-robotics/fuel/blob/main/fuel_planner/bspline_opt/src/bspline_optimizer.cpp"
click node_bspline "https://github.com/hkust-aerial-robotics/fuel/blob/main/fuel_planner/bspline/src/non_uniform_bspline.cpp"
click node_polytraj "https://github.com/hkust-aerial-robotics/fuel/blob/main/fuel_planner/poly_traj/src/polynomial_traj.cpp"
click node_traj_server "https://github.com/hkust-aerial-robotics/fuel/blob/main/fuel_planner/plan_manage/src/traj_server.cpp"
click node_visualization "https://github.com/hkust-aerial-robotics/fuel/blob/main/fuel_planner/traj_utils/src/planning_visualization.cpp"
click node_quad_sim "https://github.com/hkust-aerial-robotics/fuel/blob/main/uav_simulator/so3_quadrotor_simulator/src/dynamics/Quadrotor.cpp"
click node_control "https://github.com/hkust-aerial-robotics/fuel/blob/main/uav_simulator/so3_control/src/SO3Control.cpp"
click node_position_command "https://github.com/hkust-aerial-robotics/fuel/blob/main/uav_simulator/Utils/multi_map_server/quadrotor_msgs/msg_gen/cpp/include/quadrotor_msgs/PositionCommand.h"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_map_ros,node_sdf,node_frontiers toneBlue
class node_explore_fsm,node_explore_manager,node_heading,node_graph_search,node_tsp,node_path_search toneAmber
class node_planner_manager,node_optimizer,node_bspline,node_polytraj,node_traj_server,node_visualization toneMint
class node_map_sim,node_sensor,node_quad_sim,node_control,node_position_command toneRose
class node_operator toneIndigo
```

## Components

### Mapping and perception

- [Map ingestion](https://github.com/hkust-aerial-robotics/fuel/blob/main/fuel_planner/plan_env/src/map_ros.cpp): `fuel_planner/plan_env/src/map_ros.cpp`
- [SDF map](https://github.com/hkust-aerial-robotics/fuel/blob/main/fuel_planner/plan_env/src/sdf_map.cpp): `fuel_planner/plan_env/src/sdf_map.cpp`
- [Frontier structure](https://github.com/hkust-aerial-robotics/fuel/blob/main/fuel_planner/active_perception/src/frontier_finder.cpp): `fuel_planner/active_perception/src/frontier_finder.cpp`

### Exploration planning

- [Exploration control](https://github.com/hkust-aerial-robotics/fuel/blob/main/fuel_planner/exploration_manager/src/fast_exploration_fsm.cpp): `fuel_planner/exploration_manager/src/fast_exploration_fsm.cpp`
- [Coverage planning](https://github.com/hkust-aerial-robotics/fuel/blob/main/fuel_planner/exploration_manager/src/fast_exploration_manager.cpp): `fuel_planner/exploration_manager/src/fast_exploration_manager.cpp`
- [Viewpoint refinement](https://github.com/hkust-aerial-robotics/fuel/blob/main/fuel_planner/active_perception/src/heading_planner.cpp): `fuel_planner/active_perception/src/heading_planner.cpp`
- [Coverage search](https://github.com/hkust-aerial-robotics/fuel/blob/main/fuel_planner/active_perception/include/active_perception/graph_search.h): `fuel_planner/active_perception/include/active_perception/graph_search.h`
- [Tour solver](https://github.com/hkust-aerial-robotics/fuel/blob/main/fuel_planner/utils/lkh_tsp_solver/src/lkh_interface.cpp): `fuel_planner/utils/lkh_tsp_solver/src/lkh_interface.cpp`
- [Path search](https://github.com/hkust-aerial-robotics/fuel/blob/main/fuel_planner/path_searching/src/kinodynamic_astar.cpp): `fuel_planner/path_searching/src/kinodynamic_astar.cpp`

### Trajectory generation

- [Trajectory planning](https://github.com/hkust-aerial-robotics/fuel/blob/main/fuel_planner/plan_manage/src/planner_manager.cpp): `fuel_planner/plan_manage/src/planner_manager.cpp`
- [B-spline optimizer](https://github.com/hkust-aerial-robotics/fuel/blob/main/fuel_planner/bspline_opt/src/bspline_optimizer.cpp): `fuel_planner/bspline_opt/src/bspline_optimizer.cpp`
- [B-spline representation](https://github.com/hkust-aerial-robotics/fuel/blob/main/fuel_planner/bspline/src/non_uniform_bspline.cpp): `fuel_planner/bspline/src/non_uniform_bspline.cpp`
- [Polynomial trajectories](https://github.com/hkust-aerial-robotics/fuel/blob/main/fuel_planner/poly_traj/src/polynomial_traj.cpp): `fuel_planner/poly_traj/src/polynomial_traj.cpp`
- [Trajectory execution](https://github.com/hkust-aerial-robotics/fuel/blob/main/fuel_planner/plan_manage/src/traj_server.cpp): `fuel_planner/plan_manage/src/traj_server.cpp`
- [Planning visualization](https://github.com/hkust-aerial-robotics/fuel/blob/main/fuel_planner/traj_utils/src/planning_visualization.cpp): `fuel_planner/traj_utils/src/planning_visualization.cpp`

### Simulation and vehicle

- [Map source](https://github.com/hkust-aerial-robotics/fuel/blob/main/uav_simulator/map_generator/src/map_publisher.cpp): `uav_simulator/map_generator/src/map_publisher.cpp`
- [Local sensing](https://github.com/hkust-aerial-robotics/fuel/blob/main/uav_simulator/local_sensing/src/depth_render_node.cpp): `uav_simulator/local_sensing/src/depth_render_node.cpp`
- [Quadrotor dynamics](https://github.com/hkust-aerial-robotics/fuel/blob/main/uav_simulator/so3_quadrotor_simulator/src/dynamics/Quadrotor.cpp): `uav_simulator/so3_quadrotor_simulator/src/dynamics/Quadrotor.cpp`
- [SO3 control](https://github.com/hkust-aerial-robotics/fuel/blob/main/uav_simulator/so3_control/src/SO3Control.cpp): `uav_simulator/so3_control/src/SO3Control.cpp`
- [Position command](https://github.com/hkust-aerial-robotics/fuel/blob/main/uav_simulator/Utils/multi_map_server/quadrotor_msgs/msg_gen/cpp/include/quadrotor_msgs/PositionCommand.h): `uav_simulator/Utils/multi_map_server/quadrotor_msgs/msg_gen/cpp/include/quadrotor_msgs/PositionCommand.h`

### Other components

- **Operator**

## Connections

- Operator → Exploration control: starts exploration
- Map source → Local sensing: supplies environment
- Local sensing → Map ingestion: provides observations
- Map ingestion → SDF map: updates map (evidence: `fuel_planner/plan_env/src/sdf_map.cpp`)
- SDF map → Frontier structure: informs frontier search
- Exploration control → Coverage planning: requests coverage plan
- Coverage planning → Frontier structure: uses frontier structure
- Coverage planning → Coverage search: plans coverage paths
- Coverage planning → Tour solver: orders coverage
- Coverage planning → Viewpoint refinement: refines viewpoints
- Coverage planning → Trajectory planning: requests trajectories
- Trajectory planning → Path search: searches paths
- Trajectory planning → B-spline optimizer: optimizes trajectory
- B-spline optimizer → SDF map: queries distances (evidence: `fuel_planner/bspline_opt/src/bspline_optimizer.cpp`)
- B-spline optimizer → B-spline representation: optimizes spline
- Trajectory planning → Polynomial trajectories: generates trajectory
- Trajectory planning → Trajectory execution: provides trajectory
- Trajectory execution → Position command: publishes commands
- Position command → Quadrotor dynamics: drives vehicle
- Quadrotor dynamics → SO3 control: models controlled vehicle
- Exploration control → Planning visualization: displays plans
