Numpy & PyTorch implementation of the JRMPC algorithm.
Project description
JRMPC Numpy/PyTorch
JRMPC (Joint Registration of Multiple Point Clouds) is an algorith to jointly estimate rigid transformation aligning a set of point clouds of varying lengths.
Installation
pip install jrmpc
Presentation
This repos is a Numpy and PyTorch portage of the JRMPC algorithm.
The two reference papers are:
- Georgios D. Evangelidis, D. Kounades-Bastian, R. Horaud, and E.Z Psarakis, A Generative Model for the Joint Registration of Multiple Point Sets, ECCV, 2014.
- Georgios D. Evangelidis, R. Horaud, Joint Alignment of Point Sets with Batch and Incremental Expectation-Maximization, PAMI, 2018.
The original code provided by the authors is downloadable through this link.
Motivation
Python is widely used in the machine learning community, far more than MATLAB.
Leveraging PyTorch allows this implementation to support CUDA GPU. From my quick testing on a single RTX 3090,
it is approximately 50x faster than the base Matlab implementation.
Getting started
In the simplest setup, the following code is enough:
from jrmpc import jrmpc
V: list[Tensor] = load_views(...) # list of M tensors (3, Nj).
result = jrmpc(V)
R_hat, t_hat = result.R, result.t
V_registered = [r @ v + t for v, r, t in zip(views, R_hat, t_hat)]
I provide a small demo notebook with some visualizations.
Multi-backend support
If you run import jrmpc from jrmpc
, it will attempt to automatically choose a backend: torch
if available, else numpy
.
If you want to manually choose a backend, run one of the following:
from jrmpc.torch import jrmpc
from jrmpc.numpy import jrmpc
Documentation
Here is the complete API description:
Parameters
- V (
Sequence[Tensor]
): Views, sequence of $M$ point clouds of varying length(3, Nj), j=0:M
. - X (
Optional[Tensor]
): Cluster centers. IfNone
, computed internally. - R (
Optional[Tensor]
): Initial rotations(M, 3, 3)
. IfNone
, initialized with the identity matrix. - t (
Optional[Tensor]
): Initial translations(M, 3)
. If None,t[j]
is initialized with the arithmetic mean ofV[j]
, i.e. as a centering operation. - S (
Optional[Tensor]
): Initial variances for theK
GMM components. Either a tensor(K,)
or a single scalar. If scalar is provided then allK
components are initialized with the same variance. IfNone
, all variances are initialized with the same value, which is computed as the squared length of the diagonal of the bounding box that contains all points ofV
, after applying initial rototranslation. - fix_model (bool):
If
True
, the modelX
onto which the viewsV
are registered is not updated during optimization. Only rotations and translations are estimated. Default value:False
. - Q_factor (
float, optional
): After having computedQ
(=1/S
), it is multiplied by this factor. Default value:1000
. - max_num_iter (
Optional[int]
): Specifies the number of iterations, Default value:100
. - epsilon (
Optional[Tensor]
): Artificial covariance flatten. A positive number added toS
, after its update, at every iteration. Default value:1e-6
. - initial_priors (
Optional[Tensor]
): Specifies the prior probabilitiesp
of the GMM components, and implicitly defines the priorp_{K+1}
for the outlier class. It can be a(K,)
tensor or a scalar. Ifp
is scalar then that same value is used for all components. The sum of all elements inp
(orK*p
if p is scalar) must be less than1
as they represent a probability mass.p_{K+1}
is computed internally as1 - sum(p)
if p is a vector, or asp_{K+1}
=1-K\*p
otherwise. gamma is uniquely defined fromp_{K+1}
as1 = (gamma+1)*sum(p)
. Default value: The distribution ofp_k
is initialized as a uniform asp_k = 1/(K+1), k=0:K
. - gamma (
Optional[float]
): Positive scalar specifying the outlier proportion inV
. Used to compute the prior probabilityp_{K+1}
of the outlier component asgamma*sum_k(p_k)
. If gamma is provided thenpk's
are initialized uniformly assum_k(p_k) = 1/(gamma+1)
=>p_k = 1/(K*(gamma+1))
. Paramater gamma is a shortcut to setinitial_priors
uniformly, and therefore, eithergamma
orinitialPriors
should be given at a time. Default value:1/K
. - update_priors (
bool, optional
): If True, priors are updated at every iteration. Default value:False
. - progress_bar (
bool, optional
): IfTrue
, display a progress bar during themax_num_iter
optimization steps. Default value:False
.
Returns
A named tuple with four elements:
- R: estimated rotation matrices to align the given views onto the estimated template. Tensor
(M, 3, 3)
. - t: estimated translation vector to align the given views onto the estimated template. Tensor
(M, 3, 1)
. - X: estimated template. Point clouds
(M, K)
. - S: Scalar variance associated to each of the estimated template
K
Gaussians. Tensor(K,)
. - A: Aij in R^K: posterior probability of the j-th point of the i-th view to be associated with K clusters. List of M Tensors (N_i, K).
- p: Priors probabilities, not including outliers. Tensor
(K + 1)
. - history: the transformation parameters after each iteration. Dictionary with keys
R
andt
.history['R']
andhistory['t']
are list of lengthmax_num_iter
of rotation and translation tensors.
Bonus: Fast non-generative pairwise registration
In some cases, a model is available, and many views must be registered independently onto it. The torch function
jrmpc.parallel_jrmpc_single_view_fixed_model
provides a fast way to do this.
It accepts a batch of views (B, 3, N)
and a single model (3, K)
.
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.