sct_register_to_template¶
Register an anatomical image to the spinal cord MRI template (default: PAM50).
The registration process includes three main registration steps:
straightening of the image using the spinal cord segmentation (see sct_straighten_spinalcord for details);
vertebral alignment between the image and the template, using labels along the spine;
iterative slice-wise non-linear registration (see sct_register_multimodal for details)
To register a subject to the template, try the default command:
sct_register_to_template -i data.nii.gz -s data_seg.nii.gz -l data_labels.nii.gz
If this default command does not produce satisfactory results, the -param
argument should be tweaked according to the tips given here: https://spinalcordtoolbox.com/en/latest/user_section/command-line.html#sct-register-multimodal
The default registration method brings the subject image to the template, which can be problematic with highly non-isotropic images as it would induce large interpolation errors during the straightening procedure. Although the default method is recommended, you may want to register the template to the subject (instead of the subject to the template) by skipping the straightening procedure. To do so, use the parameter -ref subject
. Example below:
sct_register_to_template -i data.nii.gz -s data_seg.nii.gz -l data_labels.nii.gz -ref subject -param step=1,type=seg,algo=centermassrot,smooth=0:step=2,type=seg,algo=columnwise,smooth=0,smoothWarpXY=2
Vertebral alignment (step 2) consists in aligning the vertebrae between the subject and the template.
Two types of labels are possible:
Vertebrae mid-body labels, created at the center of the spinal cord using the parameter
-l
;Posterior edge of the intervertebral discs, using the parameter
-ldisc
.
If only one label is provided, a simple translation will be applied between the subject label and the template label. No scaling will be performed.
If two labels are provided, a linear transformation (translation + rotation + superior-inferior linear scaling) will be applied. The strategy here is to define labels that cover the region of interest. For example, if you are interested in studying C2 to C6 levels, then provide one label at C2 and another at C6. However, note that if the two labels are very far apart (e.g. C2 and T12), there might be a mis-alignment of discs because a subject’s intervertebral discs distance might differ from that of the template.
If more than two labels are used, a non-linear registration will be applied to align the each intervertebral disc between the subject and the template, as described in sct_straighten_spinalcord. This the most accurate method, however it has some serious caveats:
This feature is not compatible with the parameter
-ref subject
, where only a rigid registration is performed.Due to the non-linear registration in the S-I direction, the warping field will be cropped above the top label and below the bottom label. Applying this warping field will result in a strange-looking registered image that has the same value above the top label and below the bottom label. But if you are not interested in these regions, you do not need to worry about it.
We recommend starting with 2 labels, then trying the other options on a case-by-case basis depending on your data.
More information about label creation can be found at https://spinalcordtoolbox.com/user_section/tutorials/vertebral-labeling.html
usage: sct_register_to_template -i <file> -s <file> [-h] [-s-template-id <int>]
[-l <file>] [-ldisc <file>] [-lspinal <file>]
[-ofolder <folder>] [-t <folder>]
[-c {t1,t2,t2s}] [-ref {template,subject}]
[-param <list>]
[-centerline-algo {polyfit,bspline,linear,nurbs}]
[-centerline-smooth <int>] [-qc <folder>]
[-qc-dataset <str>] [-qc-subject <str>]
[-r <int>] [-v <int>]
MANDATORY ARGUMENTS¶
- -i
Input anatomical image. Example:
anat.nii.gz
- -s
Spinal cord segmentation. Example:
anat_seg.nii.gz
OPTIONAL ARGUMENTS¶
- -s-template-id
Segmentation file ID to use for registration. The ID is an integer indicated in the file ‘template/info_label.txt’. This ‘info_label.txt’ file corresponds to the template indicated by the flag
-t
. By default, the spinal cord segmentation is used (ID=3), but if available, a different segmentation such as white matter segmentation could produce better registration results.Default: 3
- -l
One or two labels (preferred) located at the center of the spinal cord, on the mid-vertebral slice. Example:
anat_labels.nii.gz
For more information about label creation, please see: https://spinalcordtoolbox.com/user_section/tutorials/vertebral-labeling.html
- -ldisc
File containing disc labels. Labels can be located either at the posterior edge of the intervertebral discs, or at the orthogonal projection of each disc onto the spinal cord (e.g.: the file
xxx_seg_labeled_discs.nii.gz
output by sct_label_vertebrae)If you are using more than 2 labels, all discs covering the region of interest should be provided. E.g., if you are interested in levels C2 to C7, then you should provide disc labels 2,3,4,5,6,7. For more information about label creation, please refer to https://spinalcordtoolbox.com/user_section/tutorials/vertebral-labeling.html
- -lspinal
Labels located in the center of the spinal cord, at the superior-inferior level corresponding to the mid-point of the spinal level. Example:
anat_labels.nii.gz
Each label is a single voxel, which value corresponds to the spinal level (e.g.: 2 for spinal level 2). If you are using more than 2 labels, all spinal levels covering the region of interest should be provided (e.g., if you are interested in levels C2 to C7, then you should provide spinal level labels 2,3,4,5,6,7).”
- -ofolder
Output folder.
- -t
Path to template
Default: “/home/docs/checkouts/readthedocs.org/user_builds/spinalcordtoolbox/checkouts/stable/data/PAM50”
- -c
Possible choices: t1, t2, t2s
Contrast to use for registration.
Default: “t2”
- -ref
Possible choices: template, subject
Reference for registration: template: subject->template, subject: template->subject.
Default: “template”
- -param
Parameters for registration (see sct_register_multimodal). Default: step=0
type=label
dof=Tx_Ty_Tz_Rx_Ry_Rz_Sz
step=1
type=imseg
algo=centermassrot
metric=MeanSquares
iter=10
smooth=0
gradStep=0.5
slicewise=0
smoothWarpXY=2
pca_eigenratio_th=1.6
step=2
type=seg
algo=bsplinesyn
metric=MeanSquares
iter=3
smooth=1
gradStep=0.5
slicewise=0
smoothWarpXY=2
pca_eigenratio_th=1.6
- -centerline-algo
Possible choices: polyfit, bspline, linear, nurbs
Algorithm for centerline fitting (when straightening the spinal cord).
Default: “bspline”
- -centerline-smooth
Degree of smoothing for centerline fitting. Only use with -centerline-algo {bspline, linear}.
Default: 20
- -qc
The path where the quality control generated content will be saved.
- -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