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, 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. - 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)
. - 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.
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.