libpointmatcher Documentation

libpointmatcher is a C++ library that implements the Iterative Closest Point (ICP) algorithm for aligning point clouds. It supports both point-to-point and point-to-plane ICP.

Key capabilities:

• Alignment: Finds the best transform $T$ such that $T * S = R$, where $R$ is the reference cloud and $S$ is the source cloud.
• Transform Types: Supports rigid transforms and similarity transforms (which include scale changes) using point-to-point ICP.
• Preprocessing: Includes a set of filters for denoising and subsampling input point clouds.
• Configuration: Can be configured via YAML files or an in-memory C++ API.
• File Support: Supports a variety of point cloud file formats.

libpointmatcher is primarily designed for 64-bit systems. Support for 32-bit systems is limited due to issues with the Eigen library.

Ubuntu

Tested on 64-bit architectures (x86 and arm64/v8):

• Ubuntu 18.04.1 LTS (bionic)
• Ubuntu 20.04 LTS (focal)
• Ubuntu 22.04 LTS (jammy)

MacOS

Tested on arm64/v8 architecture:

• MacOS 14.1.1

Windows

Windows is not officially supported. However, it is confirmed to work within the Windows Subsystem for Linux (WSL).

In libpointmatcher, transformations are encapsulated in a TransformationParameters object. This object is internally an Eigen matrix representing the transformation in homogeneous coordinates.

• For 2D transformations, this is a square 3x3 matrix.
• For 3D transformations, this is a square 4x4 matrix.

Transforming a point cloud involves left-multiplying the point cloud by this transformation matrix.

The Linear family uses an influence function that behaves linearly. For most members (except L2), the parameter k controls the width of the linear region. Once past this region, the influence function becomes null.

• L2: The ideal linear influence function; it is parameter-less and requires no tuning.
• Switchable-Constraint: Provides a smooth transition between inliers and outliers.
• Maximum Distance (MaxDist): Provides a sharp transition between inliers and outliers. It is used in Generalized-ICP (GICP).

A Voxel Grid Filter is a type of down-sampling filter. Unlike descriptive filters that add information to points, down-sampling filters reduce the total number of points in a cloud to improve computational efficiency.

How it works

The filter divides the spatial domain into a regular grid of volumetric elements called voxels. Points falling within the same voxel are combined into a single output point. There are two common methods for representing the distribution of points within a voxel:

1. Centroid (Spatial Average): The output point is the average position of all points in the voxel. This is more accurate but computationally more expensive as it scales linearly with the number of points and voxels.
2. Geometrical Center: The output point is simply the center of the voxel. This is faster but less representative of the actual point distribution.

In libpointmatcher, point clouds are encapsulated in DataPoints objects. A DataPoints object consists of four primary components:

1. Features matrix: An Eigen matrix containing point coordinates.
2. Feature Labels: A vector of human-readable labels (e.g., X, Y, Z) for the rows of the features matrix.
3. Descriptors matrix: An Eigen matrix containing additional point information (e.g., surface normals, orientation).
4. Descriptor Labels: A vector of human-readable labels identifying the descriptor rows.

Iterative Closest Point (ICP) registration finds a rigid geometric transformation to align a 'reading cloud' with a 'reference cloud'. The process follows a specific chain of operations:

1. Data Filtering: Reading and reference clouds are processed with data filters to remove noise and augment points with descriptive information (descriptors).
2. Matching: Each point in the reading cloud is associated with a point in the reference cloud.
3. Outlier Removal: A chain of outlier filters removes statistical outliers from the matches.
4. Transformation Computation: A cost function (e.g., sum of mean square distances) is minimized to solve for the optimal transformation.
5. Verification: Transformations are verified to ensure convergence towards an optimal alignment.

In libpointmatcher, this entire process is encapsulated within the PM::ICP class.

Descriptors provide extra information per point (such as sensor orientation or surface normals). Like the features matrix, descriptors are stored in an Eigen matrix where each column represents a point.

Multiple descriptors can be stored by stacking them in the rows. For example, if you have a 3D orientation and a 3D surface normal, the descriptor matrix will have 6 rows. You can identify these groups using Descriptor Labels (e.g., assigning "orientation" to the first three rows and "normal" to the next three).

Datapoint filters are independent modules applied to reading and reference point clouds before the ICP (Iterative Closest Point) process. They can be combined into sequential chains to adapt to specific alignment problems.

Purposes of Datapoint Filters:

• Noise Removal: Removing noisy points that make alignment difficult.
• Down-sampling: Removing redundant points to speed up the alignment process.
• Descriptor Augmenting: Adding descriptive information (e.g., surface normal vectors or sensor direction) to points.

Note: Datapoint filters are distinct from outlier filters, which are applied later in the ICP chain for different purposes.

The Iterative Closest Point (ICP) chain in libpointmatcher follows a specific pipeline of data processing, matching, and optimization. By default, the chain consists of the following stages:

1. Data Filters: Random sampling is applied to both reference and reading clouds (probability of 0.75).
2. Matcher: KD tree matcher (using a linear heap) finds the closest neighbor in the reference cloud.
3. Outlier Filters: A trimmed distance filter keeps the top 85% of points with the smallest distances.
4. Minimizer: Point-to-plane minimization is used to allow points to 'slide' along planes.
5. Transformation Checkers: The loop terminates based on a maximum of 40 iterations or when relative transformation motion falls below a threshold (using smoothed average differences).
6. Inspectors: None applied by default.