# leggedrobotics/dlio architecture

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

- Interactive diagram: https://gitdiagram.com/leggedrobotics/dlio
- Repository: https://github.com/leggedrobotics/dlio

## Overview

This ROS1 DLIO fork estimates LiDAR motion from synchronized IMU and point-cloud streams, compensates for scan motion, and publishes odometry and trajectory products while building a map from keyframes. Its principal runtime path is the odometry node: sensor input and IMU state estimation feed deskewing and scan-to-submap registration; keyframes are sent to a separate mapper for map publication and automatic PCD saving. README capabilities also include live and bag-replay operation. Source excerpts are partial, so uncertain internal call links are omitted.

Main entry points: [`src/dlio/odom.cc`](https://github.com/leggedrobotics/dlio/blob/grandtour/src/dlio/odom.cc) (Odometry runtime), [`src/nano_gicp/nano_gicp.cc`](https://github.com/leggedrobotics/dlio/blob/grandtour/src/nano_gicp/nano_gicp.cc) (NanoGICP alignment), [`src/dlio/map.cc`](https://github.com/leggedrobotics/dlio/blob/grandtour/src/dlio/map.cc) (Map accumulation), [`src/dlio/odom_node.cc`](https://github.com/leggedrobotics/dlio/blob/grandtour/src/dlio/odom_node.cc) (Odometry node)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_sensors["Sensor processing"]
  node_odom_node["Odometry node<br/>[odom_node.cc]"]
  node_odom_runtime["Odometry runtime<br/>[odom.cc]"]
end

subgraph group_estimation["Odometry estimation"]
  node_imu_state["IMU state and bias<br/>[odom.cc]"]
  node_deskew["Cloud deskewing<br/>[odom.cc]"]
  node_keyframes_submap["Keyframes and submap<br/>[odom.cc]"]
end

subgraph group_registration["Registration engine"]
  node_nano_gicp["NanoGICP alignment<br/>[nano_gicp.cc]"]
  node_least_squares["Least-squares optimizer"]
  node_kdtree["KD-tree search<br/>[nanoflann.cc]"]
  node_kdtree_adaptor["Point-cloud adaptor"]
end

subgraph group_mapping["Mapping and outputs"]
  node_map_node["Map node<br/>[map_node.cc]"]
  node_map_runtime["Map accumulation<br/>[map.cc]"]
  node_map_state["Voxel map<br/>[map.h]"]
  node_pose_outputs["Pose and path outputs<br/>[odom.cc]"]
  node_cloud_outputs["Deskewed cloud output<br/>[odom.cc]"]
end

node_sensor_streams(("IMU and LiDAR"))
node_result_consumers(("ROS consumers"))
node_pcd_file["Saved map PCD"]
node_runtime_config["Sensor and runtime settings<br/>[dlio.yaml]"]

node_sensor_streams -->|"publishes sensors"| node_odom_node
node_odom_node -->|"starts"| node_odom_runtime
node_runtime_config -->|"configures"| node_odom_runtime
node_odom_runtime -->|"processes IMU"| node_imu_state
node_odom_runtime -->|"deskews scans"| node_deskew
node_odom_runtime -->|"builds submap"| node_keyframes_submap
node_odom_runtime -->|"aligns scan"| node_nano_gicp
node_nano_gicp -->|"searches neighbors"| node_kdtree
node_kdtree -->|"indexes points"| node_kdtree_adaptor
node_nano_gicp -->|"optimizes alignment"| node_least_squares
node_odom_runtime -->|"publishes poses"| node_pose_outputs
node_odom_runtime -->|"publishes cloud"| node_cloud_outputs
node_pose_outputs -->|"delivers odometry"| node_result_consumers
node_cloud_outputs -->|"delivers cloud"| node_result_consumers
node_odom_runtime -->|"publishes keyframes"| node_map_node
node_map_node -->|"starts"| node_map_runtime
node_map_runtime -->|"updates map"| node_map_state
node_map_state -->|"publishes map"| node_result_consumers
node_map_runtime -->|"saves on shutdown"| node_pcd_file

click node_odom_node "https://github.com/leggedrobotics/dlio/blob/grandtour/src/dlio/odom_node.cc"
click node_odom_runtime "https://github.com/leggedrobotics/dlio/blob/grandtour/src/dlio/odom.cc"
click node_imu_state "https://github.com/leggedrobotics/dlio/blob/grandtour/src/dlio/odom.cc"
click node_deskew "https://github.com/leggedrobotics/dlio/blob/grandtour/src/dlio/odom.cc"
click node_keyframes_submap "https://github.com/leggedrobotics/dlio/blob/grandtour/src/dlio/odom.cc"
click node_nano_gicp "https://github.com/leggedrobotics/dlio/blob/grandtour/src/nano_gicp/nano_gicp.cc"
click node_least_squares "https://github.com/leggedrobotics/dlio/blob/grandtour/src/nano_gicp/lsq_registration.cc"
click node_kdtree "https://github.com/leggedrobotics/dlio/blob/grandtour/src/nano_gicp/nanoflann.cc"
click node_kdtree_adaptor "https://github.com/leggedrobotics/dlio/blob/grandtour/include/nano_gicp/nanoflann_adaptor.h"
click node_map_node "https://github.com/leggedrobotics/dlio/blob/grandtour/src/dlio/map_node.cc"
click node_map_runtime "https://github.com/leggedrobotics/dlio/blob/grandtour/src/dlio/map.cc"
click node_map_state "https://github.com/leggedrobotics/dlio/blob/grandtour/include/dlio/map.h"
click node_pose_outputs "https://github.com/leggedrobotics/dlio/blob/grandtour/src/dlio/odom.cc"
click node_cloud_outputs "https://github.com/leggedrobotics/dlio/blob/grandtour/src/dlio/odom.cc"
click node_runtime_config "https://github.com/leggedrobotics/dlio/blob/grandtour/cfg/dlio.yaml"

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_odom_node,node_odom_runtime toneBlue
class node_imu_state,node_deskew,node_keyframes_submap toneAmber
class node_nano_gicp,node_least_squares,node_kdtree,node_kdtree_adaptor toneMint
class node_map_node,node_map_runtime,node_map_state,node_pose_outputs,node_cloud_outputs toneRose
class node_sensor_streams,node_result_consumers,node_pcd_file toneIndigo
class node_runtime_config toneTeal
```

## Components

### Sensor processing

- [Odometry node](https://github.com/leggedrobotics/dlio/blob/grandtour/src/dlio/odom_node.cc): `src/dlio/odom_node.cc`
- [Odometry runtime](https://github.com/leggedrobotics/dlio/blob/grandtour/src/dlio/odom.cc): `src/dlio/odom.cc`

### Odometry estimation

- [IMU state and bias](https://github.com/leggedrobotics/dlio/blob/grandtour/src/dlio/odom.cc): `src/dlio/odom.cc`
- [Cloud deskewing](https://github.com/leggedrobotics/dlio/blob/grandtour/src/dlio/odom.cc): `src/dlio/odom.cc`
- [Keyframes and submap](https://github.com/leggedrobotics/dlio/blob/grandtour/src/dlio/odom.cc): `src/dlio/odom.cc`

### Registration engine

- [NanoGICP alignment](https://github.com/leggedrobotics/dlio/blob/grandtour/src/nano_gicp/nano_gicp.cc): `src/nano_gicp/nano_gicp.cc`
- [Least-squares optimizer](https://github.com/leggedrobotics/dlio/blob/grandtour/src/nano_gicp/lsq_registration.cc): `src/nano_gicp/lsq_registration.cc`
- [KD-tree search](https://github.com/leggedrobotics/dlio/blob/grandtour/src/nano_gicp/nanoflann.cc): `src/nano_gicp/nanoflann.cc`
- [Point-cloud adaptor](https://github.com/leggedrobotics/dlio/blob/grandtour/include/nano_gicp/nanoflann_adaptor.h): `include/nano_gicp/nanoflann_adaptor.h`

### Mapping and outputs

- [Map node](https://github.com/leggedrobotics/dlio/blob/grandtour/src/dlio/map_node.cc): `src/dlio/map_node.cc`
- [Map accumulation](https://github.com/leggedrobotics/dlio/blob/grandtour/src/dlio/map.cc): `src/dlio/map.cc`
- [Voxel map](https://github.com/leggedrobotics/dlio/blob/grandtour/include/dlio/map.h): `include/dlio/map.h`
- [Pose and path outputs](https://github.com/leggedrobotics/dlio/blob/grandtour/src/dlio/odom.cc): `src/dlio/odom.cc`
- [Deskewed cloud output](https://github.com/leggedrobotics/dlio/blob/grandtour/src/dlio/odom.cc): `src/dlio/odom.cc`

### Other components

- **IMU and LiDAR**
- **ROS consumers**
- **Saved map PCD**
- [Sensor and runtime settings](https://github.com/leggedrobotics/dlio/blob/grandtour/cfg/dlio.yaml): `cfg/dlio.yaml`

## Connections

- IMU and LiDAR → Odometry node: publishes sensors
- Odometry node → Odometry runtime: starts
- Sensor and runtime settings → Odometry runtime: configures
- Odometry runtime → IMU state and bias: processes IMU
- Odometry runtime → Cloud deskewing: deskews scans
- Odometry runtime → Keyframes and submap: builds submap
- Odometry runtime → NanoGICP alignment: aligns scan
- NanoGICP alignment → KD-tree search: searches neighbors
- KD-tree search → Point-cloud adaptor: indexes points
- NanoGICP alignment → Least-squares optimizer: optimizes alignment
- Odometry runtime → Pose and path outputs: publishes poses
- Odometry runtime → Deskewed cloud output: publishes cloud
- Pose and path outputs → ROS consumers: delivers odometry
- Deskewed cloud output → ROS consumers: delivers cloud
- Odometry runtime → Map node: publishes keyframes
- Map node → Map accumulation: starts
- Map accumulation → Voxel map: updates map
- Voxel map → ROS consumers: publishes map
- Map accumulation → Saved map PCD: saves on shutdown