# ethz-asl/bievr-lio architecture

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

- Interactive diagram: https://gitdiagram.com/ethz-asl/bievr-lio
- Repository: https://github.com/ethz-asl/bievr-lio

## Overview

BIEVR-LIO estimates LiDAR-inertial odometry from synchronized scans and IMU data, exposing online topic and recorded-bag entry points through both ROS versions. The core workflow preprocesses and undistorts each scan, initializes and samples a voxel-wise bump-image map, registers scan points to it, and maintains an inertial state estimate for publication. The graph includes the documented ROS1/ROS2 and map-informed sampling capabilities. Several implementation files were not sampled, so uncertain internal wiring is omitted.

Main entry points: [`BIEVR/src/pipeline.cpp`](https://github.com/ethz-asl/bievr-lio/blob/main/BIEVR/src/pipeline.cpp) (Odometry pipeline), [`interfaces/ros1/src/process_topics.cpp`](https://github.com/ethz-asl/bievr-lio/blob/main/interfaces/ros1/src/process_topics.cpp) (ROS1 topics), [`interfaces/ros2/src/process_topics.cpp`](https://github.com/ethz-asl/bievr-lio/blob/main/interfaces/ros2/src/process_topics.cpp) (ROS2 topics), [`BIEVR/src/synchronizer.cpp`](https://github.com/ethz-asl/bievr-lio/blob/main/BIEVR/src/synchronizer.cpp) (Sensor synchronizer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["ROS interfaces"]
  node_ros1_topics["ROS1 topics<br/>[process_topics.cpp]"]
  node_ros1_bag["ROS1 bag<br/>[process_bag.cpp]"]
  node_ros2_topics["ROS2 topics<br/>[process_topics.cpp]"]
  node_ros2_bag["ROS2 bag<br/>[process_bag.cpp]"]
  node_conversions["Message conversion<br/>[conversions.h]"]
end

subgraph group_estimation["State estimation"]
  node_sync["Sensor synchronizer<br/>[synchronizer.cpp]"]
  node_pipeline["Odometry pipeline<br/>[pipeline.cpp]"]
  node_preprocess["Scan preprocessing<br/>[preprocess.cpp]"]
  node_undistort["Scan undistortion<br/>[undistort.cpp]"]
  node_imu["IMU integration<br/>[imu_integrator.cpp]"]
  node_inertial_factor["Inertial factors"]
  node_prior_factor["Prior factors<br/>[prior_factor.cpp]"]
  node_state[("State window<br/>[pipeline.h]")]
end

subgraph group_mapping["Mapping and registration"]
  node_map[("Bump-image map<br/>[bievr_map.cpp]")]
  node_sampling["Informed sampling<br/>[pipeline.cpp]"]
  node_registration["Scan registration<br/>[ls_optimizer.cpp]"]
end

subgraph group_output["ROS output"]
  node_ros1_pub["ROS1 publisher<br/>[publisher.h]"]
  node_ros2_pub["ROS2 publisher<br/>[publisher.h]"]
  node_pub_base["Shared publishing<br/>[publisher_base.h]"]
end

node_sensor(("LiDAR and IMU"))
node_bag(("Recorded bag"))
node_ros_output(("Odometry and clouds"))

node_sensor -->|"sends messages"| node_ros1_topics
node_sensor -->|"sends messages"| node_ros2_topics
node_ros1_topics -->|"converts messages"| node_conversions
node_ros2_topics -->|"converts messages"| node_conversions
node_conversions -->|"returns sensor data"| node_ros1_topics
node_conversions -->|"returns sensor data"| node_ros2_topics
node_ros1_topics -->|"adds sensor data"| node_sync
node_ros2_topics -->|"adds sensor data"| node_sync
node_bag -->|"provides recording"| node_ros1_bag
node_bag -->|"provides recording"| node_ros2_bag
node_ros1_bag -->|"feeds messages"| node_sync
node_ros2_bag -->|"feeds messages"| node_sync
node_sync -->|"dispatches frames"| node_pipeline
node_pipeline -->|"filters scans"| node_preprocess
node_pipeline -->|"undistorts scans"| node_undistort
node_pipeline -->|"integrates IMU"| node_imu
node_pipeline -->|"initializes map"| node_map
node_pipeline -->|"samples source"| node_sampling
node_sampling -->|"queries geometry"| node_map
node_pipeline -->|"runs alignment"| node_registration
node_registration -->|"matches against"| node_map
node_pipeline -->|"updates states"| node_state
node_pipeline -->|"optimizes with"| node_inertial_factor
node_pipeline -->|"adds priors"| node_prior_factor
node_ros1_bag -->|"publishes results"| node_ros1_pub
node_ros1_topics -->|"publishes results"| node_ros1_pub
node_ros2_bag -->|"publishes results"| node_ros2_pub
node_ros2_topics -->|"publishes results"| node_ros2_pub
node_ros1_pub -->|"uses backend"| node_pub_base
node_ros2_pub -->|"uses backend"| node_pub_base
node_pub_base -->|"emits messages"| node_ros_output

click node_ros1_topics "https://github.com/ethz-asl/bievr-lio/blob/main/interfaces/ros1/src/process_topics.cpp"
click node_ros1_bag "https://github.com/ethz-asl/bievr-lio/blob/main/interfaces/ros1/src/process_bag.cpp"
click node_ros2_topics "https://github.com/ethz-asl/bievr-lio/blob/main/interfaces/ros2/src/process_topics.cpp"
click node_ros2_bag "https://github.com/ethz-asl/bievr-lio/blob/main/interfaces/ros2/src/process_bag.cpp"
click node_conversions "https://github.com/ethz-asl/bievr-lio/blob/main/interfaces/ros_common/include/bievr_ros_common/conversions.h"
click node_sync "https://github.com/ethz-asl/bievr-lio/blob/main/BIEVR/src/synchronizer.cpp"
click node_pipeline "https://github.com/ethz-asl/bievr-lio/blob/main/BIEVR/src/pipeline.cpp"
click node_preprocess "https://github.com/ethz-asl/bievr-lio/blob/main/BIEVR/src/preprocess.cpp"
click node_undistort "https://github.com/ethz-asl/bievr-lio/blob/main/BIEVR/src/undistort.cpp"
click node_imu "https://github.com/ethz-asl/bievr-lio/blob/main/BIEVR/src/imu_integrator.cpp"
click node_inertial_factor "https://github.com/ethz-asl/bievr-lio/blob/main/BIEVR/src/inertial_factor.cpp"
click node_prior_factor "https://github.com/ethz-asl/bievr-lio/blob/main/BIEVR/src/prior_factor.cpp"
click node_map "https://github.com/ethz-asl/bievr-lio/blob/main/BIEVR/src/bievr_map.cpp"
click node_sampling "https://github.com/ethz-asl/bievr-lio/blob/main/BIEVR/src/pipeline.cpp"
click node_registration "https://github.com/ethz-asl/bievr-lio/blob/main/BIEVR/src/ls_optimizer.cpp"
click node_state "https://github.com/ethz-asl/bievr-lio/blob/main/BIEVR/include/bievr_lio/pipeline.h"
click node_ros1_pub "https://github.com/ethz-asl/bievr-lio/blob/main/interfaces/ros1/include/bievr_lio_ros/publisher.h"
click node_ros2_pub "https://github.com/ethz-asl/bievr-lio/blob/main/interfaces/ros2/include/bievr_lio_ros2/publisher.h"
click node_pub_base "https://github.com/ethz-asl/bievr-lio/blob/main/interfaces/ros_common/include/bievr_ros_common/publisher_base.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_ros1_topics,node_ros1_bag,node_ros2_topics,node_ros2_bag,node_conversions toneBlue
class node_sync,node_pipeline,node_preprocess,node_undistort,node_imu,node_inertial_factor,node_prior_factor,node_state toneAmber
class node_map,node_sampling,node_registration toneMint
class node_ros1_pub,node_ros2_pub,node_pub_base toneRose
class node_sensor,node_bag,node_ros_output toneIndigo
```

## Components

### ROS interfaces

- [ROS1 topics](https://github.com/ethz-asl/bievr-lio/blob/main/interfaces/ros1/src/process_topics.cpp): `interfaces/ros1/src/process_topics.cpp`
- [ROS1 bag](https://github.com/ethz-asl/bievr-lio/blob/main/interfaces/ros1/src/process_bag.cpp): `interfaces/ros1/src/process_bag.cpp`
- [ROS2 topics](https://github.com/ethz-asl/bievr-lio/blob/main/interfaces/ros2/src/process_topics.cpp): `interfaces/ros2/src/process_topics.cpp`
- [ROS2 bag](https://github.com/ethz-asl/bievr-lio/blob/main/interfaces/ros2/src/process_bag.cpp): `interfaces/ros2/src/process_bag.cpp`
- [Message conversion](https://github.com/ethz-asl/bievr-lio/blob/main/interfaces/ros_common/include/bievr_ros_common/conversions.h): `interfaces/ros_common/include/bievr_ros_common/conversions.h`

### State estimation

- [Sensor synchronizer](https://github.com/ethz-asl/bievr-lio/blob/main/BIEVR/src/synchronizer.cpp): `BIEVR/src/synchronizer.cpp`
- [Odometry pipeline](https://github.com/ethz-asl/bievr-lio/blob/main/BIEVR/src/pipeline.cpp): `BIEVR/src/pipeline.cpp`
- [Scan preprocessing](https://github.com/ethz-asl/bievr-lio/blob/main/BIEVR/src/preprocess.cpp): `BIEVR/src/preprocess.cpp`
- [Scan undistortion](https://github.com/ethz-asl/bievr-lio/blob/main/BIEVR/src/undistort.cpp): `BIEVR/src/undistort.cpp`
- [IMU integration](https://github.com/ethz-asl/bievr-lio/blob/main/BIEVR/src/imu_integrator.cpp): `BIEVR/src/imu_integrator.cpp`
- [Inertial factors](https://github.com/ethz-asl/bievr-lio/blob/main/BIEVR/src/inertial_factor.cpp): `BIEVR/src/inertial_factor.cpp`
- [Prior factors](https://github.com/ethz-asl/bievr-lio/blob/main/BIEVR/src/prior_factor.cpp): `BIEVR/src/prior_factor.cpp`
- [State window](https://github.com/ethz-asl/bievr-lio/blob/main/BIEVR/include/bievr_lio/pipeline.h): `BIEVR/include/bievr_lio/pipeline.h`

### Mapping and registration

- [Bump-image map](https://github.com/ethz-asl/bievr-lio/blob/main/BIEVR/src/bievr_map.cpp): `BIEVR/src/bievr_map.cpp`
- [Informed sampling](https://github.com/ethz-asl/bievr-lio/blob/main/BIEVR/src/pipeline.cpp): `BIEVR/src/pipeline.cpp`
- [Scan registration](https://github.com/ethz-asl/bievr-lio/blob/main/BIEVR/src/ls_optimizer.cpp): `BIEVR/src/ls_optimizer.cpp`

### ROS output

- [ROS1 publisher](https://github.com/ethz-asl/bievr-lio/blob/main/interfaces/ros1/include/bievr_lio_ros/publisher.h): `interfaces/ros1/include/bievr_lio_ros/publisher.h`
- [ROS2 publisher](https://github.com/ethz-asl/bievr-lio/blob/main/interfaces/ros2/include/bievr_lio_ros2/publisher.h): `interfaces/ros2/include/bievr_lio_ros2/publisher.h`
- [Shared publishing](https://github.com/ethz-asl/bievr-lio/blob/main/interfaces/ros_common/include/bievr_ros_common/publisher_base.h): `interfaces/ros_common/include/bievr_ros_common/publisher_base.h`

### Other components

- **LiDAR and IMU**
- **Recorded bag**
- **Odometry and clouds**

## Connections

- LiDAR and IMU → ROS1 topics: sends messages
- LiDAR and IMU → ROS2 topics: sends messages
- ROS1 topics → Message conversion: converts messages
- ROS2 topics → Message conversion: converts messages
- Message conversion → ROS1 topics: returns sensor data
- Message conversion → ROS2 topics: returns sensor data
- ROS1 topics → Sensor synchronizer: adds sensor data
- ROS2 topics → Sensor synchronizer: adds sensor data
- Recorded bag → ROS1 bag: provides recording
- Recorded bag → ROS2 bag: provides recording
- ROS1 bag → Sensor synchronizer: feeds messages
- ROS2 bag → Sensor synchronizer: feeds messages
- Sensor synchronizer → Odometry pipeline: dispatches frames
- Odometry pipeline → Scan preprocessing: filters scans
- Odometry pipeline → Scan undistortion: undistorts scans
- Odometry pipeline → IMU integration: integrates IMU
- Odometry pipeline → Bump-image map: initializes map
- Odometry pipeline → Informed sampling: samples source
- Informed sampling → Bump-image map: queries geometry
- Odometry pipeline → Scan registration: runs alignment
- Scan registration → Bump-image map: matches against
- Odometry pipeline → State window: updates states
- Odometry pipeline → Inertial factors: optimizes with
- Odometry pipeline → Prior factors: adds priors
- ROS1 bag → ROS1 publisher: publishes results
- ROS1 topics → ROS1 publisher: publishes results
- ROS2 bag → ROS2 publisher: publishes results
- ROS2 topics → ROS2 publisher: publishes results
- ROS1 publisher → Shared publishing: uses backend
- ROS2 publisher → Shared publishing: uses backend
- Shared publishing → Odometry and clouds: emits messages