Registration: using transformations generated from other packages

The mrtransform allows the spatial transformation of images when provided with a suitable linear or nonlinear transformation (“warp”). For linear transformations, MRtrix3 uses homogeneous transformation matrices stored as plain text. These can be converted from FSL and ITK-based (plain text) convention with the command transformconvert. The MRtrix3 tools expect nonlinear transformations in an image format where each voxel defines the scanner space location in the other image.

This transformation format is called a deformation field. When warping an image, these locations are used to sample intensity values in the source image space to fill the image grid in the target space. In contrast, a displacement field stores the displacements (in mm) to the other image from each voxel’s position (in scanner space). A valid MRtrix3 warp is a 4D image containing the deformation field coordinates stored as 3 volumes (x, y, z). For conversion between warp formats see warpconvert.

The following steps describe how you can use mrtransform to apply warps that have been generated from other software packages that provide registration and transformation tools not using the MRtrix3 warp format:

Warping images

The warp’s voxel grid is identical to that of the reference (“target”) image. Each spatial location in the warp specifies the offset relative to the target voxel location in scanner space coordinates from which to pull the image intensity value from the original (“source”) space image. Other software might have different file conventions such as using displacement fields and or different file and coordinate system conventions. However, you can also use mrtransform to apply warps generated from other packages that are in any format using the following steps:

First register an input/source image to a reference image using your registration package of choice. For instance, using antsRegistration on the moving image input.nii with fixed reference image reference.nii:

antsRegistration --verbose 1 --dimensionality 3 --float 0 --output [ants,antsWarped.nii.gz,antsInverseWarped.nii.gz] --interpolation Linear --use-histogram-matching 1 --winsorize-image-intensities [0.005,0.995] --transform Rigid[0.1] --metric CC[reference.nii,input.nii,1,4,Regular,0.1] --convergence [1000x500x250x100,1e-6,10] --shrink-factors 8x4x2x1 --smoothing-sigmas 3x2x1x0vox --transform Affine[0.1] --metric CC[reference.nii,input.nii,1,4,Regular,0.2] --convergence [1000x500x250x100,1e-6,10] --shrink-factors 8x4x2x1 --smoothing-sigmas 3x2x1x0vox --transform SyN[0.1,3,0] --metric CC[reference.nii,input.nii,1,4] --convergence [100x70x50x20,1e-6,10] --shrink-factors 4x2x2x1 --smoothing-sigmas 2x2x1x0vox -x [reference_mask.nii.gz,input_mask.nii.gz]
  1. Generate an identity (deformation field) warp using the image you wish to warp (“source”; or “moving” image):
warpinit input.mif identity_warp[].nii
  1. Transform this identity warp using the registration program that was used to generate the warp.

For example, if you are using the ANTs registration package:

for i in {0..2}; do
    antsApplyTransforms -d 3 -e 0 -i identity_warp${i}.nii -o mrtrix_warp${i}.nii -r reference.nii -t ants1Warp.nii.gz -t ants0GenericAffine.mat --default-value 2147483647
  1. Correct the warp

The resulting 3 3D images mrtrix_warp?.nii hold the voxel-specific corresponding (x, y, z) scanner-space locations. However, locations in the target space to which no known location exists within the moving space need to be handled explicitly. Neglecting this can result in many voxels in the output mrtrix_warp pointing to the location defined by the out of bounds value, such as the origin (0.0, 0.0, 0,0) or other values as in the warp shown below (produced by the deprecated command WarpImageMultiTransform):


Out of bounds locations should ideally be marked by the transformation command with a unique special value that prevents using that part of the warp. MRtrix3 uses the not-a-number value (nan) for this purpose. Either specify nan as the out of bounds value if your registration package supports this or manually convert out of bound markers (here 2147483647) to vectors of nans either with the tool waprcorrect

$ warpcorrect mrtrix_warp[].nii mrtrix_warp_corrected.mif -marker 2147483647

or if that is not possible, manually for instance by transforming an empty source image (using nearest neighbour interpolation) followed by thresholding (mrthreshold) and nan-masking (see mrcalc's -if operator).

  1. Warp the image
mrtransform input.nii -warp mrtrix_warp_corrected.mif warped_input_image.mif

You can check that the conversion went as expected by comparison with ANTs’ output:

mrview input_warped.mif -overlay.load antsWarped.nii.gz -overlay.opacity 0.3

Warping tracks files

To warp a tck file using a warp generated using a different software package, we need to generate an MRtrix3 compatible warp analogously to the above steps. However, warping tracks files differs from warping images due to the type of information stored: in images we pull (interpolate) intensity values sampled on the source grid to new locations on the target grid. Streamlines, on the other hand, consist of a series of vertices (coordinates defined in source space) that need to be pushed to new locations in the target space. The two operations have different spatial lookup spaces (target for images, source for tracks) and (approximately) opposing offset directions. Therefore you will need to apply the inverse transformation to warp tracks files from source to target space compared to that to warp image files.

Compared with the steps described in warping images, you will need to initialise the identity warp with respect to the reference space and amend the command used for warping the identity transform in step 2 to use the inverse warps. Note that the inverse of a series of transformations is their inverses applied in reverse order.

  1. Initialise warp
warpinit reference.mif inv_identity_warp[].nii
  1. Apply the transformation to identity warp
for i in {0..2}; do
    antsApplyTransforms -d 3 -e 0 -i inv_identity_warp${i}.nii -o inv_mrtrix_warp${i}.nii -r input.nii -t [ants0GenericAffine.mat, 1] -t ants1InverseWarp.nii.gz --default-value 2147483647
  1. Fix warp
warpcorrect inv_mrtrix_warp[].nii inv_mrtrix_warp_corrected.mif -marker 2147483647

You can check that the conversion went well by transforming the reference image to the input space:

mrtransform reference.nii -warp inv_mrtrix_warp_corrected.mif reference_warped.mif
mrview reference_warped.mif -overlay.load antsInverseWarped.nii.gz -overlay.opacity 0.3
  1. Transform tracks file
tcktransform input.tck inv_mrtrix_warp_corrected.mif target.tck