How hku-mars/fast-livo2 works
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: LIVMapper.cpp LIVMapper · main.cpp ROS pipeline entry · vio.cpp Visual tracking & fusion · preprocess.cpp LiDAR preprocessing
Components 14
ROS Runtime
- Catkin package · Defines the ROS C++ package and native dependencies.
CMakeLists.txt - ROS pipeline entry · Registers callbacks and drives mapping.
src/main.cpp - LiDAR, IMU & images
- LiDAR preprocessing · Converts LiDAR formats into filtered internal points.
src/preprocess.cpp - Livox custom messages
include/livox_ros_driver/CustomMsg.h - Pose, cloud & visualization
Estimation & Mapping
- IMU propagation · Accumulates IMU data for prediction and deskewing.
src/IMU_Processing.cpp - LIVMapper · Fuses prepared sensor observations, state, and map updates.
src/LIVMapper.cpp - Visual tracking & fusion · Tracks visual observations against LiDAR-inertial prediction.
src/vio.cpp - Frames & visual state · Frames, visual points, and Lie-group state math.
src/frame.cpp - Voxel local map · Persistent geometry for registration queries and updates.
src/voxel_map.cpp
Launch & Calibration
- Dataset launch profiles · Select sensor topics, parameters, and visualization setup.
launch/mapping_avia.launch - Sensor calibration · Supplies sensor settings and camera intrinsics/extrinsics.
config/avia.yaml
Other components
- Native vision & geometry libs · ROS, PCL, Eigen, OpenCV, Sophus, and Vikit.
package.xml
Connections 19
- 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