.. _warping-fields:

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.

.. code::

   # 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 <https://nifti.nimh.nih.gov/pub/dist/src/niftilib/nifti1.h>`_.

* **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 <https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FNIRT/UserGuide#Deformation_model>`_

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 <https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FNIRT/UserGuide#Now_what.3F_--_applywarp.21>`_). So, you will need to convert the warping field using ``sct_image``.



.. code::

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

   .. code::

      # 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