Warping fields#

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 sct_apply_transfo command.

# 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:

  • v=0 contains the x displacements for each voxel.

  • v=1 contains the y displacements for each voxel.

  • v=2 contains the z displacements 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 sct_image.

# 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


The --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