# tixiaoshan/lio-sam architecture

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

- Interactive diagram: https://gitdiagram.com/tixiaoshan/lio-sam
- Repository: https://github.com/tixiaoshan/lio-sam

## Overview

LIO-SAM is a ROS1 lidar–inertial odometry and mapping package. Its main workflow deskews lidar scans using timed point and IMU data, extracts geometric features, and uses mapping optimization to estimate poses and build a map; a separate, periodically reset IMU factor graph provides high-rate odometry. Mapping also supports GPS factors and loop closure, and the package exposes map saving. The graph reflects documented or excerpted relationships; some ROS topic links to mapping are conventional but not visible in the sampled mapping excerpt, so they are marked unverified.

Main entry points: [`src/mapOptmization.cpp`](https://github.com/tixiaoshan/lio-sam/blob/master/src/mapOptmization.cpp) (Map optimization), [`include/utility.h`](https://github.com/tixiaoshan/lio-sam/blob/master/include/utility.h) (Parameters and utilities), [`src/imageProjection.cpp`](https://github.com/tixiaoshan/lio-sam/blob/master/src/imageProjection.cpp) (Scan projection), [`src/imuPreintegration.cpp`](https://github.com/tixiaoshan/lio-sam/blob/master/src/imuPreintegration.cpp) (IMU preintegration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Scan front end"]
  node_projection["Scan projection"]
  node_features["Feature extraction"]
end

subgraph group_estimation["Pose estimation"]
  node_preintegration["IMU preintegration"]
end

subgraph group_mapping["Mapping and outputs"]
  node_mapping["Map optimization<br/>[mapOptmization.cpp]"]
  node_loop["Loop closure<br/>[mapOptmization.cpp]"]
  node_gpsfactor["GPS factors<br/>[mapOptmization.cpp]"]
  node_mapstore[("Keyframe map<br/>[mapOptmization.cpp]")]
  node_mapservice["Map saving<br/>[mapOptmization.cpp]"]
end

subgraph group_shared["Shared runtime"]
  node_utility["Parameters and utilities<br/>[utility.h]"]
end

node_lidar(("Lidar sensor"))
node_imu(("IMU sensor"))
node_gps(("GPS source"))
node_consumers(("Odometry and map consumers"))

node_lidar -->|"provides scans"| node_projection
node_imu -->|"provides motion data"| node_projection
node_projection -->|"publishes deskewed cloud"| node_features
node_features -.->|"sends features"| node_mapping
node_imu -->|"provides measurements"| node_preintegration
node_mapping -.->|"supplies lidar odometry"| node_preintegration
node_gps -->|"provides GPS fixes"| node_gpsfactor
node_mapping -->|"adds GPS factors"| node_gpsfactor
node_mapping -->|"runs loop closure"| node_loop
node_mapping -->|"stores keyframes"| node_mapstore
node_preintegration -->|"publishes odometry"| node_consumers
node_mapping -.->|"publishes map outputs"| node_consumers
node_consumers -.->|"requests map save"| node_mapservice
node_utility -->|"provides parameters"| node_projection
node_utility -->|"provides parameters"| node_features
node_utility -->|"provides parameters"| node_preintegration
node_utility -->|"provides parameters"| node_mapping

click node_projection "https://github.com/tixiaoshan/lio-sam/blob/master/src/imageProjection.cpp"
click node_features "https://github.com/tixiaoshan/lio-sam/blob/master/src/featureExtraction.cpp"
click node_preintegration "https://github.com/tixiaoshan/lio-sam/blob/master/src/imuPreintegration.cpp"
click node_mapping "https://github.com/tixiaoshan/lio-sam/blob/master/src/mapOptmization.cpp"
click node_loop "https://github.com/tixiaoshan/lio-sam/blob/master/src/mapOptmization.cpp"
click node_gpsfactor "https://github.com/tixiaoshan/lio-sam/blob/master/src/mapOptmization.cpp"
click node_mapstore "https://github.com/tixiaoshan/lio-sam/blob/master/src/mapOptmization.cpp"
click node_mapservice "https://github.com/tixiaoshan/lio-sam/blob/master/src/mapOptmization.cpp"
click node_utility "https://github.com/tixiaoshan/lio-sam/blob/master/include/utility.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_projection,node_features toneBlue
class node_preintegration toneAmber
class node_mapping,node_loop,node_gpsfactor,node_mapstore,node_mapservice toneMint
class node_utility toneRose
class node_lidar,node_imu,node_gps,node_consumers toneIndigo
```

## Components

### Scan front end

- [Scan projection](https://github.com/tixiaoshan/lio-sam/blob/master/src/imageProjection.cpp): `src/imageProjection.cpp`
- [Feature extraction](https://github.com/tixiaoshan/lio-sam/blob/master/src/featureExtraction.cpp): `src/featureExtraction.cpp`

### Pose estimation

- [IMU preintegration](https://github.com/tixiaoshan/lio-sam/blob/master/src/imuPreintegration.cpp): `src/imuPreintegration.cpp`

### Mapping and outputs

- [Map optimization](https://github.com/tixiaoshan/lio-sam/blob/master/src/mapOptmization.cpp): `src/mapOptmization.cpp`
- [Loop closure](https://github.com/tixiaoshan/lio-sam/blob/master/src/mapOptmization.cpp): `src/mapOptmization.cpp`
- [GPS factors](https://github.com/tixiaoshan/lio-sam/blob/master/src/mapOptmization.cpp): `src/mapOptmization.cpp`
- [Keyframe map](https://github.com/tixiaoshan/lio-sam/blob/master/src/mapOptmization.cpp): `src/mapOptmization.cpp`
- [Map saving](https://github.com/tixiaoshan/lio-sam/blob/master/src/mapOptmization.cpp): `src/mapOptmization.cpp`

### Shared runtime

- [Parameters and utilities](https://github.com/tixiaoshan/lio-sam/blob/master/include/utility.h): `include/utility.h`

### Other components

- **Lidar sensor**
- **IMU sensor**
- **GPS source**
- **Odometry and map consumers**

## Connections

- Lidar sensor → Scan projection: provides scans (evidence: `README.md`)
- IMU sensor → Scan projection: provides motion data (evidence: `README.md`)
- Scan projection → Feature extraction: publishes deskewed cloud (evidence: `src/featureExtraction.cpp`)
- Feature extraction → Map optimization: sends features
- IMU sensor → IMU preintegration: provides measurements (evidence: `src/imuPreintegration.cpp`)
- Map optimization → IMU preintegration: supplies lidar odometry
- GPS source → GPS factors: provides GPS fixes (evidence: `README.md`)
- Map optimization → GPS factors: adds GPS factors (evidence: `README.md`)
- Map optimization → Loop closure: runs loop closure (evidence: `src/mapOptmization.cpp`)
- Map optimization → Keyframe map: stores keyframes (evidence: `src/mapOptmization.cpp`)
- IMU preintegration → Odometry and map consumers: publishes odometry (evidence: `src/imuPreintegration.cpp`)
- Map optimization → Odometry and map consumers: publishes map outputs
- Odometry and map consumers → Map saving: requests map save
- Parameters and utilities → Scan projection: provides parameters (evidence: `src/imageProjection.cpp`)
- Parameters and utilities → Feature extraction: provides parameters (evidence: `src/featureExtraction.cpp`)
- Parameters and utilities → IMU preintegration: provides parameters (evidence: `src/imuPreintegration.cpp`)
- Parameters and utilities → Map optimization: provides parameters (evidence: `src/mapOptmization.cpp`)
