patchwork-plusplus

:open_file_folder: What's in this repo

• C++ source code of Patchwork++ (patchworkpp)
• Python binding of Patchwork++ using pybind11 (python_wrapper)
• Examples codes of C++, Python, and ROS2 :thumbsup:
• Full suppor of a reproducible SemanticKITTI evaluation harness for both Patchwork and Patchwork++ (python/examples/evaluate_semantickitti.py). In the papers of Patchwork and Patchwork++, we use different evaluation protocols — see USAGE.md §1 for why and §4 for per-sequence numbers.

If you are familiar with ROS1, you can also visit here and try executing ROS1-based Patchwork++!

:package: Prerequisite packages

What we need are just minimal dependencies.

Ubuntu / Debian:

sudo apt-get install g++ build-essential libeigen3-dev python3-pip python3-dev cmake -y

macOS (Apple Silicon or Intel):

brew install cmake

Eigen is fetched automatically by CMake, so no extra system package is required on macOS. The build works with the bundled AppleClang toolchain.

:gear: How to build & Run

Python

The released library is on PyPI:

pip install pypatchworkpp                # core library
pip install 'pypatchworkpp[demo]'        # + Open3D for the visual demos

Then import pypatchworkpp in your script — see the Python examples.

Build from source (contributors / unreleased main)

make pyinstall                # equivalent to `pip install ./python/`
make pyinstall_with_demo      # also installs Open3D >= 0.17.0

C++

Pure installation

make cppinstall

Installation with demo

Only Open3D (> 0.17.0) is additionally installed for visualization purposes.

make cppinstall_with_demo

How to run the C++ demos is explained here.

ROS2

You should not need any extra dependency, just clone and build:

mkdir -p ~/ros2_ws/src
cd ~/ros2_ws/src
git clone https://github.com/url-kaist/patchwork-plusplus.git
cd ~/ros2_ws
colcon build --packages-select patchworkpp
source ./install/setup.bash

How to launch ROS2 nodes is explained here.

:compass: Choosing an algorithm

This repository ships two ground segmentation algorithms with the same input/output API. Pick the one that fits your data:

• Patchwork++ (default): adaptive elevation/flatness thresholds, RNR (intensity-based reflected noise removal), RVPF (vertical structure suppression), and TGR (probability-based ground revert). Best when the LiDAR has reflection artefacts or you want self-tuning thresholds.
• Patchwork (classic, since 1.1.0): fixed elevation/flatness thresholds with explicit `z =3.20, min. Required to install Open3D)
  • In scripts/install_open3d.bash, the installation of the higher version of CMake is already implemented.
• Open3D 0.15.2 0.18.0
• pybind11 v2.2.3
• Eigen 3.3.7

:mailbox: Contact Information

If you have any questions, please do not hesitate to contact us

• Seungjae Lee :envelope: sj98lee at kaist ac kr
• Hyungtae Lim :envelope: shapelim at kaist ac kr

Todo List

• [ ] Support intensity for RNR in master branch
• [ ] Support Patchwork mode for users who use this repository for baseline comparison purposes
• [ ] Integrate TBB and optimize the performance