Perform registration between two images. — antsRegistration • ANTsR

antsRegistration(
  fixed = NULL,
  moving = NULL,
  typeofTransform = "SyN",
  initialTransform = NA,
  outprefix = NULL,
  mask = NULL,
  movingMask = NULL,
  maskAllStages = FALSE,
  gradStep = 0.2,
  flowSigma = 3,
  totalSigma = 0,
  affMetric = "mattes",
  affSampling = 32,
  synMetric = "mattes",
  synSampling = 32,
  affIterations,
  regIterations = c(40, 20, 0),
  multivariateExtras,
  restrictTransformation,
  writeCompositeTransform = FALSE,
  randomSeed,
  samplingPercentage = 0.2,
  verbose = FALSE,
  printArgs = FALSE,
  ...
)

Arguments

fixed: fixed image to which we register the moving image.
moving: moving image to be mapped to fixed space.
typeofTransform: A linear or non-linear registration type. Mutual information metric by default. See Details.
initialTransform: either a single transform file name, a vector of transform file names, or a single antsTransform object. If NA, an initial translation aligns the center of mass of the moving image to that of the fixed image.
outprefix: output will be named with this prefix.
mask: Registration metric mask in the fixed image space.
movingMask: Registration metric mask in the moving image space.
maskAllStages: If true, apply metric mask(s) to all registration stages, instead of just the final stage.
gradStep: gradient step size (not for all tx)
flowSigma: smoothing for update field
totalSigma: smoothing for total field
affMetric: the metric for the affine part (GC, mattes, meansquares)
affSampling: the sampling parameter for the affine metric
synMetric: the metric for the syn part (CC, mattes, meansquares, demons)
synSampling: the nbins or radius parameter for the syn metric
affIterations: vector of iterations for low-dimensional registration. we will set the smoothing and multi-resolution parameters based on the length of this vector.
regIterations: vector of iterations for syn. we will set the smoothing and multi-resolution parameters based on the length of this vector.
multivariateExtras: list of additional images and metrics which will trigger the use of multiple metrics in the registration process in the deformable stage. Multivariate metrics needs 5 entries: name of metric, fixed, moving, weight, samplingParam. the list should be of the form list( list( "nameOfMetric2", img, img, weight, metricParam ) ) . Another example would be list( list( "MeanSquares", f2, m2, 0.5, 0 ), list( "CC", f2, m2, 0.5, 2 ) ). This is only compatible with the SyNOnly, ElasticOnly, or antsRegistrationSyN* transformations.
restrictTransformation: 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 c(1,1,0) for a 3D deformation field or c(1,1,0,1,1,0) for a rigid transformation. Restriction currently only works if there are no preceding transformations.
writeCompositeTransform: if TRUE, will write transformations to h5 format. Defaults to FALSE.
randomSeed: integer random seed. combine with setting ITK_GLOBAL_DEFAULT_NUMBER_OF_THREADS environment variable to limit the impact of numerical differences.
samplingPercentage: value between zero and one that allows the percentage of points sampled to be controlled in low-dimensional metric estimation.
verbose: request verbose output (useful for debugging)
printArgs: print raw command line (useful for debugging)
...: additional options see antsRegistration in ANTs

Value

outputs a list containing:

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.

Ouptut of 1 indicates failure

Details

typeofTransform can be one of:

"Translation": Translation transformation.
"Rigid": Rigid transformation: Only rotation and translation.
"Similarity": Similarity transformation: 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.
"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).
"ElasticSyN": Symmetric normalization: Affine + deformable transformation. Uses synMetric as optimization metric and elastic regularization.
"SyN": Symmetric normalization: Affine + deformable transformation. Uses synMetric as optimization metric.
"SyNRA": Symmetric normalization: Rigid + Affine + deformable transformation. Uses synMetric as optimization metric.
"SyNOnly": Symmetric normalization: no initial transformation. Uses synMetric as optimization metric. Assumes images are aligned by an inital transformation. Can be useful if you want to run an unmasked affine followed by masked deformable registration.
"ElasticOnly": Elastic normalization: no initial transformation.
"SyNCC": SyN, but with cross-correlation as the metric. Note, the default or chosen parameters will be replaced with synMetric="CC", synSampling=4, synits="2100x1200x1200x20", smoothingsigmas="3x2x1x0", shrinkfactors="4x3x2x1".
"SyNabp": SyN optimized for abpBrainExtraction, forces mutual information as optimization metric.
"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.
"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
"Elastic": simple elastic deformation. one might want to run an affine transformation before this. may not produce diffeomorphic transformations. user may need to explore gradient and sigma parameters. this will not produce a valid inverse deformation. totalSigma should be greater than zero.
"antsRegistrationSyN[x]":recreation of the antsRegistrationSyN.sh script in ANTs where 'x' is one of the transforms available (e.g., 't', 'b', 's')
"antsRegistrationSyNQuick[x]":recreation of the antsRegistrationSyNQuick.sh script in ANTs where 'x' is one of the transforms available (e.g., 't', 'b', 's')
"antsRegistrationSyNRepro[x]":reproducible registration. x options as above.
"antsRegistrationSyNQuickRepro[x]":quick reproducible registration. x options as above.

Author

Shrinidhi KL, Tustison NJ, Avants BB

Examples


# print help
antsRegistration()
#> for simplified mode: 
#>  antsRegistration( fixed , moving , typeofTransform = c("Rigid","Affine","AffineFast","SyN","SyNCC"),  outputPrefix="./antsRegOut" 
#> For full mode: use standard ants call , e.g. : 
#>  ANTsR::antsRegistration( list( d=2,m="mi[r16slice.nii.gz,r64slice.nii.gz,1,20,Regular,0.05]", t="affine[1.0]", c="2100x1200x1200x0",  s="3x2x1x0", f="4x3x2x1", u="1", o="[xtest,xtest.nii.gz,xtest_inv.nii.gz]" ) )
#> full help: 
#> [1] 0
fi <- antsImageRead(getANTsRData("r16"))
mi <- antsImageRead(getANTsRData("r64"))
mytx2 <- antsRegistration(fixed = fi, typeofTransform = "")
#> for simplified mode: 
#>  antsRegistration( fixed , moving , typeofTransform = c("Rigid","Affine","AffineFast","SyN","SyNCC"),  outputPrefix="./antsRegOut" 
#> For full mode: use standard ants call , e.g. : 
#>  ANTsR::antsRegistration( list( d=2,m="mi[r16slice.nii.gz,r64slice.nii.gz,1,20,Regular,0.05]", t="affine[1.0]", c="2100x1200x1200x0",  s="3x2x1x0", f="4x3x2x1", u="1", o="[xtest,xtest.nii.gz,xtest_inv.nii.gz]" ) )
#> full help: 
rig <- antsRegistration(
  fixed = fi, moving = mi,
  typeofTransform = "Rigid", verbose = TRUE
)
trans <- readAntsrTransform(rig$fwdtransforms, 2)
postrig <- antsRegistration(
  fixed = fi, moving = mi,
  typeofTransform = "Affine", initialTransform = trans
)
for (itype in c("AffineFast", "BOLDAffine")) {
  print(itype)
  mytx2 <- antsRegistration(
    fixed = fi, moving = mi,
    typeofTransform = itype
  )
}
#> [1] "AffineFast"
#> [1] "BOLDAffine"
mytx2 <- antsRegistration(
  fixed = fi, moving = mi,
  typeofTransform = "SyNOnly",
  multivariateExtras = list(list("MeanSquares", fi, mi, 0.5, 0))
)
testthat::expect_error(
  antsRegistration(fixed = fi, moving = mi, typeofTransform = "sdf")
)
bad <- antsRegistration(fixed = fi, moving = mi, regIterations = 40)
affIterations <- c(3, 2, 1, 0)
mytx2 <- antsRegistration(
  fixed = fi, moving = mi,
  affIterations = affIterations
)
# set below for slower but numerically repeatable results
# these should be set in .Renviron not by sys calls
#  Sys.setenv(ITK_GLOBAL_DEFAULT_NUMBER_OF_THREADS = 1)
#  Sys.setenv(ANTS_RANDOM_SEED = 20180716)
fi <- antsImageRead(getANTsRData("r16"))
mi <- antsImageRead(getANTsRData("r64"))
fi <- resampleImage(fi, c(60, 60), 1, 0)
mi <- resampleImage(mi, c(50, 50), 1, 0) # speed up
mytx <- antsRegistration(fixed = fi, moving = mi, typeofTransform = c("SyN"))
mywarpedimage <- antsApplyTransforms(
  fixed = fi, moving = mi,
  transformlist = mytx$fwdtransforms
)
mytx2 <- antsRegistration(fixed = fi, moving = mi, typeofTransform = c("SyN"))
mywarpedimage2 <- antsApplyTransforms(
  fixed = fi, moving = mi,
  transformlist = mytx2$fwdtransforms
)
# testthat::expect_equal(as.array(mywarpedimage), as.array(mywarpedimage2))

if (FALSE) { # \dontrun{
# quick visualization fix for images with odd orientation
mni <- antsImageRead(getANTsRData("mni"))
strokt1 <- antsImageRead("strokt1.nii.gz")
strokt1reg <- antsRegistration(
  fixed = mni,
  moving = strokt1,
  typeofTransform = "QuickRigid", verbose = TRUE
)
plot(strokt1reg$warpedmovout, axis = 3, nslices = 20)
# now - how to use a mask
fi <- antsImageRead(getANTsRData("r16"))
fiseg <- kmeansSegmentation(fi, 3)
mi <- antsImageRead(getANTsRData("r64"))
msk <- thresholdImage(fiseg$segmentation, 0, 0)
mytx <- antsRegistration(
  fixed = fi, moving = mi, typeofTransform = c("SyNCC"),
  mask = msk, verbose = F
)
jac <- createJacobianDeterminantImage(fi, mytx$fwdtransforms[1])
} # }