probreg

The probreg package is organized into several specialized modules for point cloud registration and processing. Key modules include:

• cpd: Coherent Point Drift (CPD) registration algorithms.
• cost_functions: Various cost functions used for registration optimization.
• filterreg: Filtering-based registration methods.
• features: Feature extraction and description tools.
• se3_op: Operations related to the SE(3) Lie group (transformations in 3D space).
• transformation: Tools for applying and managing transformations.
• gmmtree: Gaussian Mixture Model tree structures.
• gauss_transform & gaussian_filtering: Gaussian-based transformations and filtering.
• l2dist_regs: L2 distance-based registration methods.
• math_utils: General mathematical utility functions.
• callbacks: Support for callback functions during optimization processes.

Probreg implements several probabilistic point cloud registration algorithms. The available transformations (Rigid vs Non-Rigid) vary by algorithm:

Maximum Likelihood Algorithms

• Coherent Point Drift (CPD): Supports Scale + 6D pose (Rigid) and Affine, MCT (Non-Rigid).
• Extended CPD: Adds correspondence priors to CPD.
• Color CPD: Color-aware registration.
• FilterReg: Supports 6D pose (Point-to-point, Point-to-plane, FPFH-based) and experimental Deformable Kinematic (Non-Rigid).

Variational Bayesian Inference

• Bayesian CPD (BCPD): Experimental Combined model (Rigid + Scale + NonRigid-term).

Distance Minimization

• GMMReg / SVR: Supports 6D pose (Rigid) and TPS (Non-Rigid).
• GMMTree: Supports 6D pose (Rigid).

You can install probreg directly from the Git repository in editable mode. This is useful for development or if you need the latest version from the source.

$ git clone https://github.com/neka-nat/probreg.git --recurse
$ cd probreg
$ pip install -e .

To use CUDA-accelerated algorithms (such as Rigid CPD or Affine CPD), you must install cupy in your environment.

pip install cupy

You can install probreg using pip for a standard installation, or clone the repository and install it in editable mode from source.

Standard Installation

pip install probreg

Installation from Source

git clone https://github.com/neka-nat/probreg.git --recursive
cd probreg
pip install -e .

The recommended way to install probreg is using pip.

$ pip install probreg

All transformation types inherit from the Transformation abstract base class.

Key behaviors:

• transform(points, array_type): This is the primary method for users. It accepts points as a numpy array or an open3d.utility.Vector3dVector. If using Open3D vectors, it converts them to the backend array type (xp), performs the transformation, and converts them back to the original array_type.
• _transform(points): This is the internal method that subclasses must implement to define the actual mathematical operation.
• Backend Support: The xp parameter allows the transformation to run on either numpy or cupy (GPU) for accelerated computations.

The GaussTransform class uses a hybrid approach to balance accuracy and performance. It switches between two internal implementations based on the bandwidth parameter h:

1. Direct Method: Used when h < sw_h. This calculates the transform directly using the formula: $$\sum_{j} \text{weights}[j] \cdot \exp\left( - \frac{||\text{target}[i] - \text{source}[j]||^2}{h^2} \right)$$
2. IFGT (Improved Fast Gauss Transform): Used when h >= sw_h. This is an optimized implementation (via _ifgt.Ifgt) designed for efficiency when the bandwidth is larger.

Adjusting sw_h allows you to control when the library switches from the exact direct calculation to the faster IFGT approximation.

FilterReg supports two types of objective functions via the objective_type parameter:

1. pt2pt (Point-to-Point): Standard alignment where source points are matched to target points. This is the default.
2. pt2pl (Point-to-Plane): Alignment where source points are matched to the tangent planes of the target points. This requires providing target_normals to the algorithm.

When calling registration_cpd, specify the tf_type_name to determine the degrees of freedom in the registration:

• "rigid": Computes rotation, translation, and optionally scale. Use update_scale=True (default) to include scale.
• "affine": Computes an affine transformation (linear mapping plus translation).
• "nonrigid": Computes a non-rigid deformation using an RBF kernel. Requires beta (RBF kernel parameter) and lmd (regularization parameter).
• "nonrigid_constrained": An extended non-rigid CPD that allows incorporating known point correspondences using idx_source and idx_target.