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

Note

The --abs flag is specified in calls to applywarp because the warping fields generated by SCT use absolute coordinates rather than relative displacements.

Warning

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