- source
the moving volume to be aligned, a 3D array (for example a
'CT'); the result transform maps target into this image's space.
May also be a list of already co-registered 3D arrays (multiple
modalities such as 'T1', 'T2', an atlas constraint); all source
channels must share the same dimensions and vox2ras
- target
the fixed/reference volume to align to, a 3D array (for example
a 'MRI'), or a list of co-registered arrays matching
source channel-for-channel
- source_vox2ras, target_vox2ras
4x4 (or 3x4) matrices mapping the
0-indexed voxel coordinate (column-row-slice, 'C'-style starting from
0, complying with 'NIfTI') to the RAS coordinate system; if
NULL, the function looks for a "vox2ras" attribute on the array
- source_mask, target_mask
optional 3D mask arrays restricting where the
metric is evaluated; default NULL (no mask, evaluate everywhere). A
target_mask (on the target/fixed grid, same dimensions as
target) limits which target voxels drive the registration; a
source_mask (on the source/moving grid) drops samples that map outside
it. Non-zero voxels are included. Besides focusing the alignment on a region
of interest, masks speed things up by skipping background: the linear stage
samples only inside the mask, and the deformable stage skips warping voxels
outside the (dilated) mask. One mask per grid, shared across channels
- source_points, target_points
optional N x 3 matrices of
corresponding landmark coordinates that add a surface/landmark term to the
deformable ("syn"/"syn_only") stage; default
NULL (no term). Row i of target_points (in the
target/fixed RAS) and row i of source_points (in the
source/moving RAS) must be the same anatomical location, for
example corresponding cortical-surface vertices from a 'FreeSurfer'
spherical registration. The term pulls the warp of each target point onto its
source correspondent, recovering cortical folding (gyrification)
that the intensity metric blurs over, while the image metric still drives
deep-brain subcortical structures. Must be supplied together with
equal row counts. Points must be in the same RAS frame as
source_vox2ras/target_vox2ras (note 'FreeSurfer'
surfaces use surface/tkr RAS, which differs from scanner
RAS by c_ras)
- points_weight
relative weight of the landmark term against the image
metric in the deformable stage; default 0.5. Larger values follow the
landmarks more closely. The sparse landmark force is attenuated by
syn_sigma smoothing, so this typically needs tuning for a given point
count and spacing
- weights
optional numeric weights, one per source/target pair,
controlling each channel's contribution to the deformable cost; default is
equal weighting. Weights are normalized internally to sum to 1. Only the
deformable ("syn"/"syn_only") stage is multivariate; the linear
stage always uses the first (primary) pair
- type
type of transform to estimate; one of 'rigid' (6 degrees
of freedom), 'affine' (12), "syn" (affine followed
by a SDR - symmetric diffeomorphic deformation), or
'syn_only' (deformable stage only — no affine is
estimated; init_transform is used directly as the starting
affine, useful when you already have a good linear alignment)
- metric
similarity metric: "mattes" (Mattes mutual information,
the default, best for cross-modal such as 'CT'-'MRI'),
"cc" (normalized cross-correlation, for same-modality), or
"meansquares" (mean squared intensity difference). With multiple
channels, supply either a single metric (used for every pair) or a vector
with one metric per source/target pair
- shrink_factors
integer down-sampling factors, one per resolution level
(coarsest first); default c(4, 2, 1)
- smoothing_sigmas
Gaussian smoothing applied at each level, in voxels,
same length as shrink_factors; default c(2, 1, 0)
- iterations
maximum optimizer iterations per level; default
c(1000, 500, 250)
- sampling_rate
fraction of fixed voxels sampled to evaluate the metric
(speeds up large volumes); default 0.2
- interpolation
output interpolation used when warping each modality
onto the target grid: 'trilinear' (default), 'nearest' (keeps
label or segmentation values intact), or "bspline" (cubic
Catmull-Rom, higher quality, slower). Like metric, supply a
single value (applied to every channel) or one per source/target pair. This
affects only the returned warped images, never the optimization's internal
sampling (always 'trilinear', so every channel still produces
smooth gradients)
- number_of_bins
number of histogram bins for the "mattes"
metric; default 32
- seed
random seed for the voxel sampler, for reproducibility
- init_transform
optional 4x4 initial RAS-to-RAS
transform (fixed to moving) to start from
- syn_iterations, syn_sigma
deformable stage controls (only used when
type = "syn" or "syn_only"): per-level iteration counts and the
Gaussian regularization sigma (in voxels) applied to the update field. Both
are recycled to the number of levels, so syn_sigma may be a vector to
vary the regularization per stage (e.g. c(3, 3, 1) to relax it at the
finest level for sharper detail)
- verbose
logical; if TRUE (default) print per-level and
per-iteration progress to the console, including the current stage, shrink
factor, smoothing sigma, cost metric, and step size (linear) or maximum
displacement (deformable); useful to monitor convergence on large volumes