fsl.utils.transform

This module provides functions related to 3D image transformations and spaces. The following functions are provided:

transform

Transforms the given set of points p according to the given affine transformation xform.

transformNormal

Transforms the given point(s), under the assumption that they are normal vectors.

scaleOffsetXform

Creates and returns an affine transformation matrix which encodes the specified scale(s) and offset(s).

invert

Inverts the given matrix using numpy.linalg.inv.

concat

Combines the given matrices (returns the dot product).

compose

Compose a transformation matrix out of the given scales, offsets and axis rotations.

decompose

Decomposes the given transformation matrix into separate offsets, scales, and rotations, according to the algorithm described in:

rotMatToAffine

Convenience function which encodes the given (3, 3) rotation matrix into a (4, 4) affine.

rotMatToAxisAngles

Given a (3, 3) rotation matrix, decomposes the rotations into an angle in radians about each axis.

axisAnglesToRotMat

Constructs a (3, 3) rotation matrix from the given angles, which must be specified in radians.

axisBounds

Returns the (lo, hi) bounds of the specified axis/axes in the world coordinate system defined by xform.

flirtMatrixToSform

Converts the given FLIRT transformation matrix into a transformation from the source image voxel coordinate system to the reference image world coordinate system.

sformToFlirtMatrix

Under the assumption that the given srcImage and refImage share a common world coordinate system (defined by their Nifti.voxToWorldMat attributes), this function will calculate and return a transformation matrix from the srcImage scaled voxel coordinate system to the refImage scaled voxel coordinate system, that can be saved to disk and used with FLIRT, to resample the source image to the reference image.

rmsdev

Calculates the RMS deviation of the given affine transforms T1 and T2.

And a few more functions are provided for working with vectors:

veclength

Returns the length of the given vector(s).

normalise

Normalises the given vector(s) to unit length.

fsl.utils.transform.invert(x)

Inverts the given matrix using numpy.linalg.inv.

fsl.utils.transform.concat(*xforms)

Combines the given matrices (returns the dot product).

fsl.utils.transform.veclength(vec)

Returns the length of the given vector(s).

Multiple vectors may be passed in, with a shape of (n, 3).

fsl.utils.transform.normalise(vec)

Normalises the given vector(s) to unit length.

Multiple vectors may be passed in, with a shape of (n, 3).

fsl.utils.transform.scaleOffsetXform(scales, offsets)

Creates and returns an affine transformation matrix which encodes the specified scale(s) and offset(s).

Parameters
  • scales – A tuple of up to three values specifying the scale factors for each dimension. If less than length 3, is padded with 1.0.

  • offsets – A tuple of up to three values specifying the offsets for each dimension. If less than length 3, is padded with 0.0.

Returns

A numpy.float32 array of size \(4 \times 4\).

fsl.utils.transform.compose(scales, offsets, rotations, origin=None)

Compose a transformation matrix out of the given scales, offsets and axis rotations.

Parameters
  • scales – Sequence of three scale values.

  • offsets – Sequence of three offset values.

  • rotations – Sequence of three rotation values, in radians, or a rotation matrix of shape (3, 3).

  • origin – Origin of rotation - must be scaled by the scales. If not provided, the rotation origin is (0, 0, 0).

fsl.utils.transform.decompose(xform, angles=True)

Decomposes the given transformation matrix into separate offsets, scales, and rotations, according to the algorithm described in:

Spencer W. Thomas, Decomposing a matrix into simple transformations, pp 320-323 in Graphics Gems II, James Arvo (editor), Academic Press, 1991, ISBN: 0120644819.

It is assumed that the given transform has no perspective components. Any shears in the affine are discarded.

Parameters
  • xform – A (3, 3) or (4, 4) affine transformation matrix.

  • angles – If True (the default), the rotations are returned as axis-angles, in radians. Otherwise, the rotation matrix is returned.

Returns

The following:

  • A sequence of three scales

  • A sequence of three translations (all 0 if xform was a (3, 3) matrix)

  • A sequence of three rotations, in radians. Or, if angles is False, a rotation matrix.

fsl.utils.transform.rotMatToAffine(rotmat, origin=None)

Convenience function which encodes the given (3, 3) rotation matrix into a (4, 4) affine.

fsl.utils.transform.rotMatToAxisAngles(rotmat)

Given a (3, 3) rotation matrix, decomposes the rotations into an angle in radians about each axis.

fsl.utils.transform.axisAnglesToRotMat(xrot, yrot, zrot)

Constructs a (3, 3) rotation matrix from the given angles, which must be specified in radians.

fsl.utils.transform.axisBounds(shape, xform, axes=None, origin='centre', boundary='high', offset=0.0001)

Returns the (lo, hi) bounds of the specified axis/axes in the world coordinate system defined by xform.

If the origin parameter is set to centre (the default), this function assumes that voxel indices correspond to the voxel centre. For example, the voxel at (4, 5, 6) covers the space:

[3.5 - 4.5, 4.5 - 5.5, 5.5 - 6.5]

So the bounds of the specified shape extends from the corner at

(-0.5, -0.5, -0.5)

to the corner at

(shape[0] - 0.5, shape[1] - 0.5, shape[1] - 0.5)

If the origin parameter is set to corner, this function assumes that voxel indices correspond to the voxel corner. In this case, a voxel at (4, 5, 6) covers the space:

[4 - 5, 5 - 6, 6 - 7]

So the bounds of the specified shape extends from the corner at

(0, 0, 0)

to the corner at

(shape[0], shape[1], shape[1]).

If the boundary parameter is set to high, the high voxel bounds are reduced by a small amount (specified by the offset parameter) before they are transformed to the world coordinate system. If boundary is set to low, the low bounds are increased by a small amount. The boundary parameter can also be set to 'both', or None. This option is provided so that you can ensure that the resulting bounds will always be contained within the image space.

Parameters
  • shape – The (x, y, z) shape of the data.

  • xform – Transformation matrix which transforms voxel coordinates to the world coordinate system.

  • axes – The world coordinate system axis bounds to calculate.

  • origin – Either 'centre' (the default) or 'corner'.

  • boundary – Either 'high' (the default), 'low', ‘’both’`, or None.

  • offset – Amount by which the boundary voxel coordinates should be offset. Defaults to 1e-4.

Returns

A tuple containing the (low, high) bounds for each requested world coordinate system axis.

fsl.utils.transform.transform(p, xform, axes=None, vector=False)

Transforms the given set of points p according to the given affine transformation xform.

Parameters
  • p – A sequence or array of points of shape \(N \times 3\).

  • xform – A (4, 4) affine transformation matrix with which to transform the points in p.

  • axes – If you are only interested in one or two axes, and the source axes are orthogonal to the target axes (see the note below), you may pass in a 1D, N*1, or N*2 array as p, and use this argument to specify which axis/axes that the data in p correspond to.

  • vector – Defaults to False. If True, the points are treated as vectors - the translation component of the transformation is not applied. If you set this flag, you pass in a (3, 3) transformation matrix.

Returns

The points in p, transformed by xform, as a numpy array with the same data type as the input.

Note

The axes argument should only be used if the source coordinate system (the points in p) axes are orthogonal to the target coordinate system (defined by the xform).

In other words, you can only use the axes argument if the xform matrix consists solely of translations and scalings.

fsl.utils.transform.transformNormal(p, xform, axes=None)

Transforms the given point(s), under the assumption that they are normal vectors. In this case, the points are transformed by invert(xform[:3, :3]).T.

fsl.utils.transform.flirtMatrixToSform(flirtMat, srcImage, refImage)

Converts the given FLIRT transformation matrix into a transformation from the source image voxel coordinate system to the reference image world coordinate system.

FLIRT transformation matrices transform from the source image scaled voxel coordinate system into the reference image scaled voxel coordinate system (voxels scaled by pixdims, with a left-right flip if the image sform has a positive determinant).

So to construct a transformation from source image voxel coordinates into reference image world coordinates, we need to combine the following:

  1. Source voxels -> Source scaled voxels

  2. Source scaled voxels -> Reference scaled voxels (the FLIRT matrix)

  3. Reference scaled voxels -> Reference voxels

  4. Reference voxels -> Reference world (the reference image sform)

Parameters
  • flirtMat – A (4, 4) transformation matrix

  • srcImage – Source Image

  • refImage – Reference Image

fsl.utils.transform.sformToFlirtMatrix(srcImage, refImage, srcXform=None)

Under the assumption that the given srcImage and refImage share a common world coordinate system (defined by their Nifti.voxToWorldMat attributes), this function will calculate and return a transformation matrix from the srcImage scaled voxel coordinate system to the refImage scaled voxel coordinate system, that can be saved to disk and used with FLIRT, to resample the source image to the reference image.

Parameters
  • srcImage – Source Image

  • refImage – Reference Image

  • srcXform – Optionally used in place of the srcImage Nifti.voxToWorldMat

fsl.utils.transform.rmsdev(T1, T2, R=None, xc=None)

Calculates the RMS deviation of the given affine transforms T1 and T2. This can be used as a measure of the ‘distance’ between two affines.

The T1 and T2 arguments may be either full (4, 4) affines, or (3, 3) rotation matrices.

See FMRIB technical report TR99MJ1, available at:

https://www.fmrib.ox.ac.uk/datasets/techrep/

Parameters
  • T1 – First affine

  • T2 – Second affine

  • R – Sphere radius

  • xc – Sphere centre

Returns

The RMS deviation between T1 and T2.