libpointmatcher for 2D and 3D point cloud alignment

ICP registration for robotics and computer vision

libpointmatcher addresses one specific problem: aligning two point clouds so that points describing the same scene can be brought into a common coordinate frame. The README identifies Iterative Closest Point, or ICP, as the algorithm implemented by the library. That makes the project relevant to robotics applications such as mapping and computer vision workflows that process lidar or other point cloud observations.

The intended users are developers who already work with point cloud data and want a reusable C++ library rather than a complete application with a sensor driver, mapping interface, or robot controller. The project also provides Python bindings, which is useful for Python-based experiments or systems that call the native library from a higher-level environment. The repository includes examples for basic ICP, advanced API use, customized pipelines, sequence alignment, map building, overlap computation, and filtering. Those example names describe intended workflows, but the README does not claim that the library supplies a complete SLAM system or a standalone lidar pipeline.

The repository layout reinforces that it is a library project. Core implementation files are under `pointmatcher/`, Python integration is under `python/`, examples are under `examples/`, tests are under `utest/`, and documentation is under `doc/`. The `pointmatcher.pc.in`, CMake files, package metadata, Debian directory, and build-system directory indicate support for packaging and integration into larger C++ projects. This is useful for teams embedding registration in a mapping stack, but it also means deployment requires build and dependency decisions rather than downloading one complete application.

Modular C++ architecture and Python access

The central design choice is modularity. The README calls libpointmatcher a modular library implementing ICP, and the repository separates the core library, examples, Python bindings, tests, documentation, and build infrastructure. The C++ implementation is intended for efficiency, while Python bindings provide access from Python.

At the level of the algorithm, ICP repeatedly compares points in one cloud with nearby points in another, estimates a transformation, and updates the alignment. The README does not provide a detailed diagram of libpointmatcher's internal module graph, so it would be misleading to claim a particular control-flow design beyond that documented ICP purpose. The dependency on `libnabo`, described as a fast K Nearest Neighbour library for low-dimensional spaces, is consistent with point cloud matching, while Eigen provides matrix and linear algebra support and Boost provides portable C++ libraries.

The examples expose several levels of use. `examples/icp.cpp`, `icp_simple.cpp`, and `icp_advance_api.cpp` provide different ICP entry points, while `icp_customized.cpp` indicates that applications can customize behavior. `align_sequence.cpp` and `build_map.cpp` target broader point cloud workflows, and `compute_overlap.cpp` addresses overlap between point clouds. A `filterProfiler.cpp` example is also present. The README does not explain every module or configuration parameter, so the exact pipeline ordering, convergence criteria, and transformation conventions must be checked in the version-specific documentation and source before integration.

Ubuntu installation with the Docker image

The README gives a documented Docker path for Ubuntu users. First, install Docker-related dependencies by entering the utility-script directory and running the supplied installer. The commands below are copied from the README. The first script installs Docker-related tools, the second pulls the published Ubuntu Focal image, and the next starts it in an interactive container.

cd libpointmatcher/build_system/lpm_utility_script
bash lpm_install_docker_tools.bash

The first block changes into the utility-script directory and runs the project's Docker tools installer.

docker pull norlabulaval/libpointmatcher:latest-ubuntu-focal

This pulls the latest Ubuntu Focal image published under the documented Docker Hub name.

docker run -it --rm norlabulaval/libpointmatcher:latest-ubuntu-focal

The final command starts the image interactively and removes the container when the session ends. The README links to the Docker Hub image tags for other available versions, so production users should not assume that `:latest-ubuntu-focal` is the correct tag for their deployment.

Native Ubuntu and CMake installation

For users compiling from source, the README provides installer scripts for Ubuntu. Run the dependency installer before the libpointmatcher installer. The second command uses the documented `--build-system-CI-install` option, which places the build beside the repository. The README also documents `--install-path </dir/abs/path/>` for a different destination and `--help` for other options.

Before using these commands, clone the repository with its submodules. Version 1.4.0 and later integrate norlab-build-system as a git submodule, so omitting that part of the clone can leave the documented build system incomplete.

git clone --recurse-submodules https://github.com/norlab-ulaval/libpointmatcher.git

This clones the repository and its submodules in one operation.

cd libpointmatcher
bash libpointmatcher_dependencies_installer.bash
bash libpointmatcher_installer.bash --build-system-CI-install

These commands install the documented dependencies and build the project with the repository-colocated build option. If the repository was cloned earlier without submodules, the README documents this command:

git submodule update --remote --recursive --init

The source build also depends on Eigen version 3, Boost version 1.48 or newer, and libnabo version 1.0.7. The README lists Ubuntu 18.04, 20.04, and 22.04 as tested, with x86 and arm64/v8 architectures. It reports that macOS and Windows work, but Windows support is described as partial. The README points to separate compilation documentation for Ubuntu, Mac OS X, and Windows, rather than defining one universal package-manager sequence.

First use through the C++ examples

The repository includes a set of examples that provide the clearest first real use. The README links to the tutorials and describes them as covering point cloud registration through extension of the library. It also points to `examples/` for concrete programs. A new user can build the project and inspect the simple ICP example, but the README excerpt does not include the exact build command, input file names, command-line arguments, or expected output for that example.

That limitation matters. The presence of `examples/icp_simple.cpp` confirms that a simple starting point exists, but it does not let this article invent a compile or invocation command. The documented way to proceed is to build the library using the relevant compilation instructions, then use the example source and tutorials for the precise workflow. For applications that need more than basic registration, `icp_advance_api.cpp` and `icp_customized.cpp` are the relevant starting points in the repository.

The examples directory also contains `align_sequence.cpp` and `build_map.cpp`, but those files should not be treated as proof of a complete mapping framework. Their names show that the project includes code for sequence alignment and map construction. Any team evaluating it should inspect the example dependencies and input data under `examples/data/` before assuming those programs can be run independently. The `python/` directory and `examples/python/` should also be checked when Python is the intended interface, because the README documents bindings without specifying a complete Python command line for every workflow.

Limitations for production mapping workflows

The clearest limitation is scope. libpointmatcher solves point cloud alignment through ICP, but the repository is not described as a complete mapping or robot-navigation product. There is no claim in the README that it handles sensor acquisition, time synchronization, odometry, loop closure policy, map storage, or deployment on a particular robot. Those responsibilities would need to be supplied by the surrounding system.

ICP also has a data-dependent weakness that follows from the algorithm named by the project. Point cloud registration is not automatically appropriate for scans with insufficient overlap, large initial misalignment, repeated structures, or moving objects. The README does not document convergence guarantees, failure detection, or a complete set of safeguards for those cases. Teams should not infer that a returned transformation is accurate merely because the library completed an ICP run.

Platform support is uneven in a practical sense. Ubuntu 18.04, 20.04, and 22.04 on x86 and arm64/v8 are the tested combinations listed by the README. macOS and the latest Windows are reported as working, but Windows is marked as partially supported. The library also requires native C++ dependencies, including Eigen, Boost, and libnabo. This creates more integration work than a pure Python package with no system dependencies.

License, releases, and maintenance signals

The repository uses the BSD-3-Clause license. That permits use under the license's terms, but the license text controls the actual obligations and conditions. The license identifier alone is not a substitute for reviewing the repository's `LICENSE` file for the applicable notice, disclaimer, and distribution requirements.

The listed releases include 1.4.4 on 2024-12-20, 1.4.3 on 2024-06-28, and 1.4.2 on 2024-03-26. Version 1.4.0 introduced integration of norlab-build-system as a git submodule. That change has an operational consequence: source checkouts must include submodules, as shown by the README's `git clone --recurse-submodules` command. Existing clones must fetch and initialize the submodule with the documented update command.

The repository is not archived. Its last push was on 2026-08-27. The release history and repository status indicate ongoing project work, but users still need to choose and test a release for their own environment. Upgrade cost is not documented as an automated migration tool or a formal compatibility matrix. The safer upgrade assessment is to compare the selected release, rebuild native dependencies, rerun the relevant C++ or Python tests, and verify that surrounding code follows the version-specific API.

Editorial conclusion

Adopt libpointmatcher when you need a C++ point cloud registration component and are prepared to work with its native build dependencies. Do not treat it as a turnkey mapping system. Verify first that your Ubuntu version, architecture, dependency versions, installation path, and version-specific API match the documented build.

Frequently asked questions

Official sources

1. License: BSD-3-Clause
2. norlab-ulaval/libpointmatcher on GitHub
3. Project website
4. README
5. Releases