Programs · ANTs and ITK

antsRegistration

antsRegistration registers one image to another, stage by stage.

Original
ANTs 2.6.5
Command line
larmorx ants antsRegistration
Python
lx.ants.registration
Ports
  • replica larmorx Apache-2.0 validated
Evidence
every comparison with ANTs
Source
made from docs/api/ants-registration.md and the code

What it does

It runs linear stages (Translation, Rigid, Similarity, Affine, CompositeAffine), SyN stages (SyN[gradientStep,updateFieldVariance,totalFieldVariance], SyN stages), the B-spline and displacement-field stages (BSplineSyN, GaussianDisplacementField, BSplineDisplacementField, BSpline, B-spline and displacement-field stages) and the velocity-field stages (Exponential, BSplineExponential, TimeVaryingVelocityField, TimeVaryingBSplineVelocityField; Velocity-field stages): every transform antsRegistration has, in 2, 3 and 4 dimensions, double and float (--float 1), with every image metric (Mattes/MI, MI2, MeanSquares, CC, GC, and Demons, which needs a displacement field: it fails in a linear stage as in ANTs) and every point-set metric (ICP, PSE, JHCT, IGDM; Point-set metrics), several metrics per stage, sampling, masks, multi-resolution shrinking and smoothing, the gradient filter, winsorizing and histogram matching, initial transforms (files, displacement fields and composites holding them, [fixed,moving,feature]), --initialize-transforms-per-stage, --restore-state and --save-state, --print-similarity-measure-interval and --write-interval-volumes. larmorx refuses nothing ANTs accepts, except MINC transform files and the crashes and hangs listed in the register.

Command line

text
larmorx ants antsRegistration ...

Everything after larmorx ants antsRegistration is the original’s command line: the arguments of ANTs 2.6.5’s antsRegistration, as ANTs takes them. LARMORX’s own options stand between larmorx and the family ants, so they never meet the original’s (below):

text
larmorx
        [--n-threads N]
        [--implementation auto|replica|clean-room]
        [--upstream-defects fix|reproduce]
        ants antsRegistration ...

From the next release. In 0.1.0rc1, set the variables instead: OMP_NUM_THREADS, LARMORX_IMPLEMENTATION (original for the clean room) and LARMORX_UPSTREAM_DEFECTS.

Python

python
lx.ants.registration(
    stages: RegistrationStage | Sequence[RegistrationStage],
    *,
    dimension: int | None = None,
    initial_moving_transforms: Sequence[Any] = (),
    initial_fixed_transforms: Sequence[Any] = (),
    restore_state: Any = None,
    winsorize: tuple[float, float] | None = None,
    use_histogram_matching: bool = False,
    collapse_output_transforms: bool = True,
    write_composite_transform: bool = False,
    initialize_transforms_per_stage: bool = False,
    warped: bool = False,
    inverse_warped: bool = False,
    interpolation: str = "Linear",
    precision: Precision = "float64",
    random_seed: int | None = None,
    print_similarity_measure_interval: int = 0,
    n_threads: int = 1,
    upstream_defects: UpstreamDefectsName = "fix",
) -> RegistrationResult

Where Precision is one of "float64", "float32"; UpstreamDefectsName is one of "fix", "reproduce".

Register the moving images to the fixed ones in linear, SyN, B-spline and displacement-field stages, as antsRegistration (ANTs v2.6.5) does.

Returns a RegistrationResult: transforms and inverse_transforms (as ItkTransform lists, ready for lx.ants.apply_transforms), files (each output file’s transforms, by the name antsRegistration gives it), warped and inverse_warped (with those arguments), iterations (every iteration’s stage, level, number and metric value, from the DIAGNOSTIC lines) and log.

python
import larmorx as lx

stage1 = lx.ants.RegistrationStage(
    transform="Rigid", gradient_step=0.1,
    metrics=lx.ants.RegistrationMetric("Mattes", "fixed.nii.gz", "moving.nii.gz",
                                       bins=32, sampling="Regular", sampling_percentage=0.25),
    iterations=[1000, 500, 250], shrink_factors=[4, 2, 1], smoothing_sigmas=[2, 1, 0],
)
stage2 = lx.ants.RegistrationStage(
    transform="Affine", gradient_step=0.1,
    metrics=lx.ants.RegistrationMetric("Mattes", "fixed.nii.gz", "moving.nii.gz",
                                       sampling="Regular", sampling_percentage=0.25),
    iterations=[1000, 500, 250], shrink_factors=[4, 2, 1], smoothing_sigmas=[2, 1, 0],
)
res = lx.ants.registration(
    [stage1, stage2],
    initial_moving_transforms=[lx.ants.AlignCenters("fixed.nii.gz", "moving.nii.gz", "moments")],
    winsorize=(0.005, 0.995), use_histogram_matching=True,
    warped=True, random_seed=42,
)
res.files["0GenericAffine.mat"]                 # the collapsed affine, as ITK transforms
warped = lx.ants.apply_transforms("moving.nii.gz", "fixed.nii.gz", res.transforms)
[(it.stage, it.level, it.iteration, it.value) for it in res.iterations]

Its result, RegistrationResult, holds what antsRegistration wrote.

Field Type What it holds
transforms list[list[ItkTransform]]
inverse_transforms list[list[ItkTransform]] | None
files dict[str, list[ItkTransform]]
warped Image | None
inverse_warped Image | None
iterations list[RegistrationIteration]
log str

Options

Each row joins an option of the original’s command line with the Python argument that does the same. The rows are checked against the code at every test run: the options antsRegistration accepts (crates/larmorx-ants/src/cli/registration.rs) and the arguments of lx.ants.registration (python/larmorx/ants/registration.py), whose defaults and descriptions are taken from it. Under each option, in grey, ANTs’s own help for it.

ANTs option Python Default Notes
-d 2/3/4, --dimensionality dimension None default: the first fixed image’sANTs: “This option forces the image to be treated as a specified-dimensional image. If not specified, we try to infer the dimensionality from the input image.”
-o [prefix,warped,inverse], --output warped=True, inverse_warped=True warped=False, inverse_warped=False the result’s files, transforms, warped and inverse_warped; Python writes the transforms to a temporary directory and reads them back; the warped images stay in memoryANTs: “Specify the output transform prefix (output format is .nii.gz ). Optionally, one can choose to warp the moving image to the fixed space and, if the inverse transform exists, one can also output the warped fixed image. Note that only the images specified in the first metric call are warped. Use antsApplyTransforms to warp other images using the resultant transform(s). When a composite transform is not specified, linear transforms are specified with a ‘.mat’ suffix and displacement fields with a ‘Warp.nii.gz’ suffix (and ‘InverseWarp.nii.gz’, when applicable. In addition, for velocity-based transforms, the full velocity field is written to file (‘VelocityField.nii.gz’) as long as the collapse transforms flag is turned off (‘-z 0’).”
-t, -m, -c, -f, -s, -x, -g (one stage each) stages a list of lx.ants.RegistrationStage, one per -t, each with its metrics (lx.ants.RegistrationMetric, PointSetMetric, IntensityPointSetMetric), convergence, shrink factors, smoothing sigmas, masks and restrictionsANTs: “Several transform options are available. The gradientStep or learningRate characterizes the gradient descent optimization and is scaled appropriately for each transform using the shift scales estimator. Subsequent parameters are transform-specific and can be determined from the usage. For the B-spline transforms one can also specify the smoothing in terms of spline distance (i.e. knot spacing). ”ANTs: “These image metrics are available— CC: ANTS neighborhood cross correlation, MI: Mutual information, Demons: (Thirion), MeanSquares, and GC: Global Correlation. The “metricWeight” variable is used to modulate the per stage weighting of the metrics. The metrics can also employ a sampling strategy defined by a sampling percentage. The sampling strategy defaults to ‘None’ (aka a dense sampling of one sample per voxel), otherwise it defines a point set over which to optimize the metric. The point set can be on a regular lattice or a random lattice of points slightly perturbed to minimize aliasing artifacts. samplingPercentage defines the fraction of points to select from the domain. useGradientFilter specifies whether a smoothingfilter is applied when estimating the metric gradient.In addition, three point set metrics are available: Euclidean (ICP), Point-set expectation (PSE), and Jensen-Havrda-Charvet-Tsallis (JHCT).”ANTs: “Convergence is determined from the number of iterations per level and is determined by fitting a line to the normalized energy profile of the last N iterations (where N is specified by the window size) and determining the slope which is then compared with the convergence threshold.”ANTs: “Specify the shrink factor for the virtual domain (typically the fixed image) at each level.”ANTs: “Specify the sigma of gaussian smoothing at each level. Units are given in terms of voxels (‘vox’) or physical spacing (‘mm’). Example usage is ‘4x2x1mm’ and ‘4x2x1vox’ where no units implies voxel spacing.”ANTs: “Image masks to limit voxels considered by the metric. Two options are allowed for mask specification: 1) Either the user specifies a single mask to be used for all stages or 2) the user specifies a mask for each stage. With the latter one can select to which stages masks are applied by supplying valid file names. If the file does not exist, a mask will not be used for that stage. Note that we handle the fixed and moving masks separately to enforce this constraint.”ANTs: “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 ‘1x1x0’ for a deformation field or ‘1x1x0x1x1x0’ for a rigid transformation. Low-dimensional restriction only works if there are no preceding transformations.All stages up to and including the desired stage must have this option specified,even if they should not be restricted (in which case specify 1x1x1…)”
-t Rigid[step], --transform RegistrationStage(transform="Rigid", gradient_step=step) Translation, Rigid, Similarity, Affine, CompositeAffineANTs: “Several transform options are available. The gradientStep or learningRate characterizes the gradient descent optimization and is scaled appropriately for each transform using the shift scales estimator. Subsequent parameters are transform-specific and can be determined from the usage. For the B-spline transforms one can also specify the smoothing in terms of spline distance (i.e. knot spacing). ”
-t SyN[step,update,total] RegistrationStage(transform="SyN", gradient_step=step, update_field_variance=update, total_field_variance=total) variances in voxels², default 3 and 0ANTs: “Several transform options are available. The gradientStep or learningRate characterizes the gradient descent optimization and is scaled appropriately for each transform using the shift scales estimator. Subsequent parameters are transform-specific and can be determined from the usage. For the B-spline transforms one can also specify the smoothing in terms of spline distance (i.e. knot spacing). ”
-t BSplineSyN[step,updateMesh,totalMesh,order] RegistrationStage(transform="BSplineSyN", gradient_step=step, mesh_size=updateMesh, total_mesh_size=totalMesh, spline_order=order) meshes per axis at the base level ((2, 2, 2), 2x2x2), or one knot spacing in mm (26); total mesh default 0 (no smoothing), order 3ANTs: “Several transform options are available. The gradientStep or learningRate characterizes the gradient descent optimization and is scaled appropriately for each transform using the shift scales estimator. Subsequent parameters are transform-specific and can be determined from the usage. For the B-spline transforms one can also specify the smoothing in terms of spline distance (i.e. knot spacing). ”
-t GaussianDisplacementField[step,update,total] RegistrationStage(transform="GaussianDisplacementField", gradient_step=step, update_field_variance=update, total_field_variance=total) both variances required on the command lineANTs: “Several transform options are available. The gradientStep or learningRate characterizes the gradient descent optimization and is scaled appropriately for each transform using the shift scales estimator. Subsequent parameters are transform-specific and can be determined from the usage. For the B-spline transforms one can also specify the smoothing in terms of spline distance (i.e. knot spacing). ”
-t BSplineDisplacementField[step,updateMesh,totalMesh,order] RegistrationStage(transform="BSplineDisplacementField", gradient_step=step, mesh_size=, total_mesh_size=, spline_order=) the meshes at the base level, doubled at each level (ANTs doubles them already at the base level, ANTS-78: give twice the mesh, or reproduce, for its result)ANTs: “Several transform options are available. The gradientStep or learningRate characterizes the gradient descent optimization and is scaled appropriately for each transform using the shift scales estimator. Subsequent parameters are transform-specific and can be determined from the usage. For the B-spline transforms one can also specify the smoothing in terms of spline distance (i.e. knot spacing). ”
-t BSpline[step,mesh] RegistrationStage(transform="BSpline", gradient_step=step, mesh_size=mesh) a cubic B-spline transform; the mesh (or knot spacing) at the base level, doubled at each levelANTs: “Several transform options are available. The gradientStep or learningRate characterizes the gradient descent optimization and is scaled appropriately for each transform using the shift scales estimator. Subsequent parameters are transform-specific and can be determined from the usage. For the B-spline transforms one can also specify the smoothing in terms of spline distance (i.e. knot spacing). ”
-t Exponential[step,update,velocity,steps] RegistrationStage(transform="Exponential", gradient_step=step, update_field_variance=update, velocity_field_variance=velocity, integration_steps=steps) Exp is the short name; steps 0 or left out (None): automatic; the sigmas -s in the units given (ANTs: mm, ANTS-80)ANTs: “Several transform options are available. The gradientStep or learningRate characterizes the gradient descent optimization and is scaled appropriately for each transform using the shift scales estimator. Subsequent parameters are transform-specific and can be determined from the usage. For the B-spline transforms one can also specify the smoothing in terms of spline distance (i.e. knot spacing). ”
-t BSplineExponential[step,updateMesh,velocityMesh,steps,order] RegistrationStage(transform="BSplineExponential", gradient_step=step, mesh_size=updateMesh, total_mesh_size=velocityMesh, integration_steps=steps, spline_order=order) meshes or knot spacings, at the base level (ANTS-78)ANTs: “Several transform options are available. The gradientStep or learningRate characterizes the gradient descent optimization and is scaled appropriately for each transform using the shift scales estimator. Subsequent parameters are transform-specific and can be determined from the usage. For the B-spline transforms one can also specify the smoothing in terms of spline distance (i.e. knot spacing). ”
-t TimeVaryingVelocityField[step,timeIndices,update,updateTime,total,totalTime] RegistrationStage(transform="TimeVaryingVelocityField", gradient_step=step, number_of_time_indices=, update_field_variance=, update_field_time_variance=, total_field_variance=, total_field_time_variance=) tvf is the short name; all six parameters requiredANTs: “Several transform options are available. The gradientStep or learningRate characterizes the gradient descent optimization and is scaled appropriately for each transform using the shift scales estimator. Subsequent parameters are transform-specific and can be determined from the usage. For the B-spline transforms one can also specify the smoothing in terms of spline distance (i.e. knot spacing). ”
-t TimeVaryingBSplineVelocityField[step,mesh,samples,order] RegistrationStage(transform="TimeVaryingBSplineVelocityField", gradient_step=step, mesh_size=mesh, number_of_time_point_samples=samples, spline_order=order) the mesh has one size per axis and one for time (4x4x4x2)ANTs: “Several transform options are available. The gradientStep or learningRate characterizes the gradient descent optimization and is scaled appropriately for each transform using the shift scales estimator. Subsequent parameters are transform-specific and can be determined from the usage. For the B-spline transforms one can also specify the smoothing in terms of spline distance (i.e. knot spacing). ”
-m ICP[f,m,w,p,boundary] PointSetMetric("ICP", f, m, weight=w, sampling_percentage=p, boundary_points_only=boundary) f, m: a label image, a .txt or .vtk point set, or (points, labels) arraysANTs: “These image metrics are available— CC: ANTS neighborhood cross correlation, MI: Mutual information, Demons: (Thirion), MeanSquares, and GC: Global Correlation. The “metricWeight” variable is used to modulate the per stage weighting of the metrics. The metrics can also employ a sampling strategy defined by a sampling percentage. The sampling strategy defaults to ‘None’ (aka a dense sampling of one sample per voxel), otherwise it defines a point set over which to optimize the metric. The point set can be on a regular lattice or a random lattice of points slightly perturbed to minimize aliasing artifacts. samplingPercentage defines the fraction of points to select from the domain. useGradientFilter specifies whether a smoothingfilter is applied when estimating the metric gradient.In addition, three point set metrics are available: Euclidean (ICP), Point-set expectation (PSE), and Jensen-Havrda-Charvet-Tsallis (JHCT).”
-m PSE[f,m,w,p,boundary,sigma,k] PointSetMetric("PSE", ..., sigma=sigma, k_neighborhood=k) ANTs: “These image metrics are available— CC: ANTS neighborhood cross correlation, MI: Mutual information, Demons: (Thirion), MeanSquares, and GC: Global Correlation. The “metricWeight” variable is used to modulate the per stage weighting of the metrics. The metrics can also employ a sampling strategy defined by a sampling percentage. The sampling strategy defaults to ‘None’ (aka a dense sampling of one sample per voxel), otherwise it defines a point set over which to optimize the metric. The point set can be on a regular lattice or a random lattice of points slightly perturbed to minimize aliasing artifacts. samplingPercentage defines the fraction of points to select from the domain. useGradientFilter specifies whether a smoothingfilter is applied when estimating the metric gradient.In addition, three point set metrics are available: Euclidean (ICP), Point-set expectation (PSE), and Jensen-Havrda-Charvet-Tsallis (JHCT).”
-m JHCT[f,m,w,p,boundary,sigma,k,alpha,aniso] PointSetMetric("JHCT", ..., sigma=, k_neighborhood=, alpha=, anisotropic_covariances=) ANTs: “These image metrics are available— CC: ANTS neighborhood cross correlation, MI: Mutual information, Demons: (Thirion), MeanSquares, and GC: Global Correlation. The “metricWeight” variable is used to modulate the per stage weighting of the metrics. The metrics can also employ a sampling strategy defined by a sampling percentage. The sampling strategy defaults to ‘None’ (aka a dense sampling of one sample per voxel), otherwise it defines a point set over which to optimize the metric. The point set can be on a regular lattice or a random lattice of points slightly perturbed to minimize aliasing artifacts. samplingPercentage defines the fraction of points to select from the domain. useGradientFilter specifies whether a smoothingfilter is applied when estimating the metric gradient.In addition, three point set metrics are available: Euclidean (ICP), Point-set expectation (PSE), and Jensen-Havrda-Charvet-Tsallis (JHCT).”
-m IGDM[f,m,w,fmask,mmask,radius,isigma,dsigma,k,gsigma] IntensityPointSetMetric(f, m, fmask, mmask, weight=, neighborhood_radius=, intensity_sigma=, distance_sigma=, k_neighborhood=, gradient_sigma=) sigmas of 0 are estimated (the distance sigma at least one voxel, ANTS-70); the k nearest points and Gaussian gradients of gsigma mm (ANTs uses neither, ANTS-67)ANTs: “These image metrics are available— CC: ANTS neighborhood cross correlation, MI: Mutual information, Demons: (Thirion), MeanSquares, and GC: Global Correlation. The “metricWeight” variable is used to modulate the per stage weighting of the metrics. The metrics can also employ a sampling strategy defined by a sampling percentage. The sampling strategy defaults to ‘None’ (aka a dense sampling of one sample per voxel), otherwise it defines a point set over which to optimize the metric. The point set can be on a regular lattice or a random lattice of points slightly perturbed to minimize aliasing artifacts. samplingPercentage defines the fraction of points to select from the domain. useGradientFilter specifies whether a smoothingfilter is applied when estimating the metric gradient.In addition, three point set metrics are available: Euclidean (ICP), Point-set expectation (PSE), and Jensen-Havrda-Charvet-Tsallis (JHCT).”
-m Mattes[f,m,w,bins,sampling,p,gf] RegistrationMetric("Mattes", f, m, weight=w, bins=bins, sampling=..., sampling_percentage=p, use_gradient_filter=gf) MI is ANTs’ other name for Mattes; MI2 the joint-histogram MI; CC[f,m,w,radius,...]: radius=; MeanSquares, GC, Demons have no parameterANTs: “These image metrics are available— CC: ANTS neighborhood cross correlation, MI: Mutual information, Demons: (Thirion), MeanSquares, and GC: Global Correlation. The “metricWeight” variable is used to modulate the per stage weighting of the metrics. The metrics can also employ a sampling strategy defined by a sampling percentage. The sampling strategy defaults to ‘None’ (aka a dense sampling of one sample per voxel), otherwise it defines a point set over which to optimize the metric. The point set can be on a regular lattice or a random lattice of points slightly perturbed to minimize aliasing artifacts. samplingPercentage defines the fraction of points to select from the domain. useGradientFilter specifies whether a smoothingfilter is applied when estimating the metric gradient.In addition, three point set metrics are available: Euclidean (ICP), Point-set expectation (PSE), and Jensen-Havrda-Charvet-Tsallis (JHCT).”
several -m in a stage, --metric RegistrationStage(metrics=[...]) the first metric’s value; derivatives weighed by weight (normalised)ANTs: “These image metrics are available— CC: ANTS neighborhood cross correlation, MI: Mutual information, Demons: (Thirion), MeanSquares, and GC: Global Correlation. The “metricWeight” variable is used to modulate the per stage weighting of the metrics. The metrics can also employ a sampling strategy defined by a sampling percentage. The sampling strategy defaults to ‘None’ (aka a dense sampling of one sample per voxel), otherwise it defines a point set over which to optimize the metric. The point set can be on a regular lattice or a random lattice of points slightly perturbed to minimize aliasing artifacts. samplingPercentage defines the fraction of points to select from the domain. useGradientFilter specifies whether a smoothingfilter is applied when estimating the metric gradient.In addition, three point set metrics are available: Euclidean (ICP), Point-set expectation (PSE), and Jensen-Havrda-Charvet-Tsallis (JHCT).”
-c [10x5,1e-6,10], --convergence RegistrationStage(iterations=[10, 5], convergence_threshold=1e-6, convergence_window=10) a level stops when the window’s convergence value is ≤ the threshold (negative when the metric rises: findings)ANTs: “Convergence is determined from the number of iterations per level and is determined by fitting a line to the normalized energy profile of the last N iterations (where N is specified by the window size) and determining the slope which is then compared with the convergence threshold.”
-f 4x2x1, --shrink-factors RegistrationStage(shrink_factors=[4, 2, 1]) per level; per axis as CalculateShrinkFactorsPerDimension choosesANTs: “Specify the shrink factor for the virtual domain (typically the fixed image) at each level.”
-s 2x1x0vox / mm, --smoothing-sigmas RegistrationStage(smoothing_sigmas=[2, 1, 0], sigmas_in_mm=...) ANTs: “Specify the sigma of gaussian smoothing at each level. Units are given in terms of voxels (‘vox’) or physical spacing (‘mm’). Example usage is ‘4x2x1mm’ and ‘4x2x1vox’ where no units implies voxel spacing.”
-x mask / -x [fixed,moving], --masks RegistrationStage.masks=mask / (fixed, moving) None in the pair is ANTs’ NULLANTs: “Image masks to limit voxels considered by the metric. Two options are allowed for mask specification: 1) Either the user specifies a single mask to be used for all stages or 2) the user specifies a mask for each stage. With the latter one can select to which stages masks are applied by supplying valid file names. If the file does not exist, a mask will not be used for that stage. Note that we handle the fixed and moving masks separately to enforce this constraint.”
-g 1x1x0x1x1x1, --restrict-deformation RegistrationStage(restrict_deformation=[1, 1, 0, 1, 1, 1]) weights of the transform’s parametersANTs: “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 ‘1x1x0’ for a deformation field or ‘1x1x0x1x1x0’ for a rigid transformation. Low-dimensional restriction only works if there are no preceding transformations.All stages up to and including the desired stage must have this option specified,even if they should not be restricted (in which case specify 1x1x1…)”
-r file / -r [file,1] / -r [f,m,0/1/2], --initial-moving-transform initial_moving_transforms=[path or ItkTransforms, (t, True), AlignCenters(f, m, "geometry"/"moments"/"origins")] () a file whose last extension is not a transform file’s (.nii.gz, …) is a displacement field image; a composite may hold fields; a field has no inverse ([field,1] fails)ANTs: “Specify the initial moving transform(s) which get immediately incorporated into the composite transform. The order of the transforms is stack-esque in that the last transform specified on the command line is the first to be applied. In addition to initialization with ITK transforms, the user can perform an initial translation alignment by specifying the fixed and moving images and selecting an initialization feature. These features include using the geometric center of the images (=0), the image intensities (=1), or the origin of the images (=2).”
-q ..., --initial-fixed-transform initial_fixed_transforms= () ANTs: “Specify the initial fixed transform(s) which get immediately incorporated into the composite transform. The order of the transforms is stack-esque in that the last transform specified on the command line is the first to be applied. In addition to initialization with ITK transforms, the user can perform an initial translation alignment by specifying the fixed and moving images and selecting an initialization feature. These features include using the geometric center of the images (=0), the image intensities (=1), or the origin of the images (=2).”
-k state, --restore-state restore_state= None ANTs: “Specify the initial state of the registration which get immediately used to directly initialize the registration process. The flag is mutually exclusive with other intialization flags.If this flag is used, none of the initial-moving-transform and initial-fixed-transform cannot be used.”
-j state, --save-state (command line only) only on the command line (--save-state, needs -a 1): after a SyN stage, the composite before it and SyN’s fixed-to-middle and moving-to-middle fields, each followed by its inverse; after linear stages every transform (ANTS-50, ANTS-74)ANTs: “Specify the output file for the current state of the registration. The state file is written to an hdf5 composite file. It is specially usefull if we want to save the current state of a SyN registration to the disk, so we can load and restore that later to continue the next registration process directly started from the last saved state. The output file of this flag is the same as the write-composite-transform, unless the last transform is a SyN transform. In that case, the inverse displacement field of the SyN transform is also added to the output composite transform. Again notice that this file cannot be treated as a transform, and restore-state option must be used to load the written file by this flag.”
-w [0.005,0.995], --winsorize-image-intensities winsorize=(0.005, 0.995) None ANTs: “Winsorize data based on specified quantiles.”
-u 1, --use-histogram-matching use_histogram_matching=True False ANTs: “Histogram match the images before registration.”
-z 0/1, --collapse-output-transforms collapse_output_transforms= True default 1ANTs: “Collapse output transforms. Specifically, enabling this option combines all adjacent transforms wherepossible. All adjacent linear transforms are written to disk in the forman itk affine transform (called xxxGenericAffine.mat). Similarly, all adjacent displacement field transforms are combined when written to disk (e.g. xxxWarp.nii.gz and xxxInverseWarp.nii.gz (if available)).Also, an output composite transform including the collapsed transforms is written to the disk (called outputCollapsed(Inverse)Composite).”
-a 1, --write-composite-transform write_composite_transform=True False Composite.h5, InverseComposite.h5 (fields stored forward; the inverse composite holds the inverse fields)ANTs: “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.”
-i 1, --initialize-transforms-per-stage initialize_transforms_per_stage=True False needs -a 1 and -z 0ANTs: “Initialize linear transforms from the previous stage. By enabling this option, the current linear stage transform is directly intialized from the previous stage’s linear transform; this allows multiple linear stages to be run where each stage directly updates the estimated linear transform from the previous stage. (e.g. Translation -> Rigid -> Affine).”
-n Linear, --interpolation interpolation="Linear" "Linear" the warped images’ interpolator, as antsApplyTransforms -n, in every dimensionANTs: “Several interpolation options are available in ITK. These have all been made available. Currently the interpolator choice is only used to warp (and possibly inverse warp) the final output image(s).”
--float 1 precision="float32" "float64" ANTs’ single-precision pipelineANTs: “Use ‘float’ instead of ‘double’ for computations.”
--random-seed N / ANTS_RANDOM_SEED random_seed=N None without one: ANTs from the clock, larmorx 121212ANTs: “Use a fixed seed for random number generation. By default, the system clock is used to initialize the seeding. The fixed seed can be any nonzero int value.”
-p N, --print-similarity-measure-interval print_similarity_measure_interval=N 0 each of the result’s iterations gets its full_scale_valueANTs: “Prints out the CC similarity metric measure between the full-size input fixed and the transformed moving images at each iteration a value of 0 (the default) indicates that the full scale computation should not take placeany value greater than 0 represents the interval of full scale metric computation.”
--write-interval-volumes N (command line only) ANTs: “Writes out the output volume at each iteration. It helps to present the registration process as a short movie a value of 0 (the default) indicates that this option should not take placeany value greater than 0 represents the interval between the iterations which outputs are written to the disk.”
-v 1, --verbose the result its log and iterations: Python always runs verbose and parses the DIAGNOSTIC linesANTs: “Verbose output.”
--minc 1 – MINC transforms: not supported yetANTs: “Use MINC file formats for transformations.”
--version (command line only) the version lineANTs: “Get Version Information.”
-h, --help (command line only) ANTs’ short and long helpANTs: “Print the help menu (short version).”ANTs: “Print the help menu. Will also print values used on the current command line call.”
ITK_GLOBAL_DEFAULT_NUMBER_OF_THREADS n_threads 1 the result does not depend on it
LARMORX_UPSTREAM_DEFECTS upstream_defects= "fix" ANTS-49, -50, -51, ITK-18; the point-set metrics’ ANTS-61 to -63, -65 to -68, -70, ITK-22 to -24, -26, -28, -29; SyN’s ANTS-71, -73, -74, ITK-30 to -33; the B-spline and field stages’ ANTS-75, -76, -78, ITK-35, -42; the velocity-field stages’ ANTS-79 to -81, ITK-36 to -41 (upstream defects)

LARMORX’s own options

From the next release. In 0.1.0rc1, set the variables instead: OMP_NUM_THREADS, LARMORX_IMPLEMENTATION (original for the clean room) and LARMORX_UPSTREAM_DEFECTS.

They stand between larmorx and ants on the command line (larmorx --n-threads 4 ants antsRegistration ...); lx.ants.registration takes n_threads and upstream_defects as arguments, and the other is the command line’s only. Each one given wins over its environment variable, which keeps working.

Command line, then Python What it does
--n-threads N
n_threads=1
Default: every logical CPU on the command line (0), 1 in Python. The variable OMP_NUM_THREADS in 0.1.0rc1.
--implementation auto|replica|clean-room
(no Python argument)
The command line’s only: lx.ants.registration takes no implementation. The variable LARMORX_IMPLEMENTATION in 0.1.0rc1.
--upstream-defects fix|reproduce
upstream_defects="fix"
The variable LARMORX_UPSTREAM_DEFECTS in 0.1.0rc1.

Examples

The tests run every example below (validation/tests/test_reference.py), each section in a new folder where these inputs are made first: fixed.nii.gz (a synthetic head of 40 × 48 × 40 voxels of 4 mm), moving.nii.gz (a synthetic head of 40 × 48 × 40 voxels of 4 mm). The command lines run as python -m larmorx.

python
import larmorx as lx

# A rigid stage with Mattes on a quarter of the voxels, two levels, a fixed seed.
stage = lx.ants.RegistrationStage(
    transform="Rigid", gradient_step=0.1,
    metrics=lx.ants.RegistrationMetric("Mattes", "fixed.nii.gz", "moving.nii.gz",
                                       bins=32, sampling="Regular", sampling_percentage=0.25),
    iterations=[20, 10], shrink_factors=[2, 1], smoothing_sigmas=[1, 0],
)
res = lx.ants.registration([stage], random_seed=42)
res.files["0GenericAffine.mat"][0].name  # -> 'AffineTransform_double_3_3'
bash
larmorx ants antsRegistration -d 3 -o [out_,out_warped.nii.gz] -t Rigid[0.1] -m Mattes[fixed.nii.gz,moving.nii.gz,1,32,Regular,0.25] -c [20x10,1e-6,10] -f 2x1 -s 1x0vox --random-seed 42

Ports

antsRegistration has one port: a replica.

Port Package Licence Status Records
replica larmorx (built in) Apache-2.0 validated ants-registration

The replica: status validated against antsRegistration itself (its record, standard tier, 2026-10-28, and the full tier’s records): every compared case identical to ANTs 2.6.5 at one thread with the same seed (exit status, standard output with every DIAGNOSTIC line, standard error, every file), most against the unmodified binary, the rest once glibc’s exp/log/sin/cos are replaced by CORE-MATH’s correctly rounded ones, which larmorx uses (CLAUDE.md rule 5).

Tier Cases Identical to the unmodified ANTs Identical with CORE-MATH Rejected by both Expected divergences Failures
standard (2026-10-28) 513 355 44 93 21 0
full (record, A5 part 2’s run, 2026-10-21) 441 278 68 77 18 0
full, A5 part 3’s cases (record, 2026-10-23) 124 77 26 16 5 0

The cases cover every transform in 2D, 3D and 4D, double and float, every metric and sampling, masks, the initial transforms and their files, every output and interpolator, every command-line check and message, fMRIPrep 25.2.6’s own command lines of four oracle nodes, and (full tier) the linear stages of sMRIPrep’s brain extraction and template registration in all five oracle runs, and (A4 part 4) the point-set metrics: each metric alone and with the others and image metrics, label images (with boundary points), text and VTK point sets (ASCII, binary, without scalars), in-memory points, 2D, 3D and 4D, double and float, initial transforms, several levels and stages, and every message, failure and crash; and (A5 part 1) SyN stages with each metric, several metrics, masks, sampling, 2D, 3D and 4D, double and float, the collapse and every output, displacement fields among the initial transforms, saved and restored states, the point-set metrics in tangent space, and sMRIPrep’s two SyN registrations. The expected divergences: no seed (ANTs from the clock), ANTS-51’s crash, --version, three of ANTS-45’s silent failures, MINC transforms (refused), a point set’s random fraction (ANTs seeds it from the clock, ANTS-64), IGDM’s value for neighbourhoods of more than one voxel (ANTs reads before its arrays, ANTS-66), a text point set ANTs reads forever (ANTS-69), four linear stages after a displacement field (ANTs seeds their voxel sample from the clock, ANTS-72); A5 part 2 added ANTS-77’s two B-spline meshes (a size of 0, fewer sizes than dimensions: ANTs fails on garbage, larmorx refuses); A5 part 3 added three samplings of the velocity-field stages (ANTs seeds them from the clock, ANTS-82), an affine stage after a velocity field (ANTS-72) and a time-varying B-spline mesh of 0 (ANTS-77). The velocity-field stages, an expected divergence while larmorx refused them (syn/exponential), are compared since A5 part 3.

ANTs’ own result moves with its thread count, from about 1e-13 in a transform parameter on the phantoms to 1.7 in the standard record’s 36 cases at 2, 4 and 8 threads (the full account: How the records grew); larmorx gives the one-thread result at any thread count.

On the data panel (record, 2026-10-27): every antsRegistration node of the fourteen finished fMRIPrep oracle runs, each replayed from its node with its inputs and fMRIPrep’s seed (the BOLD references’ registrations to the template, the field maps’ coregistrations, sMRIPrep’s brain extraction at full size: 3.5-year-old, glioma, stroke, strong motion, 1.5 T, 7 T, multiband-8 and multi-echo among them), and the template registrations on every third voxel: 71 of 71 cases identical to ANTs 2.6.5 at one thread, 16 as built and 55 more with CORE-MATH (warped images, transforms, standard output). The template registration’s inputs, which niworkflows writes for itself and nipype does not keep, are made again exactly from each node’s recorded inputs; its fourteen whole-size runs (about 2.4 hours of ANTs at one thread each, as built and with CORE-MATH) are left for a larger machine. sMRIPrep’s brain extraction of the 7 T head at full size: ANTs 2884 MiB and 2431 s at one thread, larmorx 2394 MiB and 1165 s, its four files identical.

antsRegistration has one port, in pip install larmorx: the replica (Rust larmorx_ants::registration::helper::RegistrationHelper and the crate larmorx-registration; Apache-2.0), translated from ANTs 2.6.5’s antsRegistration on ITK 5.4.5’s v4 registration framework (Apache-2.0). Results do not depend on threads. ANTs’ do (its metrics sum per work unit); larmorx always gives ANTs’ one-thread result. Without a seed ANTs is not repeatable (its sampling is seeded from the clock); larmorx then uses a fixed seed (121212).

Evidence

How each of antsRegistration’s ports was measured against ANTs, case by case: its evidence.

More in the repository

The API page docs/api/ants-registration.md holds what antsRegistration shares with the page’s other programs: