{"id":24539702,"url":"https://github.com/stephlin/kcp","last_synced_at":"2025-04-15T06:25:42.420Z","repository":{"id":63412720,"uuid":"424852773","full_name":"StephLin/KCP","owner":"StephLin","description":"K-Closest Points and Maximum Clique Pruning for Efficient and Effective 3-D Laser Scan Matching (RA-L 2022)","archived":false,"fork":false,"pushed_at":"2022-11-09T11:34:30.000Z","size":1570,"stargazers_count":134,"open_issues_count":0,"forks_count":15,"subscribers_count":9,"default_branch":"main","last_synced_at":"2023-11-07T18:42:01.642Z","etag":null,"topics":["autonomous-vehicles","data-association","point-cloud-registration","point-clouds","robotics","scan-matching"],"latest_commit_sha":null,"homepage":"https://stephlin.github.io/KCP/","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/StephLin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-11-05T06:44:49.000Z","updated_at":"2023-10-16T02:18:40.000Z","dependencies_parsed_at":"2022-11-18T12:18:50.195Z","dependency_job_id":null,"html_url":"https://github.com/StephLin/KCP","commit_stats":null,"previous_names":[],"tags_count":0,"template":null,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StephLin%2FKCP","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StephLin%2FKCP/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StephLin%2FKCP/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StephLin%2FKCP/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/StephLin","download_url":"https://codeload.github.com/StephLin/KCP/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":235152337,"owners_count":18944168,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["autonomous-vehicles","data-association","point-cloud-registration","point-clouds","robotics","scan-matching"],"created_at":"2025-01-22T17:15:46.832Z","updated_at":"2025-01-22T17:15:47.542Z","avatar_url":"https://github.com/StephLin.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# KCP\n\n[![License](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg?style=flat)](https://opensource.org/licenses/BSD-3-Clause)\n[![Build](https://github.com/StephLin/KCP/actions/workflows/build-deploy.yml/badge.svg)](https://StephLin.github.io/KCP)\n\nThe official implementation of KCP: K-Closest Points and Maximum Clique Pruning\nfor Efficient and Effective 3D Laser Scan Matching, accepted for publication in\nthe IEEE Robotics and Automation Letters (RA-L).\n\n![](docs/images/snapshot.gif)\n\nKCP is an efficient and effective local point cloud registration approach\ntargeting for real-world 3D LiDAR scan matching problem. A simple (and naive)\nunderstanding is: **I**CP iteratively considers the closest point of each source\npoint, but **K**CP considers the **k** closest points of each source point in\nthe beginning, and outlier correspondences are mainly rejected by the maximum\nclique pruning method. KCP is written in **C++** and we also support **Python**\nbinding of KCP (pykcp).\n\nFor more, please refer to our paper:\n\n- Yu-Kai Lin, Wen-Chieh Lin, Chieh-Chih Wang, **K-Closest Points and Maximum Clique Pruning for Efficient and Effective 3-D Laser Scan Matching**. _IEEE Robotics and Automation Letters (RA-L)_, vol.7, no. 2, pp. 1471 -- 1477, Apr. 2022. ([paper](https://doi.org/10.1109/LRA.2021.3140130)) ([preprint](https://gpl.cs.nycu.edu.tw/Steve-Lin/KCP/preprint.pdf)) ([code](https://github.com/StephLin/KCP)) ([video](https://youtu.be/ZaDLEOz_yYc))\n\nIf you use this project in your research, please cite:\n\n```bibtex\n@article{lin2022kcp,\n  title={K-Closest Points and Maximum Clique Pruning for Efficient and Effective 3-D Laser Scan Matching},\n  author={Lin, Yu-Kai and Lin, Wen-Chieh and Wang, Chieh-Chih},\n  journal={IEEE Robotics and Automation Letters},\n  volume={7},\n  number={2},\n  pages={1471--1477},\n  year={2022},\n  doi={10.1109/LRA.2021.3140130},\n}\n```\n\nand if you find this project helpful or interesting, please **:star:Star** the\nrepository. Thank you!\n\n**Table of Contents**\n\n- [KCP](#kcp)\n  - [:package: Resources](#package-resources)\n  - [:gear: Installation](#gear-installation)\n    - [Step 1. Preparing the Dependencies](#step-1-preparing-the-dependencies)\n      - [GCC, CMake, Git, and Eigen3](#gcc-cmake-git-and-eigen3)\n      - [nanoflann](#nanoflann)\n      - [TEASER++](#teaser)\n    - [Step 2. Preparing Dependencies of Python Binding (Optional)](#step-2-preparing-dependencies-of-python-binding-optional)\n    - [Step 3. Building KCP](#step-3-building-kcp)\n      - [Without Python Binding](#without-python-binding)\n      - [With Python Binding](#with-python-binding)\n    - [Step 4. Installing KCP to the System (Optional)](#step-4-installing-kcp-to-the-system-optional)\n  - [:seedling: Examples](#seedling-examples)\n  - [:memo: Some Remarks](#memo-some-remarks)\n    - [Tuning Parameters](#tuning-parameters)\n    - [Controlling Computational Cost](#controlling-computational-cost)\n    - [Torwarding Global Registration Approaches](#torwarding-global-registration-approaches)\n  - [:gift: Acknowledgement](#gift-acknowledgement)\n\n## :package: Resources\n\n- [API Documentation](https://stephlin.github.io/KCP)\n- [Complete result of the experiment of robustness](https://gpl.cs.nycu.edu.tw/Steve-Lin/KCP/robustness.html)\n\n## :gear: Installation\n\nThe project is originally developed in **Ubuntu 18.04**, and the following\ninstruction supposes that you are using Ubuntu 18.04 as well. I am not sure if\nit also works with other Ubuntu versions or other Linux distributions, but maybe\nyou can give it a try :+1:\n\nAlso, please feel free to open an issue if you encounter any problems of the\nfollowing instruction.\n\n### Step 1. Preparing the Dependencies\n\nYou have to prepare the following packages or libraries used in KCP:\n\n1. A C++ compiler supporting C++14 and OpenMP (e.g. [GCC](https://gcc.gnu.org/) 7.5).\n2. [CMake](https://cmake.org/) \u0026#x2265; **3.11**\n3. [Git](https://git-scm.com/)\n4. [Eigen3](https://eigen.tuxfamily.org/index.php?title=Main_Page) \u0026#x2265; 3.3\n5. [nanoflann](https://github.com/jlblancoc/nanoflann)\n6. [TEASER++](https://github.com/MIT-SPARK/TEASER-plusplus) \u0026#x2265; [d79d0c67](https://github.com/MIT-SPARK/TEASER-plusplus/tree/d79d0c67)\n\n#### GCC, CMake, Git, and Eigen3\n\n```bash\nsudo apt update\nsudo apt install -y g++ build-essential libeigen3-dev git software-properties-common lsb-release\n\n# If you want to obtain newer version of cmake, run the following commands: (Ref: https://apt.kitware.com/)\n# wget -O - https://apt.kitware.com/keys/kitware-archive-latest.asc 2\u003e/dev/null | gpg --dearmor - | sudo tee /usr/share/keyrings/kitware-archive-keyring.gpg \u003e/dev/null\n# echo \"deb [signed-by=/usr/share/keyrings/kitware-archive-keyring.gpg] https://apt.kitware.com/ubuntu/ $(lsb_release -sc) main\" | sudo tee /etc/apt/sources.list.d/kitware.list \u003e/dev/null\n# sudo apt update\n\nsudo apt install cmake\n```\n\n#### nanoflann\n\n```bash\ncd ~\ngit clone https://github.com/jlblancoc/nanoflann\ncd nanoflann\nmkdir build \u0026\u0026 cd build\ncmake .. -DNANOFLANN_BUILD_EXAMPLES=OFF -DNANOFLANN_BUILD_TESTS=OFF\nmake\nsudo make install\n```\n\n#### TEASER++\n\n```bash\ncd ~\ngit clone https://github.com/MIT-SPARK/TEASER-plusplus\ncd TEASER-plusplus\ngit checkout d79d0c67\nmkdir build \u0026\u0026 cd build\ncmake .. -DBUILD_TESTS=OFF -DBUILD_PYTHON_BINDINGS=OFF -DBUILD_DOC=OFF\nmake\nsudo make install\n```\n\n### Step 2. Preparing Dependencies of Python Binding (Optional)\n\nThe Python binding of KCP (pykcp) uses\n[pybind11](https://github.com/pybind/pybind11) to achieve operability between\nC++ and Python. KCP will automatically download and compile pybind11 during the\ncompilation stage. However, you need to prepare a runable Python environment\nwith header files for the Python C API (python3-dev):\n\n```bash\nsudo apt install -y python3 python3-dev\n```\n\n### Step 3. Building KCP\n\nExecute the following commands to build KCP:\n\n#### Without Python Binding\n\n```bash\ngit clone https://github.com/StephLin/KCP\ncd KCP\nmkdir build \u0026\u0026 cd build\ncmake ..\nmake\n```\n\n#### With Python Binding\n\n```bash\ngit clone https://github.com/StephLin/KCP\ncd KCP\nmkdir build \u0026\u0026 cd build\ncmake .. -DKCP_BUILD_PYTHON_BINDING=ON -DPYTHON_EXECUTABLE=$(which python3)\nmake\n```\n\n### Step 4. Installing KCP to the System (Optional)\n\nThis will make the KCP library available in the system, and any C++ (CMake)\nproject can find the package by `find_package(KCP)`. Think twice before you\nenter the following command!\n\n```bash\n# Under /path/to/KCP/build\nsudo make install\n```\n\n## :seedling: Examples\n\nWe provide two examples (one for C++ and the other for Python 3) These examples\ntake nuScenes' LiDAR data to perform registration. Please check\n\n- [C++ example with CMake](examples/cpp), and\n- [Python example](examples/python)\n\nfor more information.\n\n## :memo: Some Remarks\n\n### Tuning Parameters\n\nThe major parameters are\n\n- `kcp::KCP::Params::k` and\n- `kcp::KCP::Params::teaser::noise_bound`,\n\nwhere `k` is the number of nearest points of each source point selected to be\npart of initial correspondences, and `noise_bound` is the criterion to determine\nif a correspondence is correct. In our paper, we suggest `k=2` and `noise_bound`\nthe 3-sigma (we use `noise_bound=0.06` meters for nuScenes data), and those are\ndefault values in the library.\n\nThere is also a boolean parameter to enable debug messages called\n`kcp::KCP::Params::verbose` (default: `false`).\n\nTo use different parameters to the KCP solver, please refer to the following\nsnippets:\n\n**C++**\n\n```cpp\n#include \u003ckcp/solver.hpp\u003e\n\nauto params = kcp::KCP::Params();\n\nparams.k                  = 2;\nparams.verbose            = false;\nparams.teaser.noise_bound = 0.06;\n\nauto solver = kcp::KCP(params);\n```\n\n**Python**\n\n```python\nimport pykcp\n\nparams = pykcp.KCPParams()\nparams.k = 2\nparams.verbose = False\nparams.teaser.noise_bound = 0.06\n\nsolver = pykcp.KCP(params)\n```\n\n### Controlling Computational Cost\n\nInstead of\n[correspondence-free registration in TEASER++](https://github.com/MIT-SPARK/TEASER-plusplus/issues/120),\nKCP considers k closest point correspondences to reduce the major computational\ncost of the maximum clique algorithm, and we have expressed the ability for\nreal-world scenarios without any complicate or learning-based feature descriptor\nin the paper. However, it is still possible to encounter computational time or\nmemory issue if there are too many correspondences fed to the solver.\n\nWe suggest controlling your keypoints around 500 for k=2 (in this way the\ncomputational time will be much closer to the one presented in the paper).\n\n### Torwarding Global Registration Approaches\n\nIt is promising that KCP can be extended to a global registration approach if a\nfast and reliable sparse feature point representation method is employed.\n\nIn this way, the role of RANSAC, a fast registration approach usually used in\nlearning based approaches, is similar to KCP's, but the computation results of\nKCP are deterministic, and also, KCP has better theoretical supports.\n\n## :gift: Acknowledgement\n\nThis project refers to the computation of the smoothness term defined in\n[LOAM](https://www.ri.cmu.edu/pub_files/2014/7/Ji_LidarMapping_RSS2014_v8.pdf)\n(implemented in [Tixiao Shan](https://github.com/TixiaoShan)'s excellent project\n[LIO-SAM](https://github.com/TixiaoShan/LIO-SAM), which is licensed under\nBSD-3). We modified the definition of the smoothness term (and it is called the\nmulti-scale curvature in this project).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstephlin%2Fkcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstephlin%2Fkcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstephlin%2Fkcp/lists"}