Metadata-Version: 2.2
Name: genz-icp
Version: 0.3.0
Summary: Generalizable and degeneracy-robust LiDAR odometry
Keywords: LiDAR,Localization,Odometry,SLAM
Author-Email: Daehan Lee <daehanlee@postech.ac.kr>, Hyungtae Lim <shapelim@mit.edu>
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Other Audience
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: Unix
Classifier: Programming Language :: C++
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Project-URL: Homepage, https://github.com/cocel-postech/genz-icp
Requires-Python: >=3.8
Requires-Dist: natsort
Requires-Dist: numpy
Requires-Dist: pydantic>=2
Requires-Dist: pydantic-settings
Requires-Dist: pyquaternion
Requires-Dist: rich
Requires-Dist: tqdm
Requires-Dist: typer[all]>=0.6.0
Provides-Extra: all
Requires-Dist: open3d>=0.16; extra == "all"
Requires-Dist: polyscope>=2.4.0; extra == "all"
Requires-Dist: ouster-sdk>=0.11; extra == "all"
Requires-Dist: pyntcloud; extra == "all"
Requires-Dist: PyYAML; extra == "all"
Requires-Dist: trimesh; extra == "all"
Requires-Dist: rosbags<0.12,>=0.10; extra == "all"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Provides-Extra: visualizer
Requires-Dist: open3d>=0.13; extra == "visualizer"
Description-Content-Type: text/markdown

<div align="center">
    <h1>GenZ-ICP</h1>
    <a href="https://github.com/cocel-postech/genz-icp/releases"><img src="https://img.shields.io/github/v/release/cocel-postech/genz-icp?label=version" /></a>
    <a href="https://github.com/cocel-postech/genz-icp/blob/master/LICENSE"><img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License: MIT" /></a>
    <a href="https://github.com/cocel-postech/genz-icp"><img src="https://img.shields.io/badge/Linux-FCC624?logo=linux&logoColor=black" /></a>
    <a href="https://github.com/cocel-postech/genz-icp"><img src="https://img.shields.io/badge/Windows-0078D6?logo=windows&logoColor=white" /></a>
    <a href="https://github.com/cocel-postech/genz-icp"><img src="https://img.shields.io/badge/mac%20os-000000?logo=apple&logoColor=white" /></a>
    <br />
    <br />
    <a href="https://www.youtube.com/watch?v=EyTJbdC_AA4">Demo</a>
    <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
    <a href="https://github.com/cocel-postech/genz-icp/blob/master/README.md#install">Install</a>
    <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
    <a href="https://github.com/cocel-postech/genz-icp/tree/master/ros">ROS</a>
    <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
    <a href="https://arxiv.org/abs/2411.06766">Paper</a>
    <span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>
    <a href="https://github.com/cocel-postech/genz-icp/issues">Contact Us</a>
  <br />
  <br />

[GenZ-ICP](https://arxiv.org/abs/2411.06766) is a **Generalizable and Degeneracy-Robust LiDAR Odometry Using an Adaptive Weighting**
</div>

<hr />

## Install

```sh
pip install genz-icp
```

If you also want to install all the *(optional)* dependencies, like Open3D/Polyscope for visualization:

```sh
pip install "genz-icp[all]"
```

## Running the system

Next, follow the instructions on how to run the system by typing:

```sh
genz_icp_pipeline --help
```

This should print a help message with supported dataloaders and options.

### Config

You can generate a default config `genz_icp.yaml` by typing:

```sh
genz_icp_dump_config
```

Now, you can modify the parameters and pass the file to `--config` when running `genz_icp_pipeline` as follows:

```sh
genz_icp_pipeline --config /path/to/genz_icp.yaml --visualize /path/to/data --topic /pointcloud_topic
```

### Built-in pre-tuned configs (installed with pip)

Pre-tuned YAML files are packaged together with `genz-icp`, so you can use them by filename directly.

Available pre-tuned configs:

- `corridor.yaml`: Ground-Challenge dataset, `Corridor1` and `Corridor2` sequences (topic: `/velodyne_points`)
- `exp07.yaml`: Hilti-Oxford dataset, `Exp07` sequence (topic: `/hesai/pandar`)
- `kitti.yaml`: KITTI odometry dataset (topic: `/velodyne_points`)
- `long_corridor.yaml`: SubT-MRS dataset, `Long_Corridor` sequence (topic: `/velodyne_points`)
- `newer_college.yaml`: Newer College dataset, `01_short_experiment`, `02_long_experiment`, `07_parklandmount` sequences (topic: `/os1_cloud_node/points`)
- `indoor.yaml`: General indoor environments (topic set by user input)
- `outdoor.yaml`: General outdoor environments (topic set by user input)

Example:

```sh
genz_icp_pipeline --config long_corridor.yaml --visualize /path/to/data --topic /velodyne_points
```

You can still pass your own local YAML path:

```sh
genz_icp_pipeline --config /path/to/my_config.yaml --visualize /path/to/data --topic /pointcloud_topic
```

### Install Python API (developer mode)

If you plan to modify the code, the main requirements are a modern C++ compiler and `pip`.
In Ubuntu-based systems:

```sh
sudo apt install g++ python3-pip
```

Then clone and install editable mode:

```sh
git clone https://github.com/cocel-postech/genz-icp.git
cd genz-icp
python3 -m pip install -e ./python --no-build-isolation
```

### Install Python API (expert mode)

If you want more control over the build, install CMake and dependencies explicitly:

```sh
sudo apt install build-essential libeigen3-dev libtbb-dev pybind11-dev ninja-build
```

## :pencil: Citation

If you use our codes, please cite our paper ([arXiv][arXivLink], [IEEE *Xplore*][genzicpIEEElink])
```
@ARTICLE{lee2024genzicp,
  author={Lee, Daehan and Lim, Hyungtae and Han, Soohee},
  journal={IEEE Robotics and Automation Letters (RA-L)}, 
  title={{GenZ-ICP: Generalizable and Degeneracy-Robust LiDAR Odometry Using an Adaptive Weighting}}, 
  year={2025},
  volume={10},
  number={1},
  pages={152-159},
  keywords={Localization;Mapping;SLAM},
  doi={10.1109/LRA.2024.3498779}
}
```

[genzicpIEEElink]: https://ieeexplore.ieee.org/document/10753079

## :sparkles: Contributors

Like [KISS-ICP](https://github.com/PRBonn/kiss-icp),
we envision GenZ-ICP as a community-driven project, we love to see how the project is growing thanks to the contributions from the community. We would love to see your face in the list below, just open a Pull Request!

<a href="https://github.com/cocel-postech/genz-icp/graphs/contributors">
  <img src="https://contrib.rocks/image?repo=cocel-postech/genz-icp" />
</a>

## :pray: Acknowledgement

Many thanks to KISS team—[Ignacio Vizzo][nacholink], [Tiziano Guadagnino][guadagninolink], [Benedikt Mersch][merschlink]—to provide outstanding LiDAR odometry codes!

Please refer to [KISS-ICP][kissicplink] for more information

[nacholink]: https://github.com/nachovizzo
[guadagninolink]: https://github.com/tizianoGuadagnino
[merschlink]: https://github.com/benemer
[kissicplink]: https://github.com/PRBonn/kiss-icp

## :mailbox: Contact information

If you have any questions, please do not hesitate to contact us
* [Daehan Lee][dhlink] :envelope: daehanlee `at` postech `dot` ac `dot` kr
* [Hyungtae Lim][htlink] :envelope: shapelim `at` mit `dot` edu

[dhlink]: https://github.com/Daehan2Lee
[htlink]: https://github.com/LimHyungTae
