[//]: # ( ==== Description ====================================================================== ) **_libpointmatcher_ is a modular library implementing the Iterative Closest Point (ICP) algorithm
for aligning point clouds. It has applications in robotics and computer vision.**
The library is written in C++ for efficiency with [bindings in Python](doc/index.md#python-).

[//]: # (====Badges===============================================================================)

[//]: # (====Awesome badges=======================================================================) [](https://github.com/szenergy/awesome-lidar#basic-matching-algorithms)       [](http://jslee02.github.io/awesome-robotics-libraries/#3d-mapping)       [](https://github.com/ahundt/awesome-robotics#point-clouds)
            ^{LIDAR                             Robotics                 Robotics Libraries}

---

Supported OS And Architecture

libpointmatcher is tested on our build system under the following architecture and OS:

• Ubuntu bionic (18.04), focal (20.04) and jammy (22.04)
• x86 and arm64/v8

Note:

• libpointmatcher reportedly works on MacOs OsX (latest) and Windows (latest)

★ Version >= 1.4.0 Release Note

This release of libpointmatcher introduces the integration of norlab-build-system (NBS) as a git submodule for codebase development and testing.

Execute the following to clone the repository with its submodule:

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

If libpointmatcher was previously cloned, execute the following to fetch its new submodule

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

★ Contributing Instructions

See contributing_instructions.md for instructions related to bug reporting, code contribution and for setting up the libpointmatcher-build-system on your workstation to speed up your local development workflow.

Documentation and Tutorials

**Quick link for the tutorial pages: Tutorials.

Those tutorials are written using Markdown syntax and stored in the project’s /doc folder. Their scope ranges from introductory material on performing point cloud registration to instructions for the more experienced developer on how to extend the library’s codebase.

Libpointmatcher’s source code is fully documented based on doxygen to provide an easy API to developers. An example of this API can be found here, but it is suggested to use the one build for your version in doc/html.

libpointmatcher was orginaly developed by François Pomerleau and Stéphane Magnenat as part of our work at ASL-ETH. It is now maintained by the Northern Robotics Laboratory (Norlab), led by François Pomerleau.

You can read the latest changes in the release notes.

Quick Start

Although we suggest to use the tutorials, here is a quick version of it:

The library has a light dependency list:

• Eigen version 3, a modern C++ matrix and linear-algebra library,
• boost version 1.48 and up, portable C++ source libraries,
• libnabo version 1.0.7, a fast K Nearest Neighbour library for low-dimensional spaces,

and was compiled on:

• Ubuntu (see how)
• Mac OS X (see how)
• Windows (see how - partially supported)

Docker images

Run the following commands to pull and run libpointmatcher in a docker container

docker pull norlabulaval/libpointmatcher:latest-ubuntu-focal

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

See available libpointmatcher image tags on dockerhub.

To install docker related dependencies on ubuntu, execute the following

cd ./build_system/lpm_utility_script

# Execute docker tools install script i.e. docker daemon, docker compose, docker buildx
bash lpm_install_docker_tools.bash

Compilation & Installation

For beginner users unfamiliar with compiling and installing a library in Linux, go here for detailed instructions on compiling libpointmatcher from the source code.

For conveniences, you can use the provided installer script for ubuntu

bash libpointmatcher_dependencies_installer.bash

# Use the --help flag to see the list of optional flag
bash libpointmatcher_installer.bash [<optional flag>]

If you are comfortable with Linux and CMake and have already installed the prerequisites above, the following commands should install libpointmatcher on your system.

mkdir build && cd build
cmake ..
make
sudo make install

Testing

Libpointmatcher ships with a version of the Google testing framework GTest. Unit tests are located in the utest/ directory and are compiled with libpointmatcher (CMake variable BUILD_TESTS must be set to TRUE before compiling). To run the tests and make sure that your compiled version is working correctly, run the test executable in your build directory:

cd build
utest/utest --path ../examples/data/

Linking to external projects.

We mainly develop for cmake projects and we provide example files under examples/demo_cmake/ to help you in your own project. We also provide a QT Creator example in examples/demo_QT/, which manually lists all the dependencies in the file demo.pro. You would need to ajust those paths to point at the appropriate locations on your system. For a more detailed procedure, check the Linking Projects to libpointmatcher section.

File formats

The library support different file formats for importing or exporting data:

• csv (Comma Separated Values)
• vtk (Visualization Toolkit Files)
• ply (Polygon File Format)
• pcd (Point Cloud Library Format)

Those functionnalities are available without increasing the list of dependencies at the expense of limited functionality support. For more details, see the tutorial Importing and Exporting Point Clouds. Example executables using those file formats from the command line can be found in the /examples directory and are described here in more detail.

Citing

If you use libpointmatcher in an academic context, please cite the following publication:

@article{Pomerleau12comp,
	author = {Pomerleau, Fran{\c c}ois and Colas, Francis and Siegwart, Roland and Magnenat, St{\'e}phane},
	title = {{Comparing ICP Variants on Real-World Data Sets}},
	journal = {Autonomous Robots},
	year = {2013},
	volume = {34},
	number = {3},
	pages = {133--148},
	month = feb
}

and/or

@INPROCEEDINGS{pomerleau11tracking,
	author = {Fran{\c c}ois Pomerleau and St{\'e}phane Magnenat and Francis Colas and Ming Liu and Roland Siegwart},
	title = {Tracking a Depth Camera: Parameter Exploration for Fast ICP},
	booktitle = {Proc. of the IEEE/RSJ International Conference on Intelligent Robots and Systems (IROS)},
	publisher = {IEEE Press},
	pages = {3824--3829},
	year = {2011}
}

Extra Reading

If you are interested in learning more about different registration algorithms, we recently put together a literature review surveying multiple solutions. The review is organized in the same way as the library and many examples are provided based on real deployments.

F. Pomerleau, F. Colas and R. Siegwart (2015), “A Review of Point Cloud Registration Algorithms for Mobile Robotics”, Foundations and Trends® in Robotics: Vol. 4: No. 1, pp 1-104. https://doi.org/10.1561/2300000035

If you don’t have access to the journal, you can download it from here.

More Point Clouds

We also produced those freely available data sets to test different registration solutions:

Challenging data sets for point cloud registration algorithms

You can download the files in CSV or VTK formats, which are directly supported by the library I/O module.

Projects and Partners

If you are using libpointmatcher in your project and you would like to have it listed here, please contact François Pomerleau.

• European Project NIFTi (FP7 ICT-247870): Search and rescue project in dynamic environments. Results: video of multi-floor reconstruction and video of railyard reconstruction. All results with real-time computation.
• NASA Ames Stereo Pipeline: Planetary reconstruction from satellite observations. Results: used for Mars, Moon, and Earth point clouds.
• Armasuisse S+T UGV research program ARTOR: Development of techniques for reliable autonomous navigation of a wheeled robot in rough, outdoor terrain. Results: video of urban and dynamic 3D reconstruction and video of open space 3D reconstruction with real-time computation.
• Swiss National Science Foundation - Limnobotics: Robotic solution for toxic algae monitoring in lacs. Result: video of 3D shore reconstruction with real-time computation.
• CGAL includes our library for their registration pipeline.
• Norlab is maintaining and using the library for its research on autonomous navigation in harsh environments.
• ANYbotics AG is investigating autonomous navigation algorithms using this library.
• Point Laz Mining LiDAR Expert is scanning mine shafts to ensure infrastructure safety.
• Point Laz Mining LiDAR Expert is scanning mine shafts to ensure infrastructure safety.
• DREAM lab use libpointmatcher to reconstruct wood logs in 3D. For a larger list of work realized with libpointmatcher, please see the page Applications And Publications.

License

libpointmatcher is released under a permissive BSD license. Enjoy!

Changelog for package libpointmatcher

1.4.4 (2024-12-16)

New features: * Added Angle Limit Datapointsfilter, which filters points if they lie inside or outside of a given spherical wedge * Added support for binary PLY files IO

Major changes: * Min. Cmake version pumped to 3.15 * Removed dependency on boost filesystem * Python bindings compile with recent versions of pybind11

Other changes: * Updated Python GitHub action * Updated gitignore * Updated docs

1.4.3 (2024-06-28)

• Class to generate point cloud primitives
• Updated documentation
• Github actions for code API
• Function that lists all available Filter parameters

1.4.2 (2024-03-23)

• Add dockerhub release logic and improve main readme by \@RedLeader962 in https://github.com/norlab-ulaval/libpointmatcher/pull/550
• Update .gitingore with auto-generated patterns for C++, Python, JetBrains IDEs ,and VSCode by \@boxanm in https://github.com/norlab-ulaval/libpointmatcher/pull/555
• build: add ubuntu jammy to the repository suported version by \@RedLeader962 in https://github.com/norlab-ulaval/libpointmatcher/pull/557
• fix: Change unit tests floating point type to double and add a precision argument to output streams by \@boxanm in https://github.com/norlab-ulaval/libpointmatcher/pull/558
• Update the minimum required Cmake version to 3.10.2 by \@boxanm in https://github.com/norlab-ulaval/libpointmatcher/pull/560
• fix: Issue 534 transformation tests failing on some platforms by \@boxanm in https://github.com/norlab-ulaval/libpointmatcher/pull/559
• Added orientation descriptor in RigidTransformation and SimilarityTransformation compute functions. by \@simonpierredeschenes in https://github.com/norlab-ulaval/libpointmatcher/pull/553

1.4.1 (2024-03-19)

• Update package.xml version properly

1.4.0 (2023-12-15)

• fix: N2ST path resolution in dependencies-doc docker image
• refactor: move libpointmatcher build-system logic to norlab-build-system submodule
• fix: build-system side unstable compilation issue fix
• Fixes to CMake library management config generation
• New DataPoints filter for descriptor augmentation Enhancement
• Fix 2D transformation tests in debug
• Fix Transformations test build when using Eigen3.4
• Disable static boost linkage by default
• Update CompilationPython.md
• Update README.md
• Update readme_test.md for docker daemon test
• Create readme_test.md
• Updated the inner loop counter
• build-system minor mod
• libpointmatcher build-system
• Fix omega descriptor export
• Handle libnabo config mode
• Build python binding as regular package
• Fix time values after applying Sampling surface normal filter
• Add seed to Random sampling filter
• Add more details in pypointmatcher's installation docs
• Fixed compilation on Visual Studio 2022
• Fix 4DoF PointToPlane error minimizer crash
• Use the LOG_INFO_STREAM macro instead of std::cerr
• package format=3
• Create LICENSE file based on BSD license as per package.xml
• catkin not required for pure cmake packages
• Histogram<T>::computeStats() without sorting the Histogram
• Windows: Fix Narrowing conversion of seed in MaxPointCount
• Change storage ordering of the eigen vectors descriptors
• Apply the transformation to eigen vectors
• Fix the surface normals datapoints filter covariance matrix bug
• Fix weird behavior of MaxPointCountDataPointsFilter
• Bug fix in SurfaceNormalOutlierFilter
• Update CompilationWindows.md
• [Matches/OutlierFiltersImpl] Made convergence error messages more informative
• RemoveBeyond option for the maxQuantileDistance filter
• refactor: Drop support for yaml-cpp old API Enhancement
• Automaticaly find eigen3
• Strong Windows installation tutorial update
• Add libpointmatcher_INCLUDE_DIR to match with CGAL
• Add Boost_LIBRARIES to pointmatcher_LIBRARIES
• Add option to weight by reading pc
• Fixes for windows
• Fix windows doc
• Include iso646.h to add and, or, not macros
• Typo in PCL lib name
• Implemented an in-place method for transforming DataPoints objects
• The keyword "or" is not supported by windows compilers.
• Link against pthread
• [DataPoints] Added check to prevent unsigned int underflow in getEuclideanDim()
• [feature/spdf] Add SpectralDecompositionFilter (SpDF)
• Fixed the differences between examples and documentation (#409)
• Fix build of downstream packages.
• Reorganization of the compiling tutorials for ubuntu and macos
• Added reference for PointToPlaneWithCov ErrorMinimizer.
• [WIP] feature/python_module : Adding libpointmatcher's Python bindings (#222) Enhancement
• Feature/speedup random sampling filter
• Replaced the remaining raw pointers with shared pointers in Registrar.h
• Adding the new outlierfilters documentation to mkdocs .yml
• Outlier filter documentation added
• Fix/typo Fixes tutorials building failure
• Fixes tutorials formatting problem (#373)
• [WIP] Fix/typo : Tutorials improvements
• Fix out-of-bounds access
• Add missing force4DOF param to PointToPlaneWithCov
• Modernize cmake; make cmake compatible with git submoduling
• Feature/4 dof for point to plane minimizer
• Feature/geometry data points filter for master
• Get rid of the Visual C++ warnings
• Change matrix type
• Update link to documentation in readme
• Fix segfault happening in ICPSequence class
• Added missing include that made windows compilation fail.
• Change icp chain image to an svg
• Add support for Travis
• Fix typo
• Improve speed of Normal Space filtering
• Fix/normal space hashing
• Fix/clamp normals

1.3.1 (2019-03-04)

• Added documentation for people using ROS.
• Increased libnabo minimal version to 1.0.7.
• Added interface to inform if maximum number of iterations was reached.
• Fixed portability issue of the FileLogger.
• Fixed unit tests on Windows.
• Fixed parameter-less modules having 'unknown' as class name.
• Updated Windows compilation tutorial.
• Fixed compilation problems on Windows.
• Fixed PointToPlan error residual.
• Changed DOI resolver link in documentation.
• Added validation for the input transformation matrix in ICP.cpp.
• Removed duplication of PointToPoint compute in PointToPointWithCov.
• Added the RemoveSensorBias filter.
• Splitted ErrorMinimizersImpl.cpp into multiple files.

1.3.0 (2018-10-26)

• Removed some boost utilities supported by c++11
• Replaced raw pointers by std smart pointers

1.2.4 (2018-10-15)

• Support of Eigen 3.3
• Introduced SurfaceNormalDataPointsFilter, OctreeGridDataPointsFilter and NormalSpaceDataPointsFilter
• A lot of bugs were fixed

1.2.3 (2015-05-15)

• Support including other versions of YAML in compilation units that also include the YAML version packed with libpointmatcher (PR #80)
• Changed immutability concept for SupportLabel to support MSVC 2012 (#78)
• Fixed build system related bugs (#79, #70, ..).
• updated build_map example, added better error message, added better information prints
• cleaned CMakeList and added missing dependencies for external projetcs
• avoid possibility of building dynamic library on MacOS
• updated Mac build instructions
• Tim3xx laser support on Simple Noise filter (#64)
• Modified default covariance return in PointToPlaneWithCovErrorMinimizer (#59)
• update usage text and retab
• Removed compilation warnings
• add unit test for ICPSequence
• added application of reference data points filters for ICPSequence objects (#56)
• Merge branch 'master' of github.com:ethz-asl/libpointmatcher
• fix problem with libnabo linking (#54)
• Adapted the code to handle 2D point clouds and decided to split the initial/icp/complete transformation matrices in 3 different files. It should be easier to post process the transformations.
• Changed matrix for matrices as output suffix
• Changed the ICP example (pmicp) to accept initial translation/rotation input and allow to output the transformation matrices
• CutBelowLevelDataPointsFilter (PR #48)
• split unit tests (PR #47)
• Delete roadmap.txt
• change year to 2014
• correct bug in DataPoints operator==
• add a method to remove features or descriptors
• add empty function for removing features and descriptors
• add functions to DataPoints avoiding error on rows and cols
• fill missing documentation
• resolve warning from unsigned to int in IO.cpp
• add extra empty line in utest
• add extra unit tests and resolve remaining bugs
• Refactored how to load PLY files
• Allow 2D descriptors (##45)
• Allow saving 2D descriptors coming from a 2Dmap, that are converted to 3D when writing to the file but needed after if we want to load the map as 2D.
• Contributors: Francis Colas, Francisco J Perez Grau, François Pomerleau, HannesSommer, Philipp Kruesi, Renaud Dube, Simon Lynen, chipironcin, pomerlef, smichaud, v01d

1.2.2 (2014-08-05)

• Yaml-cpp0.3 now built with libpointmatcher for compatibility with newer Ubuntu systems using yaml-cpp0.5

1.2.1

• Fixed bug with soft outlier weights in error minimization
• Fixed some issues for releasing into ROS ecosystem
• Contributors: François Pomerleau, Mike Bosse, Samuel Charreyron, Simon Lynen