Repository files navigation

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 withbindings in Python.

          
           ^{LIDAR                           Robotics               Robotics Libraries}

---

libpointmatcher is tested on our build system under the following:

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

Note:

• libpointmatcher reportedly works on Mac OS X (latest) and Windows (latest)

This release oflibpointmatcher introduces the integration ofnorlab-build-system (NBS) as agit 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

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

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

Seecontributing_instructions.mdfor instructions related to bug reporting, code contribution and for setting up thelibpointmatcher-build-systemon your workstation to speed up your local development workflow.

**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 foundhere, but it is suggested to use the one build for your version indoc/html.

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

You can read the latest changes in therelease notes.

To install docker related dependencies on ubuntu, execute the following

cd libpointmatcher/build_system/lpm_utility_script# Execute docker tools install script i.e. docker daemon, docker compose, docker buildxbash lpm_install_docker_tools.bash

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

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

Seeavailablelibpointmatcher image tagson dockerhub.

For beginner users unfamiliar with compiling and installing a library in Linux, you can use the provided installer script for ubuntu:

cd libpointmatcherbash libpointmatcher_dependencies_installer.bashbash libpointmatcher_installer.bash --build-system-CI-install

The first script installs all Libpointmatcher dependencies. The second script installs Libpointmatcher.The--build-system-CI-install flag tell the installer to colocate the build and the repository.If you want to install to a different location, instead use the--install-path </dir/abs/path/> flag.Use the--help flag for more options.

Although we suggest to use thetutorials, 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)

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 buildcmake ..makesudo make install

Libpointmatcher ships with a version of the Google testing frameworkGTest. Unit tests are located in theutest/ directory and are compiled with libpointmatcher (CMake variableBUILD_TESTS must be set toTRUE 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 buildutest/utest --path ../examples/data/

We mainly develop forcmake projects and we provide example files underexamples/demo_cmake/ to help you in your own project. We also provide aQT Creator example inexamples/demo_QT/, which manually lists all the dependencies in the filedemo.pro. You would need to ajust those paths to point at the appropriate locations on your system. For a more detailed procedure, check theLinking Projects to libpointmatcher section.

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 oflimited functionality support. For more details, see thetutorialImporting and Exporting Point Clouds. Example executables usingthose file formats from the command line can be found in the/examples directory and aredescribedhere in more detail.

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}}

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 fromhere.

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.

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

• European ProjectNIFTi (FP7 ICT-247870): Search and rescue project in dynamic environments. Results:video of multi-floor reconstruction andvideo of railyard reconstruction. All results with real-time computation.
• NASA AmesStereo Pipeline: Planetary reconstruction from satellite observations. Results: used for Mars, Moon, and Earth point clouds.
• Armasuisse S+T UGV research programARTOR: Development of techniques for reliable autonomous navigation of a wheeled robot in rough, outdoor terrain. Results:video of urban and dynamic 3D reconstruction andvideo 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 pageApplications And Publications.

libpointmatcher is released under a permissive BSD license. Enjoy!