NIfTI transform ambiguity

Wiki
1

In the NIfTI & NIfTI-2 (.nii) image format, there is not one, but two items stored in the image header that provide information regarding the localisation of the image within physical space (the image transform):

  • The “ qform ” entry is intended to specify a rigid transformation from voxel coordinates into a spatial location corresponding to the subject’s position within the scanner.
  • The “ sform ” entry is intended to specify an affine transformation from voxel coordinates into a spatial location within the space of some template image.

While the storage of both of these fields within a single image was well-intentioned, the practical reality is that there is no robust way for any software to know which of the two transforms should be used. Furthermore, while software developers will typically ensure that the handling of these fields is internally consistent within their own software, this handling can differ between packages, causing problems for those who utilise multiple software tools.

The handling of this information in MRtrix3 is as follows:

  • When reading NIfTI images:

    • If only one of these transformations is present and valid in the image header (as indicated by the “ sform_code ” and “ qform_code ” flags within the NIfTI image header), then only the valid transformation will be used.

    • If both sform_code and qform_code are set, then MRtrix3 will explicitly compare these two transformations:

      • If they are identical, then MRtrix3 can proceed using either data without ambiguity.

      • If they however differ, then MRtrix3 will issue a warning, and inform the user as to which of the two transforms is being used (more information below).

  • When writing NIfTI images, MRtrix3 will:

    • Write the same transformation to both the qform and sform fields, based on MRtrix3’s internal representation of the header transformation for that particular image.

    • Set both sform_code and qform_code to 1, indicating that they both provide transformations to scanner-based anatomical coordinates.

    This provides the least ambiguity for image data generated by MRtrix3, and ensures maximal compatibility with other software tools (which may only attempt to read from one field or the other).

What if the qform and sform transformations differ on image read?

As stated previously, if a NIfTI file being read by MRtrix3 contains valid data for both of the two transformations, yet the two transformations differ, a decision must be made regarding which of the two transforms will be used. While a command-line warning will always be issued by MRtrix3 whenever this occurs, which of the two transformations is chosen depends on a couple of factors:

Software version

The default transformation selected depends on the particular version of MRtrix3 installed:

  • 3.0_RC2 and prior: sform
  • 3.0_RC3: qform
  • 3.0_RC4 onwards: sform

Historically MRtrix3 had been configured to use the sform transformation by default, as it was more likely to be the transformation most recently updated by prior image processing. With the 3.0_RC3 update, this was changed to the qform transformation, based on the intent of NIfTI whereby the qform represents the spatial localisation of subject-specific data (consistent with the standard used throughout MRtrix3 of operating on positions / directions defined in real space / scanner space) and is additionally constrained to be orthonormal based on the quaternion representation of the transformation, whereas the sform represents an affine transformation to some template space (which is neither constrained to be orthonormal nor corresponds to the subject’s location in space). Unfortunately the disadvantages of this selection were not appreciated in full until after the release of 3.0_RC3; in particular a loss of precision due to floating-point rounding of the quaternion representation, and the fact that some softwares may update the sform matrix in-place yet leave the qform_code flag set and not correspondingly update the qform transformation. As such, from 3.0_RC4 onwards, MRtrix3 will revert to using the sform transformation by default in such cases.

Config file

It is possible to manually control which of the two transformations are read by MRtrix3 in cases of ambiguity, by setting a value for entry NIfTIUseSform in the MRtrix3 configuration file. Note that even in this scenario, MRtrix3 will still provide a command-line warning to alert the user of the potential ambiguity.