ANTSREGISTRATION(1)

💖 ANTSREGISTRATION(1) 💖

Okay bestie, this is the manual page for antsRegistration, filed under User Commands in section 1 🦋 Let's get into it!

---

✨ NAME ✨

antsRegistration, part of the ANTS registration suite 🎀

---

💅 DESCRIPTION 💅

🌸 COMMAND:

antsRegistration

Okay so this is a user-level registration app, and it's built on the classes in ITK v4.0 and later 💜 You can set up any number of "stages." Each stage is a transform, plus an image metric, plus iterations, shrink factors, and smoothing sigmas for every level. It's giving customization 💅

⚠️ Mandatory, no cap: you have to explicitly set the dimensionality, metric, transform, output, convergence, shrink-factors, and smoothing-sigmas parameters. No skipping these!

🎀 OPTIONS:

• --version — Gets your version info ✨
• -d, --dimensionality 2/3/4 — This forces the image to be treated as an image of the dimensionality you pick 🦋 If you don't set it, we try to figure it out from the input image.
• -o, --output outputTransformPrefix — Here's where you set the output transform prefix (the output format is .nii.gz 💖). You can also warp the moving image into the fixed space, and if the inverse transform exists, you can output the warped fixed image too. Heads up: only the images from the first metric call get warped. For everything else, use antsApplyTransforms with the resulting transform(s) 🫶 Also, when you don't specify a composite transform, linear transforms get a .mat suffix and displacement fields get a Warp.nii.gz suffix (plus InverseWarp.nii.gz when that applies). For velocity-based transforms, the full velocity field gets written to VelocityField.nii.gz as long as the collapse transforms flag is off (-z 0) 🌈

[outputTransformPrefix,<outputWarpedImage>,<outputInverseWarpedImage>]

• -j, --save-state saveStateAsTransform — This saves the current state of the registration to a file 🍓 It's especially useful when you want to save the state of a SyN registration to disk, so you can load and restore it later and keep going from where you left off. The file is written as an hdf5 composite file. It's the same as the write-composite-transform output, except when the last transform is a SyN transform. In that case, the inverse displacement field of the SyN transform gets added to the output composite transform too. Also, this file isn't a transform, so you have to load it back in with the restore-state option 🙈
• -k, --restore-state restoreStateAsATransform — This sets the initial state of the registration, and it gets used right away to start the registration process 🧚 This flag can't be combined with other initialization flags. If you use it, you can't use the initial-moving-transform or the initial-fixed-transform either 💀
• -a, --write-composite-transform 1/(0) — This is a yes-or-no flag for whether the composite transform (plus its inverse, if there is one) gets written to an hdf5 composite file. It's off by default, so only each stage's transform gets written to file 💜 Values: 0
• -p, --print-similarity-measure-interval <unsignedIntegerValue> — This prints the CC similarity metric between the full-size input fixed image and the transformed moving image at each iteration 📈 A value of 0 (the default) means the full-scale computation doesn't happen. Any value above 0 sets the interval for full-scale metric computation 🌸 Values: 0
• --write-interval-volumes <unsignedIntegerValue> — This writes out the output volume at each iteration, so you can turn the whole registration into a short movie 🎬 A value of 0 (the default) means this option doesn't do anything. Any value above 0 sets the interval between iterations whose outputs get written to disk 🩷 Values: 0
• -z, --collapse-output-transforms (1)/0 — This collapses output transforms, which means it combines all the adjacent transforms wherever it can 🧠 All adjacent linear transforms get written to disk as an ITK affine transform called xxxGenericAffine.mat. Adjacent displacement field transforms get combined too when they're written, like xxxWarp.nii.gz and xxxInverseWarp.nii.gz (if that one exists). Plus, an output composite transform that includes the collapsed transforms gets written to disk, called outputCollapsed(Inverse)Composite 👑 Values: 1
• -i, --initialize-transforms-per-stage (1)/0 — This initializes linear transforms from the previous stage 🦋 When it's on, the current linear stage's transform is initialized straight from the previous stage's linear transform. That means you can run multiple linear stages, where each one keeps refining the estimated linear transform from the stage before it, like Translation -> Rigid -> Affine ✨ Values: 0
• -n, --interpolation Linear — Here are the interpolation options. ITK offers a bunch of them and they've all been made available 🌈 Right now, the interpolator choice only gets used to warp (and possibly inverse warp) the final output image(s), so keep that in mind 🫶

Linear
NearestNeighbor MultiLabel[<sigma=imageSpacing>,<alpha=4.0>]
Gaussian[<sigma=imageSpacing>,<alpha=1.0>] BSpline[<order=3>]
CosineWindowedSinc WelchWindowedSinc HammingWindowedSinc
LanczosWindowedSinc GenericLabel[<interpolator=Linear>]

• -g, --restrict-deformation PxQxR — This lets you restrict the optimization of the displacement field, translation, rigid, or affine transform on a per-component basis 🎀 For example, if you want to limit the deformation or rotation of a 3-D volume to its first two dimensions, you can give a weight vector of 1x1x0 for a deformation field, or 1x1x0x1x1x0 for a rigid transformation. Heads up: low-dimensional restriction only works when there are no preceding transformations. Also, every stage up to and including the one you want must have this option set, even the stages you don't want restricted (for those, specify 1x1x1...) 🙈
• -q, --initial-fixed-transform initialTransform — This sets the initial fixed transform(s), which get folded into the composite transform right away 💖 The order is stack-esque, so the last transform you list on the command line is the first one applied 🥞 Besides ITK transforms, you can also do an initial translation alignment by giving the fixed and moving images plus an initialization feature. The features are the geometric center of the images (=0), the image intensities (=1), or the origin of the images (=2) 🧚

initialTransform
[initialTransform,<useInverse>]
[fixedImage,movingImage,initializationFeature]

• -r, --initial-moving-transform initialTransform — This sets the initial moving transform(s), which get folded into the composite transform right away 🌸 Same deal as the fixed one: the order is stack-esque, so the last transform on the command line is applied first 🥞 You can also do an initial translation alignment with fixed and moving images plus an initialization feature, using the geometric center (=0), the image intensities (=1), or the origin (=2) 🦋

initialTransform
[initialTransform,<useInverse>]
[fixedImage,movingImage,initializationFeature]

• -m, --metric — These are the image metrics you can use, and the list is long, so take a deep breath 💅 The image metrics are CC (ANTS neighborhood cross correlation), MI (mutual information), Demons (Thirion), MeanSquares, and GC (Global Correlation). The metricWeight value lets you tune how much each metric counts per stage ⚖️ The metrics can also use a sampling strategy, defined by a sampling percentage. The sampling strategy defaults to None, which is dense sampling of one sample per voxel. Otherwise, it defines a point set to optimize the metric over. That point set can sit on a regular lattice, or a random lattice of points that's slightly perturbed to cut down on aliasing artifacts 🌀 samplingPercentage is the fraction of points to pick from the domain. useGradientFilter decides whether a smoothing filter gets applied when the metric gradient is estimated 🫧 There are also three point set metrics: Euclidean (ICP), Point-set expectation (PSE), and Jensen-Havrda-Charvet-Tsallis (JHCT) 👑

CC[fixedImage,movingImage,metricWeight,radius,<samplingStrategy={None,Regular,Random}>,<samplingPercentage=[0,1]>,<useGradientFilter=false>]

MI[fixedImage,movingImage,metricWeight,numberOfBins,<samplingStrategy={None,Regular,Random}>,<samplingPercentage=[0,1]>,<useGradientFilter=false>]
Mattes[fixedImage,movingImage,metricWeight,numberOfBins,<samplingStrategy={None,Regular,Random}>,<samplingPercentage=[0,1]>,<useGradientFilter=false>]
MeanSquares[fixedImage,movingImage,metricWeight,radius=NA,<samplingStrategy={None,Regular,Random}>,<samplingPercentage=[0,1]>,<useGradientFilter=false>]
Demons[fixedImage,movingImage,metricWeight,radius=NA,<samplingStrategy={None,Regular,Random}>,<samplingPercentage=[0,1]>,<useGradientFilter=false>]
GC[fixedImage,movingImage,metricWeight,radius=NA,<samplingStrategy={None,Regular,Random}>,<samplingPercentage=[0,1]>,<useGradientFilter=false>]
ICP[fixedPointSet,movingPointSet,metricWeight,<samplingPercentage=[0,1]>,<boundaryPointsOnly=0>]
PSE[fixedPointSet,movingPointSet,metricWeight,<samplingPercentage=[0,1]>,<boundaryPointsOnly=0>,<pointSetSigma=1>,<kNeighborhood=50>]
JHCT[fixedPointSet,movingPointSet,metricWeight,<samplingPercentage=[0,1]>,<boundaryPointsOnly=0>,<pointSetSigma=1>,<kNeighborhood=50>,<alpha=1.1>,<useAnisotropicCovariances=1>]
IGDM[fixedImage,movingImage,metricWeight,fixedMask,movingMask,<neighborhoodRadius=0x0>,<intensitySigma=0>,<distanceSigma=0>,<kNeighborhood=1>,<gradientSigma=1>]

• -t, --transform — pick your transform, the big boss of registration 🦋 The list below is every option, exactly as they're spelled. Each one has its own arguments, and the gradientStep (or learningRate) sets how the gradient descent optimization behaves. That value gets scaled properly for each transform by the shift scales estimator, so you don't have to babysit it. The stuff after that is transform-specific, and you can figure it out from the usage. For the B-spline transforms you can also set smoothing by spline distance (aka knot spacing) 🧚

Rigid[gradientStep]
Affine[gradientStep] CompositeAffine[gradientStep]
Similarity[gradientStep] Translation[gradientStep]
BSpline[gradientStep,meshSizeAtBaseLevel]
GaussianDisplacementField[gradientStep,updateFieldVarianceInVoxelSpace,totalFieldVarianceInVoxelSpace]
BSplineDisplacementField[gradientStep,updateFieldMeshSizeAtBaseLevel,<totalFieldMeshSizeAtBaseLevel=0>,<splineOrder=3>]
TimeVaryingVelocityField[gradientStep,numberOfTimeIndices,updateFieldVarianceInVoxelSpace,updateFieldTimeVariance,totalFieldVarianceInVoxelSpace,totalFieldTimeVariance]
TimeVaryingBSplineVelocityField[gradientStep,velocityFieldMeshSize,<numberOfTimePointSamples=4>,<splineOrder=3>]
SyN[gradientStep,<updateFieldVarianceInVoxelSpace=3>,<totalFieldVarianceInVoxelSpace=0>]
BSplineSyN[gradientStep,updateFieldMeshSizeAtBaseLevel,<totalFieldMeshSizeAtBaseLevel=0>,<splineOrder=3>]
Exponential[gradientStep,updateFieldVarianceInVoxelSpace,velocityFieldVarianceInVoxelSpace,<numberOfIntegrationSteps>]
BSplineExponential[gradientStep,updateFieldMeshSizeAtBaseLevel,<velocityFieldMeshSizeAtBaseLevel=0>,<numberOfIntegrationSteps>,<splineOrder=3>]

• -c, --convergence MxNxO — convergence check time! 🎀 The value is MxNxO, which is [MxNxO,<convergenceThreshold=1e-6>,<convergenceWindowSize=10>]. Convergence is figured out from how many iterations happen per level. ANTs fits a line to the normalized energy profile of the last N iterations (N is your window size), takes the slope, and compares it to the convergence threshold 💅
• -s, --smoothing-sigmas MxNxO... — set the gaussian smoothing sigma for each level 🌸 You can pick units: voxels ('vox') or physical spacing ('mm'). Examples are '4x2x1mm' and '4x2x1vox'. No unit at all means voxel spacing ✨
• -f, --shrink-factors MxNxO... — set the shrink factor for the virtual domain (usually the fixed image) at each level 🍓
• -u, --use-histogram-matching — histogram match the images before registration, so they match up nicely first 🫶
• -w, --winsorize-image-intensities [lowerQuantile,upperQuantile] — winsorize the data using the quantiles you give it 💜
• -x, --masks [fixedImageMask,movingImageMask] — image masks that limit which voxels the metric looks at 👑 You get two choices here. Either you give one mask and it's used for every stage, or you give a mask for each stage. With per-stage masks you pick which stages get masks by supplying valid file names. If a file doesn't exist, that stage just goes without a mask. Also, the fixed and moving masks get handled separately, and that's how this rule is enforced 🔥
• --float — use 'float' instead of 'double' for computations. Lighter, but make sure that's what you want 🌈
• --minc — use MINC file formats for transformations 🦋 <VALUES>: 0
• --random-seed seedValue — use a fixed seed for random number generation 🌙 By default the system clock sets up the seeding. Your fixed seed can be any nonzero int value ⭐
• -v, --verbose (0)/1 — verbose output, so you can see everything it's doing 🙈
• -h — print the help menu (short version) 💖
• --help — print the full help menu. It'll also print the values used on your current command line call, which is very helpful when you forget what you typed 😭 <VALUES>: 1

---

Okay bestie that's the whole page 💖 This one is from antsRegistration 2.6.4+dfsg, dated December 2025 🌸 Go register some images and slay ✨🫶