# michael-ztk/lightning-lm architecture

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

- Interactive diagram: https://gitdiagram.com/michael-ztk/lightning-lm
- Repository: https://github.com/michael-ztk/lightning-lm

## Overview

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: [`src/core/system/slam.cc`](https://github.com/michael-ztk/lightning-lm/blob/master/src/core/system/slam.cc) (SLAM system), [`src/common/imu.h`](https://github.com/michael-ztk/lightning-lm/blob/master/src/common/imu.h) (Shared model), [`src/core/system/loc_system.cc`](https://github.com/michael-ztk/lightning-lm/blob/master/src/core/system/loc_system.cc) (Loc system), [`src/core/lio/eskf.cc`](https://github.com/michael-ztk/lightning-lm/blob/master/src/core/lio/eskf.cc) (LIO front end)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtimes"]
  node_app_slam_online(("SLAM online<br/>ros2 exe<br/>[run_slam_online.cc]"))
  node_app_slam_offline(("SLAM offline<br/>ros2 exe"))
  node_app_loc_online(("Loc online<br/>ros2 exe<br/>[run_loc_online.cc]"))
  node_app_loc_offline(("Loc offline<br/>ros2 exe<br/>[run_loc_offline.cc]"))
  node_app_frontend_offline(("Frontend only<br/>ros2 exe"))
  node_app_loop_offline(("Loop closure<br/>ros2 exe"))
  node_app_test_ui(("Test UI<br/>ros2 exe<br/>[test_ui.cc]"))
end

subgraph group_core["Core"]
  node_slam_system["SLAM system<br/>orchestrator<br/>[slam.cc]"]
  node_loc_system["Loc system<br/>orchestrator<br/>[loc_system.cc]"]
  node_preprocess["Preprocess"]
  node_lio_frontend["LIO front end<br/>odometry<br/>[eskf.cc]"]
  node_map_backend[("3D map<br/>map store<br/>[tiled_map.cc]")]
  node_grid_projection["Grid map<br/>projection<br/>[g2p5.cc]"]
  node_localization_stack["Localization<br/>map-based loc<br/>[localization.cpp]"]
  node_loop_closing["Loop closing<br/>global correction<br/>[loop_closing.cc]"]
  node_optimizer["Optimizer<br/>graph solver<br/>[optimizer.cc]"]
end

subgraph group_infra["Infra"]
  node_sensor_io["Sensor IO<br/>ingest<br/>[bag_io.cc]"]
  node_shared_model["Shared model<br/>domain types<br/>[imu.h]"]
  node_storage_config["Storage & config<br/>persistence<br/>[yaml_io.cc]"]
  node_ui["UI<br/>visualization<br/>[pangolin_window.cc]"]
  node_ros_api["ROS2 API<br/>services/topics<br/>[LocCmd.srv]"]
end

node_app_slam_online -->|"runs"| node_slam_system
node_app_slam_offline -->|"runs"| node_slam_system
node_app_loc_online -->|"runs"| node_loc_system
node_app_loc_offline -->|"runs"| node_loc_system
node_app_frontend_offline -->|"runs"| node_preprocess
node_app_loop_offline -->|"runs"| node_loop_closing
node_app_test_ui -->|"runs"| node_ui
node_sensor_io -->|"feeds"| node_preprocess
node_preprocess -->|"inputs"| node_lio_frontend
node_lio_frontend -->|"updates"| node_map_backend
node_lio_frontend -->|"drives"| node_localization_stack
node_map_backend -->|"exports"| node_grid_projection
node_map_backend -->|"persists"| node_storage_config
node_storage_config -->|"loads"| node_localization_stack
node_loop_closing -->|"solves with"| node_optimizer
node_localization_stack -->|"solves with"| node_optimizer
node_slam_system -->|"optional"| node_loop_closing
node_slam_system -->|"optional"| node_grid_projection
node_slam_system -->|"publishes"| node_ui
node_loc_system -->|"publishes"| node_ui
node_slam_system -->|"exposes"| node_ros_api
node_loc_system -->|"exposes"| node_ros_api
node_slam_system -->|"uses"| node_shared_model
node_loc_system -->|"uses"| node_shared_model
node_preprocess -->|"uses"| node_shared_model
node_lio_frontend -->|"uses"| node_shared_model
node_localization_stack -->|"uses"| node_shared_model
node_loop_closing -->|"uses"| node_shared_model
node_ui -->|"reads"| node_shared_model

click node_app_slam_online "https://github.com/michael-ztk/lightning-lm/blob/master/src/app/run_slam_online.cc"
click node_app_slam_offline "https://github.com/michael-ztk/lightning-lm/blob/master/src/app/run_slam_offline.cc"
click node_app_loc_online "https://github.com/michael-ztk/lightning-lm/blob/master/src/app/run_loc_online.cc"
click node_app_loc_offline "https://github.com/michael-ztk/lightning-lm/blob/master/src/app/run_loc_offline.cc"
click node_app_frontend_offline "https://github.com/michael-ztk/lightning-lm/blob/master/src/app/run_frontend_offline.cc"
click node_app_loop_offline "https://github.com/michael-ztk/lightning-lm/blob/master/src/app/run_loop_offline.cc"
click node_app_test_ui "https://github.com/michael-ztk/lightning-lm/blob/master/src/app/test_ui.cc"
click node_slam_system "https://github.com/michael-ztk/lightning-lm/blob/master/src/core/system/slam.cc"
click node_loc_system "https://github.com/michael-ztk/lightning-lm/blob/master/src/core/system/loc_system.cc"
click node_sensor_io "https://github.com/michael-ztk/lightning-lm/blob/master/src/wrapper/bag_io.cc"
click node_preprocess "https://github.com/michael-ztk/lightning-lm/blob/master/src/core/lio/pointcloud_preprocess.cc"
click node_lio_frontend "https://github.com/michael-ztk/lightning-lm/blob/master/src/core/lio/eskf.cc"
click node_map_backend "https://github.com/michael-ztk/lightning-lm/blob/master/src/core/maps/tiled_map.cc"
click node_grid_projection "https://github.com/michael-ztk/lightning-lm/blob/master/src/core/g2p5/g2p5.cc"
click node_localization_stack "https://github.com/michael-ztk/lightning-lm/blob/master/src/core/localization/localization.cpp"
click node_loop_closing "https://github.com/michael-ztk/lightning-lm/blob/master/src/core/loop_closing/loop_closing.cc"
click node_optimizer "https://github.com/michael-ztk/lightning-lm/blob/master/src/core/miao/core/graph/optimizer.cc"
click node_shared_model "https://github.com/michael-ztk/lightning-lm/blob/master/src/common/imu.h"
click node_storage_config "https://github.com/michael-ztk/lightning-lm/blob/master/src/io/yaml_io.cc"
click node_ui "https://github.com/michael-ztk/lightning-lm/blob/master/src/ui/pangolin_window.cc"
click node_ros_api "https://github.com/michael-ztk/lightning-lm/blob/master/srv/LocCmd.srv"

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_app_slam_online,node_app_slam_offline,node_app_loc_online,node_app_loc_offline,node_app_frontend_offline,node_app_loop_offline,node_app_test_ui toneBlue
class node_slam_system,node_loc_system,node_preprocess,node_lio_frontend,node_map_backend,node_grid_projection,node_localization_stack,node_loop_closing,node_optimizer toneAmber
class node_sensor_io,node_shared_model,node_storage_config,node_ui,node_ros_api toneMint
```

## Components

### Runtimes

ROS2 executables and deployment entry points.

- [SLAM online](https://github.com/michael-ztk/lightning-lm/blob/master/src/app/run_slam_online.cc): ros2 exe · Live SLAM runtime wired to ROS topics. · `src/app/run_slam_online.cc`
- [SLAM offline](https://github.com/michael-ztk/lightning-lm/blob/master/src/app/run_slam_offline.cc): ros2 exe · Bag-driven SLAM runtime for replayed data. · `src/app/run_slam_offline.cc`
- [Loc online](https://github.com/michael-ztk/lightning-lm/blob/master/src/app/run_loc_online.cc): ros2 exe · Live localization runtime against a prebuilt map. · `src/app/run_loc_online.cc`
- [Loc offline](https://github.com/michael-ztk/lightning-lm/blob/master/src/app/run_loc_offline.cc): ros2 exe · Bag-driven localization runtime for evaluation. · `src/app/run_loc_offline.cc`
- [Frontend only](https://github.com/michael-ztk/lightning-lm/blob/master/src/app/run_frontend_offline.cc): ros2 exe · Front-end odometry and preprocessing without full system orchestration. · `src/app/run_frontend_offline.cc`
- [Loop closure](https://github.com/michael-ztk/lightning-lm/blob/master/src/app/run_loop_offline.cc): ros2 exe · Standalone loop-closing and correction runtime. · `src/app/run_loop_offline.cc`
- [Test UI](https://github.com/michael-ztk/lightning-lm/blob/master/src/app/test_ui.cc): ros2 exe · Visualization-focused test executable. · `src/app/test_ui.cc`

### Core

Estimation, mapping, localization, and optimization subsystems.

- [SLAM system](https://github.com/michael-ztk/lightning-lm/blob/master/src/core/system/slam.cc): orchestrator · Coordinates ingestion, front end, mapping, loop closure, outputs, and optional grid projection. · `src/core/system/slam.cc`
- [Loc system](https://github.com/michael-ztk/lightning-lm/blob/master/src/core/system/loc_system.cc): orchestrator · Coordinates map-based localization, smoothing, and pose output. · `src/core/system/loc_system.cc`
- [Preprocess](https://github.com/michael-ztk/lightning-lm/blob/master/src/core/lio/pointcloud_preprocess.cc): lio preprocess · Normalizes LiDAR and IMU measurements before estimation. · `src/core/lio/pointcloud_preprocess.cc`
- [LIO front end](https://github.com/michael-ztk/lightning-lm/blob/master/src/core/lio/eskf.cc): odometry · Fast IMU-LiDAR motion estimation and scan matching. · `src/core/lio/eskf.cc`
- [3D map](https://github.com/michael-ztk/lightning-lm/blob/master/src/core/maps/tiled_map.cc): map store · Chunked tiled 3D map representation and updates. · `src/core/maps/tiled_map.cc`
- [Grid map](https://github.com/michael-ztk/lightning-lm/blob/master/src/core/g2p5/g2p5.cc): projection · Optional 3D-to-2D map projection for grid output. · `src/core/g2p5/g2p5.cc`
- [Localization](https://github.com/michael-ztk/lightning-lm/blob/master/src/core/localization/localization.cpp): map-based loc · LiDAR localization, result handling, and pose smoothing on a prebuilt map. · `src/core/localization/localization.cpp`
- [Loop closing](https://github.com/michael-ztk/lightning-lm/blob/master/src/core/loop_closing/loop_closing.cc): global correction · Detects loop candidates and applies drift correction. · `src/core/loop_closing/loop_closing.cc`
- [Optimizer](https://github.com/michael-ztk/lightning-lm/blob/master/src/core/miao/core/graph/optimizer.cc): graph solver · 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](https://github.com/michael-ztk/lightning-lm/blob/master/src/wrapper/bag_io.cc): ingest · ROS bag and wrapper boundary for incoming sensor data. · `src/wrapper/bag_io.cc`
- [Shared model](https://github.com/michael-ztk/lightning-lm/blob/master/src/common/imu.h): domain types · Common poses, IMU, odometry, keyframes, measurements, and options. · `src/common/imu.h`
- [Storage & config](https://github.com/michael-ztk/lightning-lm/blob/master/src/io/yaml_io.cc): persistence · YAML configuration and file persistence for maps and runtime settings. · `src/io/yaml_io.cc`
- [UI](https://github.com/michael-ztk/lightning-lm/blob/master/src/ui/pangolin_window.cc): visualization · Pangolin-based cloud, trajectory, and vehicle visualization. · `src/ui/pangolin_window.cc`
- [ROS2 API](https://github.com/michael-ztk/lightning-lm/blob/master/srv/LocCmd.srv): services/topics · External control and persistence services exposed by the package. · `srv/LocCmd.srv`

## Connections

- 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.
