Axis realignment at image load

MRtrix3 adopts a single canonical coordinate convention for image data, referred to as RAS: the positive direction of the first image axis is closest to subject Right, the positive direction of the second axis is closest to subject Anterior, and the positive direction of the third axis is closest to subject Superior. Any image whose stored axes do not approximately conform to this convention is silently permuted and / or flipped at load time so that the loaded image appears axial without moving any voxel intensities.

This page describes that mechanism, what it changes, what it does not change, how to inspect the on-disk versus interpreted values, and how to disable it. The realignment itself is performed by Header::realign_transform (cpp/core/header.cpp) when Header::open is called on a non-RAS source.

Why “closest to”?

The language used in the introduction above, where each image axis is described as being “closest to” an anatomical direction, is highly deliberate. When an image is described as being “RAS”, this does not guarantee that the direction in space traversed by first image axis corresponds exactly to anatomical right (similarly for the other two spatial axes). It only means that —assuming the patient orientation was entered correctly at the scanner console— the anatomical axis that the positive direction of the first image axis most closely corresponds to is Right.

This might be expressed symbolically as:

, where i, j and k are used to symbolise the three spatial image axes, as is used in the Brain Imaging Data Structure (BIDS). Indeed, intentionally disambiguating between image axes i, j and k versus anatomical directions L / R / A / P / I S frequently assists in communicating and understanding ideas relating to spatial transformations such as in this page.

What realignment changes

When the on-disk image is not approximately RAS, MRtrix3 modifies the following fields in the in-memory header only. The voxel intensities on disk are never touched.

The 4x4 affine transform matrix is rotated by a permutation of its columns and / or sign-flips, so the leading 3x3 block is as close to the identity matrix as can be achieved through those operations (ie. image axes i, j, k are as close to anatomical R, A, S as can be achieved using axis permutations and flips only).
The image strides are permuted and / or sign-flipped to match the new axis ordering, so iterating axes 0 → 1 → 2 approximately traverses anatomical R → A → S.
Axis-dependent metadata that encode directions or per-slice ordering with respect to the image axes are reoriented to remain valid:
- pe_scheme and the BIDS-style PhaseEncodingDirection field (phase encoding direction is expressed in image-axis space; see Phase encoding scheme handling).
- SliceEncodingDirection and SliceTiming (slice-ordering direction and per-slice timing offsets).
Axis-dependent metadata that arrive after image open via -json_import (or the equivalent JSON sidecar accompanying a NIfTI) are subjected to the same transformation as was applied to the corresponding image, to preserve correspondence between image data and metadata.

What is not realignment

Some other transformations occur at load time and are sometimes confused with realignment, but are independent:

FSL bvec import. The FSL bvecs / bvals convention stores diffusion gradient directions as cosine angles relative to image axes (with a caveat; see Diffusion gradient scheme handling). This contrasts with the MRtrix3 convention (for both storage in header metadata (dw_scheme) / text files / internal computations), where the gradient table contains cosine angles relative to the physical axes of the scanner (so-called real-space or scanner-space coordinates). When a gradient table is read by MRtrix3 via -fslgrad, it is immediately transformed into scanner-space, with the inverse transform applied when writing out FSL bvecs (-export_grad_fsl). This conversion is performed for every image regardless of whether any axis realignment was applied, as it is a fundamental contrast between format conventions. See Diffusion gradient scheme handling for more detail on gradient-table conventions.
NIfTI write-time axis shuffling. When writing to a NIfTI file from a header whose strides are not RAS, MRtrix3 may shuffle the spatial axes on write so that the image intensity data appear in the same order in which they are encoded within the internal representation of the image being written. This is because unlike the MRtrix image formats, the NIfTI format does not support arbitrary axis strides. This is a separate write-side step, though may modify the same set of metadata fields as can be affected by the load-time realignment.

What realignment does not change

The bytes of the image file on disk.
Quantitative voxel values
Diffusion gradient magnitudes
Metadata that are either scalar, or that are not explicitly programmed to possess an encoding related to image axes.
The total number of axes (ndim) or the size of any axis.
The voxel spacing along each (post-permutation) image axis.

Internal convention for the applied shuffle

Internally, the applied shuffle is stored as a triplet of permutation indices and a triplet of boolean flips. The convention is:

The flip is applied first, to the source-axis columns of the original transform (flips[i] is indexed by source axis).
The permutation is then applied as a column rearrangement (permutations[i] is the source axis index placed at output position i).

The user-facing description, produced by mrinfo and exported through -json_all, does not require the reader to know this convention: it enumerates per output axis the source axis it came from and whether the sign was reversed, e.g.:

Axes realignment:
  output axis 0 (~R) <- source axis 2, sign reversed
  output axis 1 (~A) <- source axis 0, sign preserved
  output axis 2 (~S) <- source axis 1, sign reversed

How to see the on-disk values

mrinfo by default prints the interpreted (post-realignment) view of an image. When realignment is non-identity, the default output additionally annotates the affected lines inline:

$ mrinfo dwi_sag.nii.gz
...
Data strides:      [ 1 2 3 4 ]    (on-disk: [ 3 -1 -2 4 ])
Transform:                0.9999       ...
                          ...
  On-disk transform:      0.07944      ...
                          ...
  Axes realignment:
                  output axis 0 (~R) <- source axis 2, sign reversed
                  output axis 1 (~A) <- source axis 0, sign preserved
                  output axis 2 (~S) <- source axis 1, sign reversed
                  (disable with -config RealignTransform false)
...

Two new options on mrinfo give scriptable access:

-realignment prints the per-output-axis enumeration above (and nothing if the image was not realigned).

-ondisk modifies -transform, -strides, -petable, and -property so they report the pre-realignment values, e.g.:

$ mrinfo dwi_sag.nii.gz -property PhaseEncodingDirection
i-
$ mrinfo dwi_sag.nii.gz -property PhaseEncodingDirection -ondisk
j-

For machine consumption, mrinfo -json_all out.json includes a top-level realignment object whenever realignment was non-identity, containing permutations, flips, axis_mapping, transform_on_disk, strides_on_disk and keyval_on_disk (the subset of keyvals whose values differ between interpreted and on-disk).

When to worry

There are three common situations where realignment can mislead an unsuspecting user:

Comparing PhaseEncodingDirection across tools. Running mrinfo image.nii.gz -property PhaseEncodingDirection and reading the same field from a sibling JSON file may produce different strings. The JSON contains the value as it sits on disk; mrinfo reports it relative to the realigned (interpreted) axes.
Piping NIfTI → MRtrix → NIfTI. Realignment information is stored only in the in-memory representation; it is not encoded in the metadata of any image on disk. Once an image has been written to any file format, the next process to read it sees the realigned axes as if they were the on-disk axes. mrinfo executed on a .mif written from a non-axial NIfTI will therefore show no realignment / on-disk annotation: the .mif format faithfully stores the arbitrary strides that resulted from the prior axis realignment, and so the resulting image is already approximately RAS.
Mixing -json_import with non-corresponding images. Using -json_import in conjunction with an image to which realignment was applied by a previous command will fail to reorient the JSON’s axis-dependent fields to conform to the prior realignment of that image. Only pass -json_import when the metadata file is a direct sidecar of the source image. A benefit of utilising the MRtrix image formats throughout a pipeline is that associated metadata embedded in the image header should have any requisite conversions or transformations to accompany an image operation applied automatically. See Phase encoding scheme handling for a worked example.

How to disable

Two scopes:

Disable the realignment entirely. Set RealignTransform: false in your MRtrix3 configuration file, or pass -config RealignTransform false on the command line. The image is then loaded with on-disk axes / strides / transform / metadata unchanged. Beware that downstream MRtrix3 commands then receive data that may not be in the expected canonical orientation; this has consequences for:
- Tools that assume RAS-relative coordinates (for instance the manual -pe_dir argument to dwifslpreproc);
- Commands that receive as input multiple images that must reside on the same image voxel gradient to facilitate per-voxel operations across them, but those images do not all already possess the same strides.
Disable only the on-load notification. Set RealignmentVerbose: false in your configuration file, or pass -config RealignmentVerbose false on the command line. The realignment itself still occurs; only the default-visible console line is suppressed.