# hku-mars/r3live architecture

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

- Interactive diagram: https://gitdiagram.com/hku-mars/r3live
- Repository: https://github.com/hku-mars/r3live

## Overview

R3LIVE fuses LiDAR, inertial, and camera measurements for real-time state estimation and RGB map reconstruction. The documented online workflow combines a geometric LiDAR-inertial map with visual-inertial texture/color mapping, and supports saving maps. A separate offline utility reconstructs and textures meshes for 3D applications. The README establishes the two odometry subsystems and their roles; sampled source excerpts are partial, so internal call wiring beyond those documented relationships is left out.

Main entry points: [`r3live/src/r3live.cpp`](https://github.com/hku-mars/r3live/blob/master/r3live/src/r3live.cpp) (R3LIVE Runtime), [`r3live/src/r3live_lio.cpp`](https://github.com/hku-mars/r3live/blob/master/r3live/src/r3live_lio.cpp) (LiDAR-Inertial Odometry), [`r3live/src/r3live_vio.cpp`](https://github.com/hku-mars/r3live/blob/master/r3live/src/r3live_vio.cpp) (Visual-Inertial Odometry), [`r3live/src/rgb_map/rgbmap_tracker.cpp`](https://github.com/hku-mars/r3live/blob/master/r3live/src/rgb_map/rgbmap_tracker.cpp) (RGB Map Tracker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_online["Online Estimation"]
  node_mapping["R3LIVE Runtime<br/>[r3live.cpp]"]
  node_lio["LiDAR-Inertial Odometry<br/>[r3live_lio.cpp]"]
  node_vio["Visual-Inertial Odometry<br/>[r3live_vio.cpp]"]
end

subgraph group_rgb["RGB Mapping"]
  node_tracker["RGB Map Tracker<br/>[rgbmap_tracker.cpp]"]
  node_image_frame["Image Frames<br/>[image_frame.cpp]"]
  node_rgb_points["RGB Point Cloud"]
  node_map["RGB Geometric Map"]
  node_recorder["Map Recorder"]
end

subgraph group_offline["Offline Meshing"]
  node_saved_map["Saved Map"]
  node_meshing["Mesh Reconstruction"]
  node_mesh_builder["Mesh Builder<br/>[build_mesh.hpp]"]
  node_mesh["Textured Mesh<br/>[Mesh.cpp]"]
end

subgraph group_support["Sensor Processing"]
  node_imu["IMU Processing<br/>[IMU_Processing.cpp]"]
  node_lidar_front["LiDAR Front End"]
  node_flow["Optical Flow<br/>[lkpyramid.cpp]"]
end

node_operator(("Operator"))
node_sensors(("Sensor Streams"))

node_sensors -->|"supply measurements"| node_mapping
node_mapping -->|"runs LIO"| node_lio
node_mapping -->|"runs VIO"| node_vio
node_lio -->|"processes inertial data"| node_imu
node_vio -->|"tracks image motion"| node_flow
node_vio -->|"updates visual map"| node_tracker
node_tracker -->|"uses frames"| node_image_frame
node_tracker -->|"updates point colors"| node_rgb_points
node_lio -->|"builds geometry"| node_map
node_rgb_points -->|"contributes RGB points"| node_map
node_operator -->|"requests map save"| node_recorder
node_recorder -->|"records map"| node_map
node_recorder -->|"writes map"| node_saved_map
node_operator -->|"starts reconstruction"| node_meshing
node_saved_map -->|"provides map"| node_meshing
node_meshing -->|"builds mesh"| node_mesh_builder
node_mesh_builder -->|"produces mesh"| node_mesh

click node_mapping "https://github.com/hku-mars/r3live/blob/master/r3live/src/r3live.cpp"
click node_lio "https://github.com/hku-mars/r3live/blob/master/r3live/src/r3live_lio.cpp"
click node_imu "https://github.com/hku-mars/r3live/blob/master/r3live/src/loam/IMU_Processing.cpp"
click node_lidar_front "https://github.com/hku-mars/r3live/blob/master/r3live/src/loam/LiDAR_front_end.cpp"
click node_vio "https://github.com/hku-mars/r3live/blob/master/r3live/src/r3live_vio.cpp"
click node_flow "https://github.com/hku-mars/r3live/blob/master/r3live/src/optical_flow/lkpyramid.cpp"
click node_tracker "https://github.com/hku-mars/r3live/blob/master/r3live/src/rgb_map/rgbmap_tracker.cpp"
click node_image_frame "https://github.com/hku-mars/r3live/blob/master/r3live/src/rgb_map/image_frame.cpp"
click node_rgb_points "https://github.com/hku-mars/r3live/blob/master/r3live/src/rgb_map/pointcloud_rgbd.cpp"
click node_map "https://github.com/hku-mars/r3live/blob/master/r3live/src/rgb_map/pointcloud_rgbd.cpp"
click node_recorder "https://github.com/hku-mars/r3live/blob/master/r3live/src/rgb_map/offline_map_recorder.cpp"
click node_meshing "https://github.com/hku-mars/r3live/blob/master/r3live/src/r3live_reconstruct_mesh.cpp"
click node_mesh_builder "https://github.com/hku-mars/r3live/blob/master/r3live/src/meshing/build_mesh.hpp"
click node_mesh "https://github.com/hku-mars/r3live/blob/master/r3live/src/meshing/MVS/Mesh.cpp"

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_mapping,node_lio,node_vio toneBlue
class node_tracker,node_image_frame,node_rgb_points,node_map,node_recorder toneAmber
class node_saved_map,node_meshing,node_mesh_builder,node_mesh toneMint
class node_imu,node_lidar_front,node_flow toneRose
class node_operator,node_sensors toneIndigo
```

## Components

### Online Estimation

- [R3LIVE Runtime](https://github.com/hku-mars/r3live/blob/master/r3live/src/r3live.cpp): `r3live/src/r3live.cpp`
- [LiDAR-Inertial Odometry](https://github.com/hku-mars/r3live/blob/master/r3live/src/r3live_lio.cpp): `r3live/src/r3live_lio.cpp`
- [Visual-Inertial Odometry](https://github.com/hku-mars/r3live/blob/master/r3live/src/r3live_vio.cpp): `r3live/src/r3live_vio.cpp`

### RGB Mapping

- [RGB Map Tracker](https://github.com/hku-mars/r3live/blob/master/r3live/src/rgb_map/rgbmap_tracker.cpp): `r3live/src/rgb_map/rgbmap_tracker.cpp`
- [Image Frames](https://github.com/hku-mars/r3live/blob/master/r3live/src/rgb_map/image_frame.cpp): `r3live/src/rgb_map/image_frame.cpp`
- [RGB Point Cloud](https://github.com/hku-mars/r3live/blob/master/r3live/src/rgb_map/pointcloud_rgbd.cpp): `r3live/src/rgb_map/pointcloud_rgbd.cpp`
- [RGB Geometric Map](https://github.com/hku-mars/r3live/blob/master/r3live/src/rgb_map/pointcloud_rgbd.cpp): `r3live/src/rgb_map/pointcloud_rgbd.cpp`
- [Map Recorder](https://github.com/hku-mars/r3live/blob/master/r3live/src/rgb_map/offline_map_recorder.cpp): `r3live/src/rgb_map/offline_map_recorder.cpp`

### Offline Meshing

- **Saved Map**
- [Mesh Reconstruction](https://github.com/hku-mars/r3live/blob/master/r3live/src/r3live_reconstruct_mesh.cpp): `r3live/src/r3live_reconstruct_mesh.cpp`
- [Mesh Builder](https://github.com/hku-mars/r3live/blob/master/r3live/src/meshing/build_mesh.hpp): `r3live/src/meshing/build_mesh.hpp`
- [Textured Mesh](https://github.com/hku-mars/r3live/blob/master/r3live/src/meshing/MVS/Mesh.cpp): `r3live/src/meshing/MVS/Mesh.cpp`

### Sensor Processing

- [IMU Processing](https://github.com/hku-mars/r3live/blob/master/r3live/src/loam/IMU_Processing.cpp): `r3live/src/loam/IMU_Processing.cpp`
- [LiDAR Front End](https://github.com/hku-mars/r3live/blob/master/r3live/src/loam/LiDAR_front_end.cpp): `r3live/src/loam/LiDAR_front_end.cpp`
- [Optical Flow](https://github.com/hku-mars/r3live/blob/master/r3live/src/optical_flow/lkpyramid.cpp): `r3live/src/optical_flow/lkpyramid.cpp`

### Other components

- **Operator**
- **Sensor Streams**

## Connections

- Sensor Streams → R3LIVE Runtime: supply measurements
- R3LIVE Runtime → LiDAR-Inertial Odometry: runs LIO
- R3LIVE Runtime → Visual-Inertial Odometry: runs VIO
- LiDAR-Inertial Odometry → IMU Processing: processes inertial data
- Visual-Inertial Odometry → Optical Flow: tracks image motion
- Visual-Inertial Odometry → RGB Map Tracker: updates visual map
- RGB Map Tracker → Image Frames: uses frames
- RGB Map Tracker → RGB Point Cloud: updates point colors
- LiDAR-Inertial Odometry → RGB Geometric Map: builds geometry
- RGB Point Cloud → RGB Geometric Map: contributes RGB points
- Operator → Map Recorder: requests map save
- Map Recorder → RGB Geometric Map: records map
- Map Recorder → Saved Map: writes map
- Operator → Mesh Reconstruction: starts reconstruction
- Saved Map → Mesh Reconstruction: provides map
- Mesh Reconstruction → Mesh Builder: builds mesh
- Mesh Builder → Textured Mesh: produces mesh