ants.registration

registration(fixed, moving, type_of_transform='SyN', initial_transform=None, outprefix='', mask=None, moving_mask=None, mask_all_stages=False, grad_step=0.2, flow_sigma=3, total_sigma=0, aff_metric='mattes', aff_sampling=32, aff_random_sampling_rate=0.2, syn_metric='mattes', syn_sampling=32, reg_iterations=(40, 20, 0), aff_iterations=(2100, 1200, 1200, 10), aff_shrink_factors=(6, 4, 2, 1), aff_smoothing_sigmas=(3, 2, 1, 0), write_composite_transform=False, verbose=False, multivariate_extras=None, restrict_transformation=None, smoothing_in_mm=False, singleprecision=True, use_legacy_histogram_matching=False, **kwargs)[source]

Register a pair of images either through the full or simplified interface to the ANTs registration method.

ANTsR function: antsRegistration

Parameters:

  • fixed (ants.core.ANTsImage) – fixed image to which we register the moving image.

  • moving (ants.core.ANTsImage) – moving image to be mapped to fixed space.

  • type_of_transform (str) – A linear or non-linear registration type. Mutual information metric by default. See Notes below for more.

  • initial_transform (list of strings (optional)) – transforms to prepend. If None, a translation is computed to align the image centers of mass, unless the type of transform is deformable-only (time-varying diffeomorphisms, SyNOnly, or antsRegistrationSyN*[so|bo]). To force initialization with an identity transform, set this to ‘Identity’.

  • outprefix (str) – output will be named with this prefix.

  • mask (ANTsImage (optional)) – Registration metric mask in the fixed image space.

  • moving_mask (ANTsImage (optional)) – Registration metric mask in the moving image space.

  • mask_all_stages (bool) – If true, apply metric mask(s) to all registration stages, instead of just the final stage.

  • grad_step (scalar) – gradient step size (not for all tx)

  • flow_sigma (scalar) – smoothing for update field At each iteration, the similarity metric and gradient is calculated. That gradient field is also called the update field and is smoothed before composing with the total field (i.e., the estimate of the total transform at that iteration). This total field can also be smoothed after each iteration.

  • total_sigma (scalar) – smoothing for total field

  • aff_metric (str) – the metric for the affine part (GC, mattes, meansquares)

  • aff_sampling (scalar) – number of bins for the mutual information metric

  • aff_random_sampling_rate (scalar) – the fraction of points used to estimate the metric. this can impact speed but also reproducibility and/or accuracy.

  • syn_metric (str) – the metric for the syn part (CC, mattes, meansquares, demons)

  • syn_sampling (scalar) – the nbins or radius parameter for the syn metric

  • reg_iterations (list/tuple of integers) – vector of iterations for syn. we will set the smoothing and multi-resolution parameters based on the length of this vector.

  • aff_iterations (list/tuple of integers) – vector of iterations for low-dimensional (translation, rigid, affine) registration.

  • aff_shrink_factors (list/tuple of integers) – vector of multi-resolution shrink factors for low-dimensional (translation, rigid, affine) registration.

  • aff_smoothing_sigmas (list/tuple of integers) – vector of multi-resolution smoothing factors for low-dimensional (translation, rigid, affine) registration.

  • write_composite_transform (bool) – Boolean specifying whether or not the composite transform (and its inverse, if it exists) should be written to an hdf5 composite file. This is false by default so that only the transform for each stage is written to file.

  • verbose (bool) – request verbose output (useful for debugging)

  • multivariate_extras (additional metrics for multi-metric registration) –

    list of additional images and metrics which will trigger the use of multiple metrics in the registration process in the deformable stage. Each multivariate metric needs 5 entries: name of metric, fixed, moving, weight, samplingParam. the list of lists should be of the form ( ( “nameOfMetric2”, img, img, weight, metricParam ) ). Another example would be ( ( “MeanSquares”, f2, m2, 0.5, 0

    ), ( “CC”, f2, m2, 0.5, 2 ) ) . This is only compatible

    with the SyNOnly or antsRegistrationSyN* transformations.

  • restrict_transformation (This option allows the user to restrict the) – optimization of the displacement field, translation, rigid or affine transform on a per-component basis. For example, if one wants to limit the deformation or rotation of 3-D volume to the first two dimensions, this is possible by specifying a weight vector of ‘(1,1,0)’ for a 3D deformation field or ‘(1,1,0,1,1,0)’ for a rigid transformation. Restriction currently only works if there are no preceding transformations.

  • smoothing_in_mm (boolean ; currently only impacts low dimensional registration) –

  • singleprecision (bool) – if True, use float32 for computations. This is useful for reducing memory usage for large datasets, at the cost of precision.

  • use_legacy_histogram_matching (bool) – if True, use the original histogram matching in ANTs. This is not recommended, but is available for backwards compatibilty with earlier versions, where it was always turned on. The default is False. A better implementation of histogram matching is available in the ants.histogram_match_image2 function.

  • kwargs (keyword args) – extra arguments

Returns:

warpedmovout: Moving image warped to space of fixed image. warpedfixout: Fixed image warped to space of moving image. fwdtransforms: Transforms to move from moving to fixed image. invtransforms: Transforms to move from fixed to moving image.

Return type:

dict containing follow key/value pairs

Notes

The output dict contains file names, designed to be used with ants.apply_transforms. As in ANTs, the forward affine transform .mat file is present in both the fwdtransforms and invtransforms lists. The matrix is inverted at run time by ants.apply_transforms when applying an inverse transform (see its whichtoinvert parameter).

type_of_transform can be one of:

  • “Translation”: Translation transformation.

  • “Rigid”: Rigid transformation: Only rotation and translation.

  • “Similarity”: Similarity transformation: uniform scaling, rotation and translation.

  • “QuickRigid”: Rigid transformation: Only rotation and translation.

    May be useful for quick visualization fixes.’

  • “DenseRigid”: Rigid transformation: Only rotation and translation.

    Employs dense sampling during metric estimation.’

  • “BOLDRigid”: Rigid transformation: Parameters typical for BOLD to

    BOLD intrasubject registration’.’

  • “Affine”: Affine transformation: Rigid + scaling + shear (12 parameters).

  • “AffineFast”: Fast version of Affine.

  • “BOLDAffine”: Affine transformation: Parameters typical for BOLD to

    BOLD intrasubject registration’.’

  • “TRSAA”: translation, rigid, similarity, affine (twice). please set

    regIterations if using this option. this would be used in cases where you want a really high quality affine mapping (perhaps with mask).

  • “Elastic”: Elastic deformation: Affine + deformable.

  • “ElasticSyN”: Symmetric normalization: Affine + deformable

    transformation, with mutual information as optimization metric and elastic regularization.

  • “SyN”: Symmetric normalization: Affine + deformable transformation,

    with mutual information as optimization metric.

  • “SyNRA”: Symmetric normalization: Rigid + Affine + deformable

    transformation, with mutual information as optimization metric.

  • “SyNOnly”: Symmetric normalization with no rigid or affine stages.

    Uses mutual information as optimization metric.

  • “SyNCC”: SyN, but with cross-correlation as the metric.

  • “SyNabp”: SyN optimized for abpBrainExtraction.

  • “SyNBold”: SyN, but optimized for registrations between BOLD and T1 images.

  • “SyNBoldAff”: SyN, but optimized for registrations between BOLD

    and T1 images, with additional affine step.

  • “SyNAggro”: SyN, but with more aggressive registration

    (fine-scale matching and more deformation). Takes more time than SyN.

  • “SyNLessAggro”: Does exactly the same thing as “SyNAggro”.

  • “TV[n]”: time-varying diffeomorphism with where ‘n’ indicates number of

    time points in velocity field discretization. The initial transform should be computed, if needed, in a separate call to ants.registration.

  • “TVMSQ”: time-varying diffeomorphism with mean square metric

  • “TVMSQC”: time-varying diffeomorphism with mean square metric for very large deformation

  • “antsRegistrationSyN[x]”: recreation of the antsRegistrationSyN.sh script in ANTs
    where ‘x’ is one of the transforms available:

    t: translation (1 stage) r: rigid (1 stage) a: rigid + affine (2 stages) s: rigid + affine + deformable syn (3 stages) sr: rigid + deformable syn (2 stages) so: deformable syn only (1 stage) b: rigid + affine + deformable b-spline syn (3 stages) br: rigid + deformable b-spline syn (2 stages) bo: deformable b-spline syn only (1 stage)

  • “antsRegistrationSyNQuick[x]”: recreation of the antsRegistrationSyNQuick.sh script in ANTs.

    x options as above.

  • “antsRegistrationSyNRepro[x]”: reproducible registration. x options as above.

  • “antsRegistrationSyNQuickRepro[x]”: quick reproducible registration. x options as above.

Example

>>> import ants
>>> fi = ants.image_read(ants.get_ants_data('r16'))
>>> mi = ants.image_read(ants.get_ants_data('r64'))
>>> fi = ants.resample_image(fi, (60,60), 1, 0)
>>> mi = ants.resample_image(mi, (60,60), 1, 0)
>>> mytx = ants.registration(fixed=fi, moving=mi, type_of_transform = 'SyN' )
>>> mytx = ants.registration(fixed=fi, moving=mi, type_of_transform = 'antsRegistrationSyN[t]' )
>>> mytx = ants.registration(fixed=fi, moving=mi, type_of_transform = 'antsRegistrationSyN[b]' )
>>> mytx = ants.registration(fixed=fi, moving=mi, type_of_transform = 'antsRegistrationSyN[s]' )