README.md

May 10, 2026 · View on GitHub

Patchwork++


C++ API Python API

Video   •   Install   •   ROS2   •   Paper   •   Contact Us

animated

Patchwork++, an extension of Patchwork, is a fast, robust, and self-adaptive ground segmentation algorithm on 3D point cloud.

:open_file_folder: What's in this repo

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

Pure installation

make pyinstall

Then, you can use Patchwork++ by import pypatchworkpp, which is super simple!

Installation to run demo

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

make pyinstall_with_demo

How to run Python demos is explained here.

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 < -sensor_height - 2.0m cutoff and few-points reject, plus optional ATAT for unknown sensor heights. Often more aggressive on ground-plane noise in heavily cluttered scenes.

Python:

import pypatchworkpp as p

pp_default = p.patchworkpp(p.Parameters())          # Patchwork++
pp_classic = p.patchwork(p.PatchworkParams())       # Patchwork (classic)

ROS2:

ros2 launch patchworkpp patchworkpp.launch.py algorithm:=patchwork

:pencil: Citation

If you use our codes, please cite our paper (arXiv, IEEE Xplore)

@inproceedings{lee2022patchworkpp,
    title={{Patchwork++: Fast and robust ground segmentation solving partial under-segmentation using 3D point cloud}},
    author={Lee, Seungjae and Lim, Hyungtae and Myung, Hyun},
    booktitle={Proc. IEEE/RSJ Int. Conf. Intell. Robots Syst.},
    year={2022},
    pages={13276-13283}
}

In addition, you can also check the paper of our baseline, Patchwork. (arXiv, IEEE Xplore)

@article{lim2021patchwork,
    title={Patchwork: Concentric Zone-based Region-wise Ground Segmentation with Ground Likelihood Estimation Using a 3D LiDAR Sensor},
    author={Lim, Hyungtae and Minho, Oh and Myung, Hyun},
    journal={IEEE Robotics and Automation Letters},
    year={2021}
}

:triangular_flag_on_post: Tested Environment

  • Ubuntu 18.04 and 20.04, 22.04, and 24.04
  • macOS 14+ (Apple Silicon)
  • CMake 3.25.1 (>=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

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