What is a warping field?#
Warping fields (also known as deformation fields) are files that represent an image transformation. You can picture warping fields as a set of vector displacements, one for each
[x, y, z] voxel in your image. You can apply a warping field to your image using the
# Apply warping fields to an image file
sct_apply_transfo -i in.nii.gz -d out.nii.gz -w warp1.nii.gz warp2.nii.gz [...]
Warping fields are generated by several SCT tools:
sct_straighten_spinalcord: When straightening a spinal cord image, two warping fields are created for the forward and inverse transformations between the curved anatomical image and the straightened image.
sct_register_to_template: When registering a spinal cord image to a template, two warping fields are created for the forward and inverse transformations between the anatomical image space and the template space.
Warping field conventions#
In the broader ecosystem of MRI software, there are two common conventions for representing warping fields:
5D composite format,
[x, y, z, t, v]:
Originates from Insight Toolkit (ITK), so it’s also referred to as the ITK format.
Used by SCT and Advanced Normalization Tools (ANTs).
Defined in the “Vector-Valued Datasets” section of the NIFTI1 Specification.
4D vector format,
[x, y, z, v]:
Used by the FMRIB Software Library (FSL) and Statistical Parametric Mapping (SPM) software packages.
Defined in the “Deformation model” section of the FSLWiki
For both formats, the
v axis will be of size 3:
xdisplacements for each voxel.
ydisplacements for each voxel.
zdisplacements for each voxel.
Compatibility with non-ITK software (FSL, SPM)#
SCT generates warping fields in the 5D composite ITK format. This format is not compatible with non-ITK software that expects the 4D vector format (such as the FSL command applywarp). So, you will need to convert the warping field using
# ERROR: This FSL command will fail, because the warping field is in ITK format
applywarp -i input_img.nii.gz -w warp_itk.nii.gz -o output_img.nii.gz --abs
# Convert ITK warping field to FSL warping field (we provide input_img.nii.gz as a reference)
sct_image -i warp_itk.nii.gz -to-fsl input_img.nii.gz -o warp_fsl.nii.gz
# Success! The converted warping field can now be applied using FSL
applywarp -i input_img.nii.gz -w warp_fsl.nii.gz -o output_img.nii.gz --abs
--abs flag is specified in calls to
applywarp because the warping fields generated by SCT use absolute coordinates rather than relative displacements.
If the warping field transforms the image into a different voxel space (i.e. if you will be using the
-r option with
applywarp), then you will also need to provide a second reference image for the destination voxel space.
# Convert ITK warping field to FSL warping field (with additional 'ref_img.nii.gz' reference)
sct_image -i warp_itk.nii.gz -to-fsl input_img.nii.gz ref_img.nii.gz -o warp_fsl.nii.gz
# Here is the corresponding FSL `applywarp` command with `-r` specified
applywarp -i input_img.nii.gz -r ref_img.nii.gz -w warp_fsl.nii.gz -o output_img.nii.gz --abs