nanoflann

Distro	Build dev	Build releases	Stable version
ROS 2 Humble (u22.04)
ROS 2 Jazzy (u24.04)
ROS 2 Kilted (u24.04)
ROS 2 Lyrical (u26.04)
ROS 2 Rolling (u26.04)

(Binary build badges are for amd64 and arm64, respectively)

1. About

nanoflann is a C++11 header-only library for building KD-Trees of datasets with different topologies: R², R³ (point clouds), SO(2) and SO(3) (2D and 3D rotation groups). No support for approximate NN is provided. nanoflann does not require compiling or installing. You just need to #include <nanoflann.hpp> in your code.

This library is a fork of the flann library by Marius Muja and David G. Lowe, and born as a child project of MRPT. Following the original license terms, nanoflann is distributed under the BSD license. Please, for bugs use the issues button or fork and open a pull request.

Cite as:

@misc{blanco2014nanoflann,
  title        = {nanoflann: a {C}++ header-only fork of {FLANN}, a library for Nearest Neighbor ({NN}) with KD-trees},
  author       = {Blanco, Jose Luis and Rai, Pranjal Kumar},
  howpublished = {\url{https://github.com/jlblancoc/nanoflann}},
  year         = {2014}
}

See the release CHANGELOG for a list of project changes.

1.1. Obtaining the code

• Easiest way: clone this GIT repository and take the include/nanoflann.hpp file for use where you need it.
• Debian or Ubuntu (21.04 or newer) users can install it simply with:

  $ sudo apt install libnanoflann-dev
  

• macOS users can install nanoflann with Homebrew with:

  $ brew install brewsci/science/nanoflann
  

or

  $ brew tap brewsci/science
  $ brew install nanoflann
  

MacPorts users can use:

  $ sudo port install nanoflann
  

• Linux users can also install it with Linuxbrew with: brew install homebrew/science/nanoflann
• List of stable releases. Check out the CHANGELOG

Although nanoflann itself doesn’t have to be compiled, you can build some examples and tests with:

$ sudo apt-get install build-essential cmake libgtest-dev libeigen3-dev
$ mkdir build && cd build && cmake ..
$ make && make test

1.2. C++ API reference

• Browse the Doxygen documentation.

• Important note: If L2 norms are used, notice that search radius and all passed and returned distances are actually squared distances.

1.3. Code examples

• KD-tree look-up with knnSearch() and radiusSearch(): pointcloud_kdd_radius.cpp
• KD-tree look-up on a point cloud dataset: pointcloud_example.cpp
• KD-tree look-up on a dynamic point cloud dataset: dynamic_pointcloud_example.cpp
• KD-tree look-up on a rotation group (SO2): SO2_example.cpp
• KD-tree look-up on a rotation group (SO3): SO3_example.cpp
• KD-tree look-up on a point cloud dataset with an external adaptor class: pointcloud_adaptor_example.cpp
• KD-tree look-up directly on an Eigen::Matrix<>: matrix_example.cpp
• KD-tree look-up directly on std::vector<std::vector<T> > or std::vector<Eigen::VectorXd>: vector_of_vectors_example.cpp
• Example with a Makefile for usage through pkg-config (for example, after doing a “make install” or after installing from Ubuntu repositories): example_with_pkgconfig/
• Example of how to build an index and save it to disk for later usage: saveload_example.cpp
• GUI examples (requires mrpt-gui, e.g. sudo apt install libmrpt-gui-dev):
  • nanoflann_gui_example_R3

1.4. Why a fork?

• Execution time efficiency:
  • The power of the original flann library comes from the possibility of choosing between different ANN algorithms. The cost of this flexibility is the declaration of pure virtual methods which (in some circumstances) impose run-time penalties. In nanoflann all those virtual methods have been replaced by a combination of the Curiously Recurring Template Pattern (CRTP) and inlined methods, which are much faster.
  • For radiusSearch(), there is no need to make a call to determine the number of points within the radius and then call it again to get the data. By using STL containers for the output data, containers are automatically resized.
  • Users can (optionally) set the problem dimensionality at compile-time via a template argument, thus allowing the compiler to fully unroll loops.

File truncated at 100 lines see the full file

Changelog for package nanoflann

1.11.0 (2026-07-31)

• Merge pull request #309 from jlblancoc/feat/incremental-index-save-load Add saveIndex()/loadIndex() to the incremental k-d tree index
• Tests: cover loadIndex()'s remaining validation branches Version mismatch, type-size mismatch, dimensionality mismatch, and truncated/EOF node data, each isolated by corrupting exactly the field the corresponding check inspects. Addresses the patch-coverage gaps left by the previous commit.
• Add saveIndex()/loadIndex() to the incremental k-d tree index KDTreeSingleIndexIncrementalAdaptor could not previously be persisted: it never populates the base class's root_node_/vAcc_, so the inherited saveIndex()/loadIndex() were silent no-ops for it. Serialize the tree topology explicitly, field by field, instead of a raw struct byte-dump (safe regardless of DIM being compile-time fixed or runtime): per node, only ptIdx, divfeat, deleted, treeDeleted and child-presence bits are written. Bounding box, subtree_size, invalid_count, the coordinate cache and parent links are all structural invariants, so they are recomputed on load instead of trusted from the file. Uses a magic number distinct from the static index's SAVE_MAGIC so loading the wrong kind of file fails fast. The multithreaded KDTreeSingleIndexIncrementalAdaptorMT variant gets forwarding saveIndex()/loadIndex() that block on any in-flight background rebuild first.
• Merge pull request #308 from icyveins7/master Fix: correct SearchParams->SearchParameters and other data types in examples/example_with_cmake
• Apply clang-format-14 to example_with_cmake fix Co-Authored-By: Claude Sonnet 5 <<noreply@anthropic.com>>
• fix: correct SearchParams->SearchParameters and other data types in examples/example_with_cmake was probably missed when they changed type names in a4fac39
• Update README with new build status badges
• Fix arm64 badge link for ROS 2 Lyrical
• docs: fix rolling URIs
• docs: extend badge tables
• Contributors: Jose Luis Blanco-Claraco, icyveins7

1.10.1 (2026-06-09)

• Merge pull request #303 from jlblancoc/refactor/tests-smaller-files refactor: unit tests into smaller files

• refactor: unit tests into smaller files

• CHANGELOG: ported to rst format for ROS tools compatibility

• doc: update outdated COPYING dates

• docs: add readme build badges

• docs: add ROS build farm badge table to README

• Add ROS package.xml and integrate BUILD_TESTING for ROS build farm

  • package.xml: plain cmake build_type, BSD-2-Clause, libgtest-dev test_depend

  - CMakeLists.txt: include(CTest), use BUILD_TESTING guard, auto-select system GTest when ROS_VERSION env is set

  - tests/CMakeLists.txt: remove redundant project(), rename test target to nanoflann_unit_tests to avoid collisions in workspaces

• Contributors: Jose Luis Blanco-Claraco

1.10.0 (2026-06-06)

• New: Incremental self-balancing dynamic k-d tree index (KDTreeSingleIndexIncrementalAdaptor), both single-threaded and multithreaded variants (#302).
• Performance: Hoist point-length computation out of search inner loops (#301).
• Refactor: Deduplicate tree builders, harden Eigen adaptor ownership, centralize DIM dispatch with if constexpr (#297, #299, #300).
• Fix: SO2_Adaptor now returns absolute angular distance instead of signed (#298).
• Fix: saveIndex/loadIndex now include a magic+version+type-size header and throw on mismatch (#295).
• Fix: KDTreeSingleIndexDynamicAdaptor_ saveIndex/loadIndex infinite recursion (#290).
• Fix: loadIndex reading past EOF for empty indices (#287).
• Fix: duplicate-entry growth on removePoint/addPoints re-add cycles (#285).
• Fix: divideTree assertion failure with dynamic adaptor removePoint/addPoints (#283).

File truncated at 100 lines see the full file