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:
- Source image space - the source image, before initial linear registration to the reference image
- Aligned-source image space - the source image, after it has been linearly transformed to the reference image space
- 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.
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)[source]¶ Loads
fname
, assumed to be a FNIRT deformation field.Parameters: - fname – File name of FNIRT deformation field
- img –
fname
loaded as anImage
- 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)[source]¶ Loads
fname
, assumed to be a FNIRT coefficient field.Parameters: - fname – File name of FNIRT coefficient field
- img –
fname
loaded as anImage
- src – Source image
- ref – Reference image
Returns:
-
fsl.transform.fnirt.
readFnirt
(fname, src, ref, defType=None)[source]¶ Reads a non-linear FNIRT transformation image, returning a
DeformationField
orCoefficientField
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.
-
fsl.transform.fnirt.
toFnirt
(field)[source]¶ Convert a
NonLinearTransform
to a FNIRT-compatibleDeformationField
orCoefficientField
.Parameters: field – NonLinearTransform
to convertReturns: A FNIRT-compatible DeformationField
orCoefficientField
.
-
fsl.transform.fnirt.
fromFnirt
(field, from_='world', to='world')[source]¶ Convert a FNIRT-style
NonLinearTransform
to a genericDeformationField
.Parameters: - field – A FNIRT-style
CoefficientField
orDeformationField
- from – Desired reference image coordinate system
- to – Desired source image coordinate system
Returns: A
DeformationField
which contains displacements from the reference imagefrom_
cordinate system to the source imageto
coordinate syste.- field – A FNIRT-style