############# Python-CPD #############
.. |master_badge| image:: https://github.com/siavashk/pycpd/actions/workflows/build-test.yml/badge.svg?branch=master .. |development_badge| image:: https://github.com/siavashk/pycpd/actions/workflows/build-test.yml/badge.svg?branch=development .. |joss_paper_badge| image:: https://joss.theoj.org/papers/10.21105/joss.04681/status.svg :target: https://doi.org/10.21105/joss.04681
+-----------------+---------------------+ | Paper Citation | |joss_paper_badge| | +-----------------+---------------------+
+-----------------+---------------------+ | Build Status | +-----------------+---------------------+ | master | |master_badge| | +-----------------+---------------------+ | development | |development_badge| | +-----------------+---------------------+
Documentation <https://siavashk.github.io/pycpd/>
_
Pure Numpy Implementation of the Coherent Point Drift Algorithm.
MIT License.
Introduction
This is a pure numpy implementation of the coherent point drift CPD <https://arxiv.org/abs/0905.2635/>
_ algorithm by Myronenko and Song for use by the python community. It provides three registration methods for point clouds: 1) Scale and rigid registration; 2) Affine registration; and 3) Gaussian regularized non-rigid registration.
The CPD algorithm is a registration method for aligning two point clouds. In this method, the moving point cloud is modelled as a Gaussian Mixture Model (GMM) and the fixed point cloud are treated as observations from the GMM. The optimal transformation parameters maximze the Maximum A Posteriori (MAP) estimation that the observed point cloud is drawn from the GMM.
The registration methods work for arbitrary MxN 2D arrays where M is the number of "points" and N is the number of dimensions. A typical point cloud would be Mx2 or Mx3 for 2D and 3D points clouds respectively. For more information, please refer to my blog <http://siavashk.github.io/2017/05/14/coherent-point-drift/>
_.
Installation
Install from PyPI #################
.. code-block:: bash
pip install pycpd
Installation from Source ########################
Clone the repository to a location, referred to as the root
folder. For example:
.. code-block:: bash
git clone https://github.com/siavashk/pycpd.git $HOME/pycpd
Install the package:
.. code-block:: bash
pip install .
or
.. code-block:: bash
make requirements make build
Install Matplotlib for Visualization ####################################
For running sample registration examples under /examples
, you will need Matplotlib
to visualize the registration. This can be downloaded by running:
.. code-block:: bash
pip install matplotlib
or
.. code-block:: bash
make visualize
Usage
Each registration method is contained within a single class inside the pycpd
subfolder. To try out the registration, you can simply run:
.. code-block:: bash
python examples/fish{Transform}{Dimension}.py
where Transform
is either rigid
, affine
or deformable
and Dimension
is either 2D
or 3D
. Note that examples are meant to be run from the root
folder.
Example
Basic Usage ###########
Basic usage includes providing any of the registration methods with 2 arrays that are MxN & BxN. E.g., they can have different numbers of points (M & B) but must have the same number of dimensions per point (N).
.. code-block:: python
from pycpd import RigidRegistration import numpy as np
target = np.array([[0, 0], [0, 1], [1, 0], [1, 1], [0.5, 0], [0, 0.5]]) print('Target Points: \n', target)
translation = [1, 0]
source = target + translation print('Source Points: \n', source)
reg = RigidRegistration(X=target, Y=source)
TY, (s_reg, R_reg, t_reg) = reg.register()
The affine and deformable registration methods are used in the same way, but provide their respective transformation parameters.
Apply Transform to Another Point Cloud ####################################### Sometimes you may want to apply the transformation parameters to another point cloud. For example, if you have a very large point cloud it is sometimes appropriate to randomly sample some of the points for registration and then apply the transformation to the entire point cloud.
To do this, after fitting the above registration, you would run reg.transform_point_cloud(Y=points_to_transform)
. This will apply the learned
registration parameters to the point cloud points_to_transform
and return the transformed point cloud.
Tuning Registration parameters ##############################
For rigid and affine registrations the main parameter you can tweak is w
. The w
parameter is an indication of the amount of noise in the
point clouds [0,1]
, by default it is set to 0
assuming no noise, but can be set at any value 0 <= w <1
with higher values indicating more noise.
For deformable registration, you can also tune alpha
, beta
, and use low_rank
.
The alpha
parameter (lambda
in the original paper) identifies a tradeoff between making points align & regularization of the deformation.
A higher value makes the deformation more rigid, a lower value makes the deformation more flexible.
The beta
is the width of the Gaussian kernel used to regularize the deformation and thus identifies how far apart points should be
to move them together (coherently). beta
depends on the scale/size of your points cloud. Tuning beta
can be simplified by normalizing
the point cloud to a unit sphere distance.
The low_rank
parameter is a boolean that indicates whether to use a regularized form of the deformation field. This further
constrains the deformation, while vastly speeding up the optimization. num_eig
is the number of eigenvalues to use in the low rank
approximation. num_eig
should be less than the number of points in the point cloud, the lower the smoother the deformation and the
faster the optimization.
Testing
Tests can be run using pytest:
.. code-block:: bash
pip install pytest pytest
or
.. code-block:: bash
make dev make test
Documentation
The documentation can be built using pydoc3
.. code-block:: bash
make dev make doc
Contributing
Contributions are welcome. Please see the guidelines outlined in the document: CONTRIBUTING <https://github.com/siavashk/pycpd/blob/master/CONTRIBUTING.md>
_.
Code of Conduct
We have adopted the code of conduct defined by the Contributor Covenant <https://www.contributor-covenant.org/>
_ to clarify expected behavior in our community. For more information see the Code of Conduct <https://github.com/siavashk/pycpd/blob/master/CODE_OF_CONDUCT.md>
_.