# hku-mars/fast-livo2 architecture

> Architecture diagram of the GitHub repository hku-mars/fast-livo2, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hku-mars/fast-livo2
- Repository: https://github.com/hku-mars/fast-livo2

## Overview

#### Purpose and Runtime
FAST-LIVO2 is a ROS/catkin C++ package for real-time tightly coupled LiDAR–IMU–camera odometry and 3D mapping. It targets Ubuntu 18.04–20.04 and processes synchronized ROS bag/live sensor streams. Build/package metadata: `CMakeLists.txt`, `package.xml`.

#### Entry Points and ROS Integration
The executable begins in `src/main.cpp`, which establishes ROS publishers/subscribers and drives the mapping pipeline. Dataset/sensor-specific launch entry points select parameters, topics, and visualization:
- `launch/mapping_avia.launch`
- `launch/mapping_ouster_ntu.launch`
- `launch/mapping_hesaixt32_hilti22.launch`

Runtime calibration and sensor settings are supplied through YAML files such as `config/avia.yaml`, `config/NTU_VIRAL.yaml`, and camera-specific files under `config/`.

#### Sensor Ingestion and Preprocessing
LiDAR messages are normalized into internal point representations and filtered/prepared before estimation. This boundary accommodates LiDAR-specific formats, including Livox custom ROS messages:
- `src/preprocess.cpp`
- `include/preprocess.h`
- `include/livox_ros_driver/CustomMsg.h`

IMU samples are accumulated and propagated to provide motion prediction and deskewing support:
- `src/IMU_Processing.cpp`
- `include/IMU_Processing.h`

#### Core Mapping and State Estimation
`LIVMapper` is the central orchestration component: it consumes prepared LiDAR, IMU propagation, visual observations, and map state; then performs localization/mapping updates and publishes results.
- `src/LIVMapper.cpp`
- `include/LIVMapper.h`
- `src/main.cpp`

The estimator’s geometric and state representations are organized around frames, visual points, and shared Lie-group/math types:
- `src/frame.cpp`
- `src/visual_point.cpp`
- `include/utils/so3_math.h`

#### Visual Odometry Path
The visual subsystem performs direct/sparse visual tracking and fusion against the LiDAR-inertial prediction rather than operating as an isolated frontend. Camera model and intrinsics/extrinsics are externalized in calibration YAMLs:
- `src/vio.cpp`
- `include/vio.h`
- `include/feature.h`

Relevant camera configurations include `config/camera_MARS_LVIG.yaml`, `config/camera_NTU_VIRAL.yaml`, and `config/camera_fisheye_HILTI22.yaml`.

#### Spatial Map Representation
The persistent local map is voxel-based, providing the geometry queried by scan-to-map/state optimization and updated from registered LiDAR observations:
- `src/voxel_map.cpp`
- `include/voxel_map.h`
- `include/common_lib.h`

The principal flow is: ROS LiDAR/IMU/image callbacks → LiDAR preprocessing and IMU propagation → LiDAR-inertial-visual optimization in `LIVMapper`/VIO → voxel-map update → ROS pose, point-cloud, and visualization outputs.

#### Dependencies and External Boundaries
Core native dependencies are ROS, PCL, Eigen, OpenCV, Sophus, and Vikit; Vikit supplies camera models and visual math. LiDAR-camera extrinsics are expected from calibration, with FAST-Calib recommended externally. COLMAP artifacts under `Log/Colmap/` and result/evaluation material under `Log/result/` are offline experiment assets, not the online odometry control path.

Main entry points: [`src/LIVMapper.cpp`](https://github.com/hku-mars/fast-livo2/blob/main/src/LIVMapper.cpp) (LIVMapper), [`src/main.cpp`](https://github.com/hku-mars/fast-livo2/blob/main/src/main.cpp) (ROS pipeline entry), [`src/vio.cpp`](https://github.com/hku-mars/fast-livo2/blob/main/src/vio.cpp) (Visual tracking & fusion), [`src/preprocess.cpp`](https://github.com/hku-mars/fast-livo2/blob/main/src/preprocess.cpp) (LiDAR preprocessing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ros["ROS Runtime"]
  node_package["Catkin package<br/>build metadata<br/>[CMakeLists.txt]"]
  node_main["ROS pipeline entry<br/>C++ executable<br/>[main.cpp]"]
  node_sensor_streams["LiDAR, IMU &amp; images<br/>ROS sensor topics"]
  node_preprocess["LiDAR preprocessing<br/>point normalization<br/>[preprocess.cpp]"]
  node_livox_msg["Livox custom messages<br/>ROS message boundary<br/>[CustomMsg.h]"]
  node_ros_outputs["Pose, cloud &amp; visualization<br/>ROS publishers"]
end

subgraph group_estimation["Estimation &amp; Mapping"]
  node_imu["IMU propagation<br/>motion prediction<br/>[IMU_Processing.cpp]"]
  node_mapper["LIVMapper<br/>mapping orchestrator<br/>[LIVMapper.cpp]"]
  node_vio["Visual tracking &amp; fusion<br/>direct sparse VIO<br/>[vio.cpp]"]
  node_state_geometry["Frames &amp; visual state<br/>estimator representations<br/>[frame.cpp]"]
  node_voxel_map[("Voxel local map<br/>spatial map<br/>[voxel_map.cpp]")]
end

subgraph group_configuration["Launch &amp; Calibration"]
  node_launch["Dataset launch profiles<br/>ROS launch"]
  node_calibration["Sensor calibration<br/>YAML configuration<br/>[avia.yaml]"]
end

node_native_deps{{"Native vision &amp; geometry libs<br/>external dependencies<br/>[package.xml]"}}

node_package -->|"builds"| node_main
node_launch -->|"starts"| node_main
node_calibration -->|"parameterizes"| node_launch
node_sensor_streams -->|"callbacks"| node_main
node_livox_msg -->|"decoded by"| node_preprocess
node_main -->|"LiDAR input"| node_preprocess
node_main -->|"IMU input"| node_imu
node_main -->|"image input"| node_vio
node_preprocess -->|"prepared scan"| node_mapper
node_imu -->|"predicted motion"| node_mapper
node_vio -->|"visual constraints"| node_mapper
node_state_geometry -->|"visual state"| node_vio
node_state_geometry -->|"state math"| node_mapper
node_voxel_map -->|"map queries"| node_mapper
node_mapper -->|"registered updates"| node_voxel_map
node_mapper -->|"publishes"| node_ros_outputs
node_calibration -->|"camera model"| node_vio
node_native_deps -.->|"geometry runtime"| node_mapper
node_native_deps -.->|"vision runtime"| node_vio

click node_package "https://github.com/hku-mars/fast-livo2/blob/main/CMakeLists.txt"
click node_launch "https://github.com/hku-mars/fast-livo2/blob/main/launch/mapping_avia.launch"
click node_calibration "https://github.com/hku-mars/fast-livo2/blob/main/config/avia.yaml"
click node_main "https://github.com/hku-mars/fast-livo2/blob/main/src/main.cpp"
click node_preprocess "https://github.com/hku-mars/fast-livo2/blob/main/src/preprocess.cpp"
click node_livox_msg "https://github.com/hku-mars/fast-livo2/blob/main/include/livox_ros_driver/CustomMsg.h"
click node_imu "https://github.com/hku-mars/fast-livo2/blob/main/src/IMU_Processing.cpp"
click node_mapper "https://github.com/hku-mars/fast-livo2/blob/main/src/LIVMapper.cpp"
click node_vio "https://github.com/hku-mars/fast-livo2/blob/main/src/vio.cpp"
click node_state_geometry "https://github.com/hku-mars/fast-livo2/blob/main/src/frame.cpp"
click node_voxel_map "https://github.com/hku-mars/fast-livo2/blob/main/src/voxel_map.cpp"
click node_native_deps "https://github.com/hku-mars/fast-livo2/blob/main/package.xml"

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_package,node_main,node_sensor_streams,node_preprocess,node_livox_msg,node_ros_outputs toneBlue
class node_imu,node_mapper,node_vio,node_state_geometry,node_voxel_map toneAmber
class node_launch,node_calibration toneMint
class node_native_deps toneNeutral
```

## Components

### ROS Runtime

- [Catkin package](https://github.com/hku-mars/fast-livo2/blob/main/CMakeLists.txt): build metadata · Defines the ROS C++ package and native dependencies. · `CMakeLists.txt`
- [ROS pipeline entry](https://github.com/hku-mars/fast-livo2/blob/main/src/main.cpp): C++ executable · Registers callbacks and drives mapping. · `src/main.cpp`
- **LiDAR, IMU & images**: ROS sensor topics
- [LiDAR preprocessing](https://github.com/hku-mars/fast-livo2/blob/main/src/preprocess.cpp): point normalization · Converts LiDAR formats into filtered internal points. · `src/preprocess.cpp`
- [Livox custom messages](https://github.com/hku-mars/fast-livo2/blob/main/include/livox_ros_driver/CustomMsg.h): ROS message boundary · `include/livox_ros_driver/CustomMsg.h`
- **Pose, cloud & visualization**: ROS publishers

### Estimation & Mapping

- [IMU propagation](https://github.com/hku-mars/fast-livo2/blob/main/src/IMU_Processing.cpp): motion prediction · Accumulates IMU data for prediction and deskewing. · `src/IMU_Processing.cpp`
- [LIVMapper](https://github.com/hku-mars/fast-livo2/blob/main/src/LIVMapper.cpp): mapping orchestrator · Fuses prepared sensor observations, state, and map updates. · `src/LIVMapper.cpp`
- [Visual tracking & fusion](https://github.com/hku-mars/fast-livo2/blob/main/src/vio.cpp): direct sparse VIO · Tracks visual observations against LiDAR-inertial prediction. · `src/vio.cpp`
- [Frames & visual state](https://github.com/hku-mars/fast-livo2/blob/main/src/frame.cpp): estimator representations · Frames, visual points, and Lie-group state math. · `src/frame.cpp`
- [Voxel local map](https://github.com/hku-mars/fast-livo2/blob/main/src/voxel_map.cpp): spatial map · Persistent geometry for registration queries and updates. · `src/voxel_map.cpp`

### Launch & Calibration

- [Dataset launch profiles](https://github.com/hku-mars/fast-livo2/blob/main/launch/mapping_avia.launch): ROS launch · Select sensor topics, parameters, and visualization setup. · `launch/mapping_avia.launch`
- [Sensor calibration](https://github.com/hku-mars/fast-livo2/blob/main/config/avia.yaml): YAML configuration · Supplies sensor settings and camera intrinsics/extrinsics. · `config/avia.yaml`

### Other components

- [Native vision & geometry libs](https://github.com/hku-mars/fast-livo2/blob/main/package.xml): external dependencies · ROS, PCL, Eigen, OpenCV, Sophus, and Vikit. · `package.xml`

## Connections

- Catkin package → ROS pipeline entry: builds
- Dataset launch profiles → ROS pipeline entry: starts
- Sensor calibration → Dataset launch profiles: parameterizes
- LiDAR, IMU & images → ROS pipeline entry: callbacks
- Livox custom messages → LiDAR preprocessing: decoded by
- ROS pipeline entry → LiDAR preprocessing: LiDAR input
- ROS pipeline entry → IMU propagation: IMU input
- ROS pipeline entry → Visual tracking & fusion: image input
- LiDAR preprocessing → LIVMapper: prepared scan
- IMU propagation → LIVMapper: predicted motion
- Visual tracking & fusion → LIVMapper: visual constraints
- Frames & visual state → Visual tracking & fusion: visual state
- Frames & visual state → LIVMapper: state math
- Voxel local map → LIVMapper: map queries
- LIVMapper → Voxel local map: registered updates
- LIVMapper → Pose, cloud & visualization: publishes
- Sensor calibration → Visual tracking & fusion: camera model
- Native vision & geometry libs → LIVMapper: geometry runtime
- Native vision & geometry libs → Visual tracking & fusion: vision runtime
