fsl.transform.fnirt

This module contains functions for working with FNIRT non-linear transformations. The following functions are available:

readFnirt	Reads a non-linear FNIRT transformation image, returning a DeformationField or CoefficientField depending on the file type.
toFnirt	Convert a NonLinearTransform to a FNIRT-compatible DeformationField or CoefficientField.
fromFnirt	Convert a FNIRT-style NonLinearTransform to a generic DeformationField.

Non-linear registration using FNIRT

FNIRT is used to calculate a non-linear registration from a source image to a reference image. FNIRT outputs the resulting non-linear transformation as either:

• A deformation/warp field which contains displacements or coordinates.

• A coefficient field which can be used to generate a warp field.

Non-linear registration using FNIRT generally follows the process depicted here:

First, an initial linear registration is performed from the source image to the reference image using FLIRT; this provides an initial global alignment which can be used as the starting point for the non-linear registration. Next, FNIRT is used to non-linearly register the aligned source image to the reference image. Importantly, both of these steps are performed using FSL coordinates.

Note that we have three spaces, and three sets of coordinate systems, to consider:

1. Source image space - the source image, before initial linear registration to the reference image

2. Aligned-source image space - the source image, after it has been linearly transformed to the reference image space

3. Reference image space

The initial affine registration calculates a transformation between spaces 1 and 2, and the non-linear registration calculates a transformation between spaces 2 and 3. Note that the fields-of-view for spaces 2 and 3 are equivalent.

The non-linear transformation file generated by FNIRT will contain the initial linear registration, with it either being encoded directly into the warps (for a warp field), or being stored in the NIfTI header (for a coefficient field).

FNIRT warp fields

A FNIRT deformation field (a.k.a. warp field) is defined in the same space as the reference image, and may contain:

• relative displacements, where each voxel in the warp field contains an offset which can be added to the reference image coordinates for that voxel, in order to calculate the corresponding source image coordinates.

• absolute coordinates, where each voxel in the warp field simply contains the source image coordinates which correspond to those reference image coordinates.

Note

FNIRT deformation field files give no indication as to whether they contain relative displacements or absolute coordinates, so heuristics must be used to infer what is stored in a a particular file. The nonlinear.detectDeformationType() function can be used to determine whether a file contains relative displacements or absolute coordinates.

If an initial linear registration was used as the starting point for FNIRT, this is encoded into the displacements/coordinates themselves, so they can be used to transform from the reference image to the original source image space.

FNIRT coefficient fields

A FNIRT coefficient field contains the coefficients of a set of quadratic or cubic B-spline functions defined on a regular 3D grid overlaid on the reference image voxel coordinate system. Each coefficient in this grid may be referred to as a control point or a knot.

Evaluating the spline functions at a particular location in the grid will result in a relative displacement which can be added to that location’s reference image coordinates, in order to determine the corresponding source image coordinates.

If an initial linear registration was used as the starting point for FNIRT, the generated displacement field will encode a transformation to aligned source image coordinates, and the initial affine will be stored in the NIfTI header of the coefficient field file.

fsl.transform.fnirt._readFnirtDeformationField(fname, img, src, ref, defType=None)

Loads fname, assumed to be a FNIRT deformation field.

Parameters:

• fname – File name of FNIRT deformation field

• img – fname loaded as an Image

• src – Source image

• ref – Reference image

• defType – Deformation type - either 'absolute' or 'relative'. If not provided, is automatically inferred from the data.

Returns:

A DeformationField object

fsl.transform.fnirt._readFnirtCoefficientField(fname, img, src, ref)

Loads fname, assumed to be a FNIRT coefficient field.

Parameters:

• fname – File name of FNIRT coefficient field

• img – fname loaded as an Image

• src – Source image

• ref – Reference image

Returns:

A CoefficientField

fsl.transform.fnirt.readFnirt(fname, src, ref, defType=None, intent=None)

Reads a non-linear FNIRT transformation image, returning a DeformationField or CoefficientField depending on the file type.

Parameters:

• fname – File name of FNIRT transformation

• src – Source image

• ref – Reference image

• defType – Deformation type - either 'absolute' or 'relative'. Only used if the file is a deformation field. If not provided, is automatically inferred from the data.

• intent – NIFTI intent code of fname. e.g. constants.FSL_FNIRT_DISPLACEMENT_FIELD. If not provided, the intent is read from the image header.

fsl.transform.fnirt.toFnirt(field)

Convert a NonLinearTransform to a FNIRT-compatible DeformationField or CoefficientField.

Parameters:

field – NonLinearTransform to convert

Returns:

A FNIRT-compatible DeformationField or CoefficientField.

fsl.transform.fnirt.fromFnirt(field, from_='world', to='world')

Convert a FNIRT-style NonLinearTransform to a generic DeformationField.

Parameters:

• field – A FNIRT-style CoefficientField or DeformationField

• from – Desired reference image coordinate system

• to – Desired source image coordinate system

Returns:

A DeformationField which contains displacements from the reference image from_ cordinate system to the source image to coordinate syste.