sct_register_multimodal

This program co-registers two 3D volumes. The deformation is non-rigid and is constrained along Z direction (i.e., axial plane). Hence, this function assumes that orientation of the destination image is axial (RPI). If you need to register two volumes with large deformations and/or different contrasts, it is recommended to input spinal cord segmentations (binary mask) in order to achieve maximum robustness. The program outputs a warping field that can be used to register other images to the destination image. To apply the warping field to another image, use sct_apply_transfo

Tips:

  • For a registration step using segmentations, use the MeanSquares metric. Also, simple algorithm will be very efficient, for example centermass as a ‘preregistration’.

  • For a registration step using images of different contrast, use the Mutual Information (MI) metric.

  • Combine the steps by increasing the complexity of the transformation performed in each step, for example:

    -param step=1,type=seg,algo=slicereg,metric=MeanSquares:
           step=2,type=seg,algo=affine,metric=MeanSquares,gradStep=0.2:
           step=3,type=im,algo=syn,metric=MI,iter=5,shrink=2
    
  • When image contrast is low, a good option is to perform registration only based on the image segmentation, i.e. using type=seg

  • Columnwise algorithm needs to be applied after a translation and rotation such as centermassrot algorithm. For example:

-param step=1,type=seg,algo=centermassrot,metric=MeanSquares:
       step=2,type=seg,algo=columnwise,metric=MeanSquares
usage: sct_register_multimodal -i <file> -d <file> [-h] [-iseg <file>]
                               [-dseg <file>] [-ilabel <file>] [-dlabel <file>]
                               [-initwarp <file>] [-initwarpinv <file>]
                               [-m <file>] [-o <file>] [-owarp <file>]
                               [-owarpinv <file>] [-param <list>]
                               [-identity <int>] [-z <int>]
                               [-x {nn,linear,spline}] [-ofolder <folder>]
                               [-qc <folder>] [-qc-dataset <str>]
                               [-qc-subject <str>] [-r <int>] [-v <int>]

MANDATORY ARGUMENTS

-i

Image source. Example: src.nii.gz

-d

Image destination. Example: dest.nii.gz

OPTIONAL ARGUMENTS

-iseg

Segmentation source. Example: src_seg.nii.gz

-dseg

Segmentation destination. Example: dest_seg.nii.gz

-ilabel

Labels source.

-dlabel

Labels destination.

-initwarp

Initial warping field to apply to the source image.

-initwarpinv

Initial inverse warping field to apply to the destination image (only use if you wish to generate the dest->src warping field)

-m

Mask that can be created with sct_create_mask to improve accuracy over region of interest. This mask will be used on the destination image. Masks will be binarized at 0.5. Example: mask.nii.gz

-o

Name of output file. Example: src_reg.nii.gz

-owarp

Name of output forward warping field.

-owarpinv

Name of output inverse warping field.

-param

Parameters for registration. Separate arguments with ,. Separate steps with :. Example: step=1,type=seg,algo=slicereg,metric=MeanSquares:step=2,type=im,algo=syn,metric=MI,iter=5,shrink=2

  • step: Step number (starts at 1, except for type=label).

  • type: {im, seg, imseg, label} type of data used for registration. If you specify ‘im’, you must also provide arguments -i and -d. If you specify ‘seg’, you must provide -iseg and -dseg. If you specify imseg, you must provide all four arguments. If you specify -label, you must provide -ilabel and -dlabel. ((Note: Use type=label only at step=0. Use type=imseg only for algo=centermassrot along with rot_method=hog or rot_method=pca_hog.))

  • algo: The algorithm used to compute the transformation. Default=syn

    • translation: translation in X-Y plane (2dof)

    • rigid: translation + rotation in X-Y plane (4dof)

    • affine: translation + rotation + scaling in X-Y plane (6dof)

    • syn: non-linear symmetric normalization

    • bsplinesyn: syn regularized with b-splines

    • slicereg: regularized translations (see: goo.gl/Sj3ZeU)

    • centermass: slicewise center of mass alignment (seg only).

    • centermassrot: slicewise center of mass and rotation alignment using method specified in ‘rot_method’

    • columnwise: R-L scaling followed by A-P columnwise alignment (seg only).

    • dl: Contrast-agnostic, deep learning-based registration based on the SynthMorph architecture. Can be run using: -param step=1,type=im,algo=dl

  • slicewise: Slice-by-slice 2d transformation. Default=0.

  • metric: {CC, MI, MeanSquares}. Default=MeanSquares.

    • CC: The cross correlation metric compares the images based on their intensities but with a small normalization. It can be used with images with the same contrast (for ex. T2-w with T2-w). In this case it is very efficient but the computation time can be very long.

    • MI: the mutual information metric compares the images based on their entropy, therefore the images need to be big enough to have enough information. It works well for images with different contrasts (for example T2-w with T1-w) but not on segmentations.

    • MeanSquares: The mean squares metric compares the images based on their intensities. It can be used only with images that have exactly the same contrast (with the same intensity range) or with segmentations.

  • iter: Number of iterations. Default=10.

  • shrink: Shrink factor. A shrink factor of 2 will down sample the images by a factor of 2 to do the registration, and thus allow bigger deformations (and be faster to compute). It is usually combined with a smoothing. (only for syn/bsplinesyn). Default=1.

  • smooth: Smooth factor (in mm). Note: if algo={centermassrot,columnwise} the smoothing kernel is: SxSx0. Otherwise it is SxSxS. Default=0.

  • laplacian: Laplace filter using Gaussian second derivatives, applied before registration. The input number correspond to the standard deviation of the Gaussian filter. Default=0.

  • gradStep: The gradient step used by the function opitmizer. A small gradient step can lead to a more accurate registration but will take longer to compute, with the risk to not reach convergence. A bigger gradient step will make the registration faster but the result can be far from an optimum. Default=0.5.

  • deformation: ?x?x?: Restrict deformation (for ANTs algo). Replace ? by 0 (no deformation) or 1 (deformation). Default=1x1x0.

  • init: Initial translation alignment based on:

    • geometric: Geometric center of images

    • centermass: Center of mass of images

    • origin: Physical origin of images

  • poly: Polynomial degree of regularization (only for algo=slicereg). Default=5.

  • filter_size: Filter size for regularization (only for algo=centermassrot). Default=5.

  • smoothWarpXY: Smooth XY warping field (only for algo=columnwize). Default=2.

  • pca_eigenratio_th: Min ratio between the two eigenvalues for PCA-based angular adjustment (only for algo=centermassrot and rot_method=pca). Default=1.6.

  • dof: Degree of freedom for type=label. Separate with _. Default=Tx_Ty_Tz_Rx_Ry_Rz. T stands for translation, R stands for rotation, and S stands for scaling. x, y, and z indicate the direction. Examples:

    • Tx_Ty_Tz_Rx_Ry_Rz would allow translation on x, y and z axes and rotation on x, y and z axes

    • Tx_Ty_Tz_Sz would allow translation on x, y and z axes and scaling only on z axis

  • rot_method {pca, hog, pcahog}: rotation method to be used with algo=centermassrot. If using hog or pcahog, type should be set to imseg. Default=pca

    • pca: approximate cord segmentation by an ellipse and finds it orientation using PCA’s eigenvectors

    • hog: finds the orientation using the symmetry of the image

    • pcahog: tries method pca and if it fails, uses method hog.

-identity

Possible choices: 0, 1

Supplying this option will skip registration optimization (e.g. translations, rotations, deformations) and will only rely on the qform (from the NIfTI header) of the source and destination images. Use this option if you wish to put the source image into the space of the destination image (i.e. match dimension, resolution and orientation).

Default: 0

-z

Size of z-padding to enable deformation at edges when using SyN.

Default: 5

-x

Possible choices: nn, linear, spline

Final interpolation.

Default: “linear”

-ofolder

Output folder. Example: reg_results

-qc

The path where the quality control generated content will be saved. Note: This flag requires the -dseg flag.

-qc-dataset

If provided, this string will be mentioned in the QC report as the dataset the process was run on.

-qc-subject

If provided, this string will be mentioned in the QC report as the subject the process was run on.

-r

Possible choices: 0, 1

Whether to remove temporary files. 0 = no, 1 = yes

Default: 1

-v

Possible choices: 0, 1, 2

Verbosity. 0: Display only errors/warnings, 1: Errors/warnings + info messages, 2: Debug mode

Default: 1