GenZ-LIO

Generalizable LiDAR-Inertial Odometry Beyond Confined–Open Boundaries

Youtube • Bilibili • Paper • Dataset • Install • Python • ROS

(October 7, 2026) pip installation is now live:

GenZ-LIO is designed for robust and computationally efficient LiDAR-inertial odometry across confined spaces, open environments, and transitions between them.

Python support

Process recorded data with an optional visualizer; no ROS installation is needed.

Install and run (Linux x86-64, Python 3.8–3.12)

1. Prepare the environment

Use Linux x86-64 with Python 3.8–3.12. Ubuntu 20.04, 22.04, and 24.04 provide Python 3.8, 3.10, and 3.12, respectively.

sudo apt-get update
sudo apt-get install -y python3-venv libgl1
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip

2. Install

Install all optional readers (rosbag and Ouster PCAP) and the visualizer:

python -m pip install 'genz-lio[all]'

The published wheels include the compiled C++ extension; no local C++ build or ROS installation is required. Plain pip install genz-lio installs the core and CLI.

3. Prepare configurations

The experiments/ YAMLs provide the sequence-specific configurations for reproducing the benchmark experiments in the paper. The default/ YAMLs are sensor templates for your own recordings.

Export all bundled YAMLs once, preserving their default/ and experiments/ subdirectories under configs/:

genz_lio_pipeline list-configs | while IFS= read -r config; do
    mkdir -p "configs/$(dirname "$config")"
    genz_lio_pipeline export-config "$config" "configs/$config"
done

Run this in the directory where you will run the examples below. This copies all 36 YAMLs unchanged and works with both source and wheel installations. Keep this folder for subsequent runs; there is no need to export again per sequence. Exported YAMLs are editable. Re-running the export will not overwrite existing files or your changes.

4. Run

1) For reproducing benchmark experiments (e.g., NarrowWide Handheld-A-01)

Use the experiment YAML prepared above with the NarrowWide Handheld-A-01 recording:

genz_lio_pipeline run "{path_to_bag}/{NW_Handheld-A-01}.bag" \
    --config configs/experiments/narrowwide/vlp16_handheld_a_01.yaml \
    --visualize --image-topic /camera/color/image_raw/compressed \
    --output results/narrowwide_handheld_a_01

The experiment YAML already contains the benchmark sensor topics and calibration. Obtain the dataset separately. The optional --image-topic displays the camera images recorded in this bag; omit it to run without the camera panel.

Press SPACE to start. For rosbag2, pass the recording directory instead of a .bag file. The exported YAMLs also work outside the source checkout.

▶️ All benchmark sequences: downloads and Python commands (42 sequences)

The commands use configs/experiments/ exported in the preparation step and write each sequence's trajectory to a separate output directory. All enable --visualize; --image-topic is included where the recording contains a camera stream. Omit that option to disable the preview. Camera streams are display-only. Download the full recordings with images when using the camera options below.

Bag filename labels in braces identify the sequence, not the official download filename. Substitute the actual downloaded or prepared filename; no file renaming is required. Labels ending in _pointcloud or _merged refer to the prepared inputs described below.

GEODE (7 sequences)

Dataset · Download.

Use the Alpha (Velodyne) recordings for these YAMLs. The examples select the left camera.

Stairs

genz_lio_pipeline run "{path_to_bag}/{GD_Stairs}.bag" \
    --config configs/experiments/geode/vlp16_stairs.yaml \
    --visualize --image-topic /left_camera/compressed \
    --output results/gd_stairs

Waterways-Short

genz_lio_pipeline run "{path_to_bag}/{GD_Waterways-Short}.bag" \
    --config configs/experiments/geode/vlp16_waterways_short.yaml \
    --visualize --image-topic /left_camera/compressed \
    --output results/gd_waterways_short

Waterways-Medium

genz_lio_pipeline run "{path_to_bag}/{GD_Waterways-Medium}.bag" \
    --config configs/experiments/geode/vlp16_waterways_medium.yaml \
    --visualize --image-topic /left_camera/compressed \
    --output results/gd_waterways_medium

Waterways-Long

genz_lio_pipeline run "{path_to_bag}/{GD_Waterways-Long}.bag" \
    --config configs/experiments/geode/vlp16_waterways_long.yaml \
    --visualize --image-topic /left_camera/compressed \
    --output results/gd_waterways_long

Offroad-02

genz_lio_pipeline run "{path_to_bag}/{GD_Offroad-02}.bag" \
    --config configs/experiments/geode/vlp16_offroad.yaml \
    --visualize --image-topic /left_camera/compressed \
    --output results/gd_offroad_02

Offroad-04

genz_lio_pipeline run "{path_to_bag}/{GD_Offroad-04}.bag" \
    --config configs/experiments/geode/vlp16_offroad.yaml \
    --visualize --image-topic /left_camera/compressed \
    --output results/gd_offroad_04

Offroad-07

genz_lio_pipeline run "{path_to_bag}/{GD_Offroad-07}.bag" \
    --config configs/experiments/geode/vlp16_offroad.yaml \
    --visualize --image-topic /left_camera/compressed \
    --output results/gd_offroad_07

ENWIDE (4 sequences)

Dataset · Download.

These four recordings contain no Image/CompressedImage topic, so the commands omit --image-topic.

Katzensee-S

genz_lio_pipeline run "{path_to_bag}/{EW_Katzensee-S}.bag" \
    --config configs/experiments/enwide/os128_enwide.yaml \
    --visualize \
    --output results/ew_katzensee_s

Katzensee-D

genz_lio_pipeline run "{path_to_bag}/{EW_Katzensee-D}.bag" \
    --config configs/experiments/enwide/os128_enwide.yaml \
    --visualize \
    --output results/ew_katzensee_d

Intersection-S

genz_lio_pipeline run "{path_to_bag}/{EW_Intersection-S}.bag" \
    --config configs/experiments/enwide/os128_enwide.yaml \
    --visualize \
    --output results/ew_intersection_s

Intersection-D

genz_lio_pipeline run "{path_to_bag}/{EW_Intersection-D}.bag" \
    --config configs/experiments/enwide/os128_enwide.yaml \
    --visualize \
    --output results/ew_intersection_d

NTU VIRAL (3 sequences)

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
LICENSES		LICENSES
cpp/genz_lio		cpp/genz_lio
docker		docker
pictures		pictures
python		python
ros		ros
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml

Sequence	YAML (`config:=`)
Stairs	experiments/geode/vlp16_stairs.yaml
Waterways-Short	experiments/geode/vlp16_waterways_short.yaml
Waterways-Medium	experiments/geode/vlp16_waterways_medium.yaml
Waterways-Long	experiments/geode/vlp16_waterways_long.yaml
Offroad-02	experiments/geode/vlp16_offroad.yaml
Offroad-04	experiments/geode/vlp16_offroad.yaml
Offroad-07	experiments/geode/vlp16_offroad.yaml

Sequence	YAML (`config:=`)
Katzensee-S	experiments/enwide/os128_enwide.yaml
Katzensee-D	experiments/enwide/os128_enwide.yaml
Intersection-S	experiments/enwide/os128_enwide.yaml
Intersection-D	experiments/enwide/os128_enwide.yaml

Sequence	YAML (`config:=`)
SPMS-01	experiments/ntu_viral/os16_spms_01.yaml
SPMS-02	experiments/ntu_viral/os16_spms_02.yaml
SPMS-03	experiments/ntu_viral/os16_spms_03.yaml

Sequence	YAML (`config:=`)
Cave-01	experiments/superloc/vlp16_cave.yaml
Cave-02	experiments/superloc/vlp16_cave.yaml
Cave-04	experiments/superloc/vlp16_cave.yaml
Corridor-02	experiments/superloc/vlp16_corridor_02.yaml

Sequence	YAML (`config:=`)
Tracked-01	experiments/narrowwide/mid70_tracked_01.yaml
Tracked-02	experiments/narrowwide/mid70_tracked_02.yaml
Handheld-A-01	experiments/narrowwide/vlp16_handheld_a_01.yaml
Handheld-A-02	experiments/narrowwide/vlp16_handheld_a_02.yaml
Handheld-B-01	experiments/narrowwide/avia_handheld_b_01.yaml
Handheld-B-02	experiments/narrowwide/avia_handheld_b_02.yaml

Sequence	YAML (`config:=`)
Long-Corridor	experiments/subt_mrs/vlp16_long_corridor.yaml
Multi-Floor	experiments/subt_mrs/vlp16_multi_floor.yaml
Laurel-Cavern	experiments/subt_mrs/vlp16_laurel_cavern.yaml

Sequence	YAML (`config:=`)
Basement-04	experiments/hilti21/mid70_hilti21_basement04.yaml
Drone-Arena	experiments/hilti21/mid70_hilti21_drone_arena.yaml

Sequence	YAML (`config:=`)
Exp-10	experiments/hilti22/pandar32_hilti22_exp10.yaml
Exp-16	experiments/hilti22/pandar32_hilti22_exp16.yaml
Exp-18	experiments/hilti22/pandar32_hilti22_exp18.yaml

Sequence	YAML (`config:=`)
Corridor-01	experiments/m3dgr/avia_corridor_01.yaml
Corridor-02	experiments/m3dgr/avia_corridor_02.yaml
GNSS-denial-01	experiments/m3dgr/avia_gnss_denial.yaml
GNSS-denial-02	experiments/m3dgr/avia_gnss_denial.yaml

Sequence	YAML (`config:=`)
christ_church-01	experiments/oxford_spires/hesai64_christ_church.yaml
christ_church-02	experiments/oxford_spires/hesai64_christ_church.yaml
christ_church-05	experiments/oxford_spires/hesai64_christ_church.yaml
blenheim_palace-01	experiments/oxford_spires/hesai64_blenheim_palace.yaml
blenheim_palace-02	experiments/oxford_spires/hesai64_blenheim_palace.yaml
blenheim_palace-05	experiments/oxford_spires/hesai64_blenheim_palace.yaml

Latest commit

History

Folders and files

Repository files navigation

GenZ-LIO

Python support

1. Prepare the environment

2. Install

3. Prepare configurations

4. Run

ROS 1 support

1. Install dependencies

2. Build GenZ-LIO

3. Run

ROS 2 support

1. Install dependencies

2. Build GenZ-LIO

3. Run

📝 Citation

✨ Contributors

🙏 Acknowledgments and license

📫 Contact

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages