Point-matching¶

Transformation estimation from landmarks.

This is basically a wrapper around the point-matching algorithm from the vt-python library.

timagetk.algorithms.pointmatching.apply_trsf_to_points(points, trsf, **kwargs)[source]¶

Apply a given transformation to a set of XYZ point coordinates.

Parameters:

points (numpy.ndarray) – A [N, 3] array of 3D point coordinates, XYZ sorted.
trsf (Trsf) – The transformation to apply to the points.

Returns:

numpy.ndarray – The registered [N, 3] array of XYZ point coordinates.

Notes

If the points are in real coordinates, you should provide a transformation with a ‘real’ unit_type attribute!

Examples

>>> import numpy as np
>>> from timagetk.io import imread
>>> from timagetk.io.util import shared_data
>>> from timagetk.algorithms.trsf import inv_trsf
>>> from timagetk.algorithms.pointmatching import pointmatching
>>> from timagetk.algorithms.pointmatching import apply_trsf_to_points
>>> ref_pts = np.loadtxt(shared_data('p58_t0_reference_ldmk-01.txt', 'p58'))
>>> flo_pts = np.loadtxt(shared_data('p58_t0_floating_ldmk-01.txt', 'p58'))
>>> trsf = pointmatching(flo_pts, ref_pts, method='rigid', real=True)
>>> reg_pts = apply_trsf_to_points(flo_pts, inv_trsf(trsf))
>>> print(ref_pts)
>>> print(reg_pts)
>>> print(flo_pts)

timagetk.algorithms.pointmatching.pointmatching(points_flo, points_ref, template_img=None, method='rigid', **kwargs)[source]¶

Computes a transformation using paired points (aka. landmarks).

The resulting transformation will allow to resample the floating image (from which the floating points are drawn) onto the reference one. Points are assumed to be paired according to their index in both lists.

Parameters:

points_flo (list) – The X, Y [, Z] point list to be registered (floating points).
points_ref (list) – The X, Y [, Z] reference point list (still points).
template_img (timagetk.SpatialImage, optional) – Template image used for the dimensions & voxelsize of the output transformation vectorfield. Required for vectorfield method.
method ({'rigid', 'affine', 'vectorfield'}, optional) – The registration method to use, DEF_BM_METHOD by default.
fluid_sigma (float or list of float) – Sigma for fluid regularization, i.e. field interpolation and regularization for pairings. Retricted to vector-field.
vector_propagation_distance (float) – Defines the propagation distance of initial pairings (i.e. displacements). This implies the same displacement for the spanned sphere. Retricted to vector-field. Distance is in world units (not voxels).
vector_fading_distance (float) – Area of fading for initial pairings (i.e. displacements). This allows progressive transition towards null displacements and thus avoid discontinuites. Distance is in world units (not voxels).
vector_propagation_type (str in {"direct", "skiz"}) – Defines how vector are propagated, see notes for more details.
estimator_type ({"wlts", "lts", "wls", "ls"}) – Transformation estimator, see notes for more details.
lts_fraction (float) – If defined, set the fraction of pairs that are kept, used with trimmed estimations.
lts_deviation (float) – If defined, set the threshold to discard pairings (see notes), used with trimmed estimations.
lts_iterations (int) – If defined, set the maximal number of iterations, used with trimmed estimations.
real (bool, optional) – Define if the given points are in voxel or real units (default)
params (str, optional) – CLI parameter string used by vt.pointmatching method.

Returns:

Trsf – The vt transformation object resampling the floating points onto the reference points.

Raises:

TypeError – If template_img is not a LabelledImage, if not None.
ValueError – If the list of points are not of equal size. If there is less than four points in the paired lists when using a linear method. If the transformation returned by vt.pointmatching is None.

Notes

Definitions of available estimator_type values:

wlts: weighted least trimmed squares (default);
lts: least trimmed squares, see [lts] for more details;
wls: weighted least squares, see [wls] for more details;
ls: least squares, see [ls] for more details.

Parameter lts_deviation is used in the formulae: threshold = average + lts_deviation * standard_deviation

Examples

>>> from timagetk.algorithms.pointmatching import pointmatching
>>> flo_points = [[0, 0, 0], [0, 0, 1], [0, 1, 0], [1, 0, 0]]
>>> ref_points = [[0, 0, 0], [0, 0, 2], [0, 2, 0], [2, 0, 0]]
>>> # - Estimate 3D affine transformation, with points as real unit coordinates:
>>> trsf = pointmatching(flo_points, ref_points, method="affine")
>>> trsf.print()
transformation type is AFFINE_3D
transformation unit is REAL_UNIT
   0,500000000000000    0,000000000000000    0,000000000000000    0,000000000000000
   0,000000000000000    0,500000000000000    0,000000000000000    0,000000000000000
   0,000000000000000    0,000000000000000    0,500000000000000    0,000000000000000
   0,000000000000000    0,000000000000000    0,000000000000000    1,000000000000000
>>> from timagetk.algorithms.trsf import inv_trsf
>>> trsf_inv = inv_trsf(trsf)
>>> trsf_inv.copy_to_array()
array([[2., 0., 0., 0.],
       [0., 2., 0., 0.],
       [0., 0., 2., 0.],
       [0., 0., 0., 1.]])
>>> # - Estimate 3D rigid transformation, with points as real unit coordinates:
>>> trsf = pointmatching(flo_points, ref_points, method='rigid', params=" -unit real")
>>> inv_trsf(trsf).copy_to_array()
array([[1.  , 0.  , 0.  , 0.25],
       [0.  , 1.  , 0.  , 0.25],
       [0.  , 0.  , 1.  , 0.25],
       [0.  , 0.  , 0.  , 1.  ]])
>>> # - Estimate 3D vectorfield transformation, with points as real unit coordinates:
>>> from timagetk.io import imread
>>> from timagetk.io.util import shared_data
>>> from timagetk.algorithms.pointmatching import pointmatching
>>> template = imread(shared_dataset("p58", "intensity")[1])
>>> flo_points = shared_data("cell_barycenters_landmarks-t0.txt", "p58")
>>> ref_points = shared_data("cell_barycenters_landmarks-t1_relab_t0.txt", "p58")
>>> trsf = pointmatching(flo_points, ref_points, template, method='vectorfield', fluid_sigma=5.0, vector_propagation_distance=20.0, vector_fading_distance=3.0, params="-unit real -propagation skiz")
>>> trsf.print()

Table of Contents

Point-matching¶