{"id":15640526,"url":"https://github.com/leonardodalinky/fpsample","last_synced_at":"2025-05-16T16:01:32.336Z","repository":{"id":194042533,"uuid":"689924061","full_name":"leonardodalinky/fpsample","owner":"leonardodalinky","description":"Python efficient farthest point sampling (FPS) library. Compatible with numpy.","archived":false,"fork":false,"pushed_at":"2024-11-07T04:10:25.000Z","size":79,"stargazers_count":116,"open_issues_count":4,"forks_count":6,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-03T17:10:01.852Z","etag":null,"topics":["farthest-point-sampling","point-cloud","python"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/leonardodalinky.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-09-11T07:34:25.000Z","updated_at":"2025-03-31T09:20:10.000Z","dependencies_parsed_at":"2024-04-10T08:24:11.493Z","dependency_job_id":"6d02b087-2574-4b91-abe9-2bbdeb450f20","html_url":"https://github.com/leonardodalinky/fpsample","commit_stats":{"total_commits":38,"total_committers":3,"mean_commits":"12.666666666666666","dds":0.1578947368421053,"last_synced_commit":"cdfec540ced830c199b4a156feacc25295b53129"},"previous_names":["leonardodalinky/fpsample"],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leonardodalinky%2Ffpsample","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leonardodalinky%2Ffpsample/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leonardodalinky%2Ffpsample/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leonardodalinky%2Ffpsample/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/leonardodalinky","download_url":"https://codeload.github.com/leonardodalinky/fpsample/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248573549,"owners_count":21126857,"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":["farthest-point-sampling","point-cloud","python"],"created_at":"2024-10-03T11:36:53.929Z","updated_at":"2025-04-12T13:34:25.033Z","avatar_url":"https://github.com/leonardodalinky.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# fpsample\n[![pypi package version badge](https://img.shields.io/pypi/v/fpsample)](https://pypi.org/project/fpsample/)\n![python version badge](https://img.shields.io/badge/python-%3E%3D3.7-blue)\n[![license badge](https://img.shields.io/github/license/leonardodalinky/fpsample)](https://github.com/leonardodalinky/fpsample/blob/main/LICENSE)\n[![star badge](https://img.shields.io/github/stars/leonardodalinky/fpsample?style=social)](https://github.com/leonardodalinky/fpsample)\n\nPython efficient farthest point sampling (FPS) library, 100x faster than `numpy` implementation.\n\n`fpsample` is coupled with `numpy` and built upon Rust pyo3 bindings. This library aims at achieving the best performance for FPS in single-threaded CPU environment.\n\n🎉 **PyTorch version with native multithreading, batch ops, Autograd and CUDA supports is in [pytorch_fpsample](https://github.com/leonardodalinky/pytorch_fpsample).**\n\n## Installation\n\n### Install from PyPI\n\n`numpy\u003e=1.16.0` is required. Install `fpsample` using pip:\n\n```shell\npip install -U fpsample\n```\n\n*NOTE: Only 64 bit package provided.*\n\nIf you encounter any installation errors, please make an issue and try to compile from source.\n\n### Build from source\n\nThe library is built using [maturin](https://github.com/PyO3/maturin). Therefore, `rust` and `cargo` are required for compiling.\n\n```shell\npip install -r requirements.txt\n```\n\nC++ compiler must support C++14. For example, `gcc\u003e=8` or `clang\u003e=5`.\n\nBuild the library and install using:\n```shell\nmaturin develop --release\n```\n\n#### Compile options\n\nFor macos users, if the compilation fails to link libstdc++, try to pass `FORCE_CXXSTDLIB=c++` as an environment variable.\n\nFor users that want larger maximum dimension support (currently set to 8), modify `build_info.rs` and compile.\n\n#### Direct porting of `QuickFPS`\n\nSee `src/bucket_fps/c_warpper.cpp` and `src/bucket_fps/_ext/` for details.\n\n## Usage\n\n```python\nimport fpsample\nimport numpy as np\n\n# Generate random point cloud\npc = np.random.rand(4096, 3)\n## sample 1024 points\n\n# Vanilla FPS\nfps_samples_idx = fpsample.fps_sampling(pc, 1024)\n\n# FPS + NPDU\nfps_npdu_samples_idx = fpsample.fps_npdu_sampling(pc, 1024)\n## or specify the windows size\nfps_npdu_samples_idx = fpsample.fps_npdu_sampling(pc, 1024, k=64)\n\n# FPS + NPDU + KDTree\nfps_npdu_kdtree_samples_idx = fpsample.fps_npdu_kdtree_sampling(pc, 1024)\n## or specify the windows size\nfps_npdu_kdtree_samples_idx = fpsample.fps_npdu_kdtree_sampling(pc, 1024, k=64)\n\n# KDTree-based FPS\nkdtree_fps_samples_idx = fpsample.bucket_fps_kdtree_sampling(pc, 1024)\n\n# NOTE: Probably the best\n# Bucket-based FPS or QuickFPS\nkdline_fps_samples_idx = fpsample.bucket_fps_kdline_sampling(pc, 1024, h=3)\n```\n\n* `FPS`: Vanilla farthest point sampling. Implemented in Rust. Achieve the same performance as `numpy`.\n* `FPS + NPDU`: Farthest point sampling with nearest-point-distance-updating (NPDU) heuristic strategy. 5x~10x faster than vanilla FPS. **Require dimensional locality and give sub-optimal answers**.\n* `FPS + NPDU + KDTree`: Farthest point sampling with NPDU heuristic strategy and KDTree. 3x~8x faster than vanilla FPS. Slightly slower than `FPS + NPDU`. But **DOES NOT** require dimensional locality.\n* `KDTree-based FPS`: A farthest point sampling algorithm based on KDTree. About 40~50x faster than vanilla FPS.\n* `Bucket-based FPS` or `QuickFPS`: A bucket-based farthest point sampling algorithm. About 80~100x faster than vanilla FPS. Require an additional hyperparameter for the height of the KDTree. In practice, `h=3` or `h=5` is recommended for small data, `h=7` is recommended for medium data, and `h=9` for extremely large data.\n\n\u003e **NOTE**: 🔥 In most cases, `Bucket-based FPS` is the best choice, with proper hyperparameter setting.\n\n### Determinism\n\nFor deterministic results, fix the first sampled point index by passing the `start_idx` parameter.\n```python\nkdline_fps_samples_idx = fpsample.bucket_fps_kdline_sampling(pc, 1024, h=3, start_idx=0)\n```\n\n**OR** set the random seed before calling the function.\n```python\nnp.random.seed(42)\n```\n\n## Performance\nSetup:\n  - CPU: Intel(R) Core(TM) i9-10940X CPU @ 3.30GHz\n  - RAM: 128 GiB\n  - SYSTEM: Ubuntu 22.04.3 LTS\n\nRun benchmark:\n```shell\npytest bench/ --benchmark-columns=mean,stddev --benchmark-sort=mean\n```\n\nResults:\n```\n---------------- benchmark '1024 of 4096': 7 tests -----------------\nName (time in ms)                   Mean            StdDev\n--------------------------------------------------------------------\ntest_bucket_fps_kdline_4k_h5      1.9469 (1.0)      0.0354 (1.54)\ntest_bucket_fps_kdline_4k_h3      2.0028 (1.03)     0.0750 (3.27)\ntest_fps_npdu_4k                  3.3361 (1.71)     0.0229 (1.0)\ntest_bucket_fps_kdline_4k_h7      3.6899 (1.90)     0.0548 (2.39)\ntest_bucket_fps_kdtree_4k         6.5072 (3.34)     0.4018 (17.52)\ntest_fps_npdu_kdtree_4k          12.3689 (6.35)     0.0380 (1.66)\ntest_vanilla_fps_4k              14.1073 (7.25)     0.4171 (18.20)\n--------------------------------------------------------------------\n\n----------------- benchmark '4096 of 50000': 7 tests -----------------\nName (time in ms)                     Mean            StdDev\n----------------------------------------------------------------------\ntest_bucket_fps_kdline_50k_h7      25.7244 (1.0)      0.5605 (1.0)\ntest_bucket_fps_kdline_50k_h5      30.0820 (1.17)     0.5973 (1.07)\ntest_bucket_fps_kdline_50k_h3      59.9939 (2.33)     1.0208 (1.82)\ntest_bucket_fps_kdtree_50k         98.2151 (3.82)     5.1610 (9.21)\ntest_fps_npdu_50k                 129.3240 (5.03)     0.5638 (1.01)\ntest_fps_npdu_kdtree_50k          287.4457 (11.17)    8.5040 (15.17)\ntest_vanilla_fps_50k              794.4958 (30.88)    5.2105 (9.30)\n----------------------------------------------------------------------\n\n------------------- benchmark '50000 of 100000': 7 tests -------------------\nName (time in ms)                         Mean              StdDev\n----------------------------------------------------------------------------\ntest_bucket_fps_kdline_100k_h7        247.6833 (1.0)        4.8640 (6.85)\ntest_bucket_fps_kdline_100k_h5        393.8612 (1.59)       3.8099 (5.37)\ntest_bucket_fps_kdtree_100k           419.4466 (1.69)       8.5836 (12.09)\ntest_bucket_fps_kdline_100k_h9        437.0670 (1.76)       2.8537 (4.02)\ntest_fps_npdu_100k                  2,990.6574 (12.07)      0.7101 (1.0)\ntest_fps_npdu_kdtree_100k           4,236.8786 (17.11)      3.3208 (4.68)\ntest_vanilla_fps_100k              20,131.7747 (81.28)    155.4407 (218.91)\n----------------------------------------------------------------------------\n```\n\n## Reference\nThe nearest-point-distance-updating (NPDU) heuristic strategy is proposed in the following paper:\n```bibtex\n@INPROCEEDINGS{Li2022adjust,\n  author={Li, Jingtao and Zhou, Jian and Xiong, Yan and Chen, Xing and Chakrabarti, Chaitali},\n  booktitle={2022 IEEE Workshop on Signal Processing Systems (SiPS)},\n  title={An Adjustable Farthest Point Sampling Method for Approximately-sorted Point Cloud Data},\n  year={2022},\n  volume={},\n  number={},\n  pages={1-6},\n  doi={10.1109/SiPS55645.2022.9919246}\n}\n```\n\nBucket-based farthest point sampling (QuickFPS) is proposed in the following paper. The implementation is based on the author's [Repo](https://github.com/hanm2019/bucket-based_farthest-point-sampling_CPU). To port the implementation to other C++ program, check [this](https://github.com/leonardodalinky/fpsample/tree/main/src/bucket_fps/_ext) for details.\n```bibtex\n@article{han2023quickfps,\n  title={QuickFPS: Architecture and Algorithm Co-Design for Farthest Point Sampling in Large-Scale Point Clouds},\n  author={Han, Meng and Wang, Liang and Xiao, Limin and Zhang, Hao and Zhang, Chenhao and Xu, Xiangrong and Zhu, Jianfeng},\n  journal={IEEE Transactions on Computer-Aided Design of Integrated Circuits and Systems},\n  year={2023},\n  publisher={IEEE}\n}\n```\n\nThanks to the authors for their great work.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleonardodalinky%2Ffpsample","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fleonardodalinky%2Ffpsample","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleonardodalinky%2Ffpsample/lists"}