How michael-ztk/lightning-lm works
1. What this repo is
Lightning-LM is a ROS2-based LiDAR SLAM and localization system. It combines a fast LiDAR-IMU odometry front end, optional loop closure, online/offline execution modes, a 3D map backend, and an optional 3D-to-2D grid-map projection.
2. Top-level runtime boundary
The package is exposed as multiple executables under src/app: offline and online variants for SLAM, localization, frontend-only, loop closure, and a test UI. This is the main “deployment boundary” of the repo: the same core algorithms are wired differently depending on whether data comes from live ROS topics or from recorded ROS2 bags.
3. Main system orchestrators
src/core/system/slam.* and src/core/system/loc_system.* are the high-level coordinators. They connect sensor ingestion, preprocessing, mapping, localization, loop closing, optional grid-map generation, and UI publishing into one pipeline. These are the main places where features are enabled/disabled by config.
4. Sensor ingestion and preprocessing
Raw input enters through ROS2 wrappers and bag utilities in src/wrapper and src/io, then flows into LiDAR/IMU preprocessing in src/core/lio/pointcloud_preprocess.* and src/core/lio/imu_processing.hpp. This stage normalizes timestamps, point formats, and measurement groups before any estimation happens. It is the key boundary between external sensor formats and internal state estimation.
5. LIO front end
The fast odometry layer lives in src/core/lio, especially eskf.*, laser_mapping.*, and pose6d.h. This is the core motion-estimation front end: it fuses IMU with deskewed LiDAR scans, produces high-rate pose estimates, and feeds both mapping and localization. The README’s “AA-FasterLIO” refers to this layer.
6. Mapping backend and map representation
The map backend is split across src/core/maps, src/core/ivox3d, and src/core/g2p5. The 3D map is stored as chunked/tiled structures for large scenes, with dynamic loading of map partitions. g2p5 converts the 3D map into a 2D grid/map projection when enabled, and the repo includes default configs and a sample grid-map image output.
7. Localization stack
Localization is isolated in src/core/localization. It includes LiDAR map matching, localization result handling, pose extrapolation/smoothing, and a pose-graph-based backend under pose_graph. This subsystem consumes the stored map and produces smooth TF outputs at IMU-like frequency. It is distinct from SLAM because it relies on a prebuilt map and emphasizes stability over map growth.
8. Loop closure and global consistency
src/core/loop_closing provides loop candidate handling and global correction. The README indicates this is optional but standard for SLAM mode. It acts as the global-consistency boundary: the LIO front end estimates local motion, while loop closure corrects drift and may propagate corrections to the trajectory and map.
9. Optimization engine
The repo vendors its own lightweight optimization library in src/core/miao. This is a major architectural component: it provides graph/vertex/edge abstractions, robust kernels, sparse block matrices, linear solvers, and optimization algorithms. It is used by loop closure and localization, replacing a heavier external optimizer and supporting incremental updates.
10. Data models and shared types
src/common defines the domain objects passed across subsystems: IMU, odometry, keyframes, loop candidates, poses, navigation state, measurement groups, and parameter/options structs. These are the shared contracts that keep the pipeline modular. If you are drawing the architecture, this package is the internal message model between stages.
11. I/O, configuration, and persistence
src/io handles YAML/config and file I/O, while config/*.yaml provides dataset- and sensor-specific tuning. The system saves maps and grid maps to disk, with the map stored as blocks plus an exportable global.pcd and map.pgm. This persistent storage boundary is important because localization later reloads the saved map by path.
12. Visualization and operator-facing UI
src/ui contains Pangolin-based visualization for 3D clouds, trajectories, and a vehicle view. UI is optional and connected through the main system rather than being a separate app. It consumes the same internal state as mapping/localization but does not drive estimation.
13. ROS2 integration surface
The package exposes ROS2 services and topics through srv/LocCmd.srv, srv/SaveMap.srv, and the wrapper code. The main runtime outputs include TF and map-related topics; the save-map service is the main control-plane hook for persisting a map during online SLAM. This is the external API boundary of the system.
14. Tooling and deployment
The repo is built as a ROS2/CMake package, with colcon build as the primary build path. It depends on PCL, OpenCV, yaml-cpp, glog, gflags, Pangolin, and ROS2 message conversion support. The docker/ and scripts/ folders are operational tooling for dependency setup, dataset conversion/merge, and map export, not core runtime logic.
15. Overall data flow
Sensor data enters from ROS2 bags or live topics, is preprocessed into normalized LiDAR/IMU measurements, runs through the LiDAR-IMU front end, then either updates the live map in SLAM mode or matches against a stored map in localization mode. Optional loop closure and smoothing refine the trajectory, while optional g2p5 projects the 3D map into a 2D grid for visualization or saving.
16. How to think about the architecture
The cleanest diagram is: external sensors and bags on the left, preprocessing and LIO in the middle, mapping/localization/loop closure as parallel core branches, optimization as the shared backend for global correction, and outputs on the right as TF, point-cloud maps, 2D grids, and UI displays.
Main entry points: slam.cc SLAM system · imu.h Shared model · loc_system.cc Loc system · eskf.cc LIO front end
Components 21
Runtimes
ROS2 executables and deployment entry points.
- SLAM online · Live SLAM runtime wired to ROS topics.
src/app/run_slam_online.cc - SLAM offline · Bag-driven SLAM runtime for replayed data.
src/app/run_slam_offline.cc - Loc online · Live localization runtime against a prebuilt map.
src/app/run_loc_online.cc - Loc offline · Bag-driven localization runtime for evaluation.
src/app/run_loc_offline.cc - Frontend only · Front-end odometry and preprocessing without full system orchestration.
src/app/run_frontend_offline.cc - Loop closure · Standalone loop-closing and correction runtime.
src/app/run_loop_offline.cc - Test UI · Visualization-focused test executable.
src/app/test_ui.cc
Core
Estimation, mapping, localization, and optimization subsystems.
- SLAM system · Coordinates ingestion, front end, mapping, loop closure, outputs, and optional grid projection.
src/core/system/slam.cc - Loc system · Coordinates map-based localization, smoothing, and pose output.
src/core/system/loc_system.cc - Preprocess · Normalizes LiDAR and IMU measurements before estimation.
src/core/lio/pointcloud_preprocess.cc - LIO front end · Fast IMU-LiDAR motion estimation and scan matching.
src/core/lio/eskf.cc - 3D map · Chunked tiled 3D map representation and updates.
src/core/maps/tiled_map.cc - Grid map · Optional 3D-to-2D map projection for grid output.
src/core/g2p5/g2p5.cc - Localization · LiDAR localization, result handling, and pose smoothing on a prebuilt map.
src/core/localization/localization.cpp - Loop closing · Detects loop candidates and applies drift correction.
src/core/loop_closing/loop_closing.cc - Optimizer · Embedded graph optimization library for pose-graph and correction backends.
src/core/miao/core/graph/optimizer.cc
Infra
I/O, shared types, services, and visualization.
- Sensor IO · ROS bag and wrapper boundary for incoming sensor data.
src/wrapper/bag_io.cc - Shared model · Common poses, IMU, odometry, keyframes, measurements, and options.
src/common/imu.h - Storage & config · YAML configuration and file persistence for maps and runtime settings.
src/io/yaml_io.cc - UI · Pangolin-based cloud, trajectory, and vehicle visualization.
src/ui/pangolin_window.cc - ROS2 API · External control and persistence services exposed by the package.
srv/LocCmd.srv
Connections 29
- SLAM online → SLAM system: runs · Launches the online SLAM orchestration.
- SLAM offline → SLAM system: runs · Launches the offline SLAM orchestration.
- Loc online → Loc system: runs · Launches live localization.
- Loc offline → Loc system: runs · Launches replay-based localization.
- Frontend only → Preprocess: runs · Exercises the front-end pipeline without the full system.
- Loop closure → Loop closing: runs · Standalone loop closure execution.
- Test UI → UI: runs · Starts the visualization UI.
- Sensor IO → Preprocess: feeds · Provides raw LiDAR/IMU data for normalization.
- Preprocess → LIO front end: inputs · Supplies deskewed and grouped measurements.
- LIO front end → 3D map: updates · Produces odometry and map updates in SLAM mode.
- LIO front end → Localization: drives · Provides high-rate pose estimates for localization.
- 3D map → Grid map: exports · Optional 3D map projection into a 2D grid map.
- 3D map → Storage & config: persists · Saved map blocks and exported artifacts.
- Storage & config → Localization: loads · Reloads the stored map and runtime settings.
- Loop closing → Optimizer: solves with · Uses graph optimization for global correction.
- Localization → Optimizer: solves with · Uses pose-graph backend and smoothing support.
- SLAM system → Loop closing: optional · Enables loop closure in SLAM mode.
- SLAM system → Grid map: optional · Enables 2D projection when configured.
- SLAM system → UI: publishes · Feeds live state to visualization.
- Loc system → UI: publishes · Feeds localization state to visualization.
- SLAM system → ROS2 API: exposes · Provides save-map and command services.
- Loc system → ROS2 API: exposes · Provides command and status surfaces.
- SLAM system → Shared model: uses · Consumes and publishes shared domain types.
- Loc system → Shared model: uses · Consumes and publishes shared domain types.
- Preprocess → Shared model: uses · Builds normalized measurement groups and state objects.
- LIO front end → Shared model: uses · Reads and writes pose, IMU, and odometry models.
- Localization → Shared model: uses · Consumes map, pose, and localization result types.
- Loop closing → Shared model: uses · Consumes loop candidates and trajectory state.
- UI → Shared model: reads · Visualizes the same internal trajectories and clouds.