adam-urbanczyk / pico_tree

PicoTree is a C++ header only library with Python bindings for nearest neighbor searches and range searches using a KdTree.

PicoTree

PicoTree is a C++ header only library with Python bindings for nearest neighbor searches and range searches using a KdTree.

See the table below to get an impression of the performance provided by the KdTree of this library versus several other implementations:

	Build C++	Build Python	Knn C++	Knn Python
nanoflann v1.3.2	3.6s	...	5.2s	...
SciPy KDTree v1.5.0	...	117.9s	...	+inf
SciPy cKDTree v1.5.0	...	9.6s	...	14.1s
Scikit-learn KDTree 0.22.2	...	27.1s	...	55.4s
PicoTree KdTree v0.6.0	2.0s	2.1s	3.1s	4.1s

The comparison was generated using 13729039 3d points from a LiDAR scan, float64, with k=1 for queries and OMP_NUM_THREADS=1. Note that a different C++ back-end was used for each of the Knn C++ and Knn Python benchmarks. This means that they shouldn't be compared directly. See the Python comparison for more details. A more detailed C++ comparison of PicoTree is available with respect to nanoflann.

Available under the MIT license.

Capabilities

• KdTree
  • Nearest neighbors, approximate nearest neighbors, radius, and box searches.
  • Customizable nearest neighbor searches, metrics and tree splitting techniques.
  • Compile time and run time known dimensions.
  • Static tree builds.
  • Thread safe queries.

The examples show how PicoTree can be used:

• How to create the expected point and point set interfaces.
• Searching using the KdTree and creating a custom search visitor.
• Support for Eigen data types.
• Using the KdTree with Python.

Requirements

Minimum:

• A compiler that is compliant with the C++11 standard or higher.
• CMake. It is also possible to just copy and paste the pico_tree directory into an include directory.

Optional:

• Doxygen. Needed for generating documentation.
• Google Test. Used for running unit tests.
• Eigen. To run the example that shows how Eigen data types can be used in combination with PicoTree.
• nanoflann, Google Benchmark and a compiler that is compliant with the C++17 standard are needed to run the comparison benchmark between nanoflann and PicoTree.

Python bindings:

• Python. Version 3.5 or higher.
• pybind11. Used to ease the creation of Python bindings. Available under the BSD license and copyright.
• OpenMP. For parallelization of queries.
• numpy. Points and search results are represented by ndarrays.
• scikit-build. Glue between CMake and setuptools.

Build

Build using CMake:

$ mkdir build && cd build
$ cmake ../
$ make
$ make install
$ make pico_tree_doc

Similarly with MSYS2 and MinGW64:

$ ...
$ cmake.exe ../ -G "MinGW Makefiles" -DCMAKE_INSTALL_PREFIX=C:/msys64/mingw64/local
$ mingw32-make.exe
$ ...

find_package(PicoTree REQUIRED)

add_executable(myexe main.cpp)
target_link_libraries(myexe PUBLIC PicoTree::PicoTree)

Install with pip3:

$ pip3 install ./pico_tree

Set a generator for use with MinGW:

$ pip3 install ./pico_tree --install-option="-GMinGW Makefiles"

References

• Computational Geometry - Algorithms and Applications. Mark de Berg, Otfried Cheong, Marc van Kreveld, and Mark Overmars, Springer-Verlag, third edition, 2008.
• S. Maneewongvatana and D. M. Mount. It's okay to be skinny, if your friends are fat. 4th Annual CGC Workshop on Computational Geometry, 1999.
• S. Arya and H. Y. Fu. Expected-case complexity of approximate nearest neighbor searching. InProceedings of the 11th ACM-SIAM Symposium on Discrete Algorithms, 2000.
• https://en.wikipedia.org/wiki/K-d_tree