fsl.transform.affine

This module contains utility functions for working with affine transformations. The following functions are available:

transform	Transforms the given set of points p according to the given affine transformation xform.
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.
flip	Applies a flip/inversion to an affine transform along specified axes.
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.
mergeBounds	Merge multiple (lo, hi) bounds together.
rmsdev	Calculates the RMS deviation of the given affine transforms T1 and T2.
rescale	Calculates an affine matrix to use for resampling.

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.
transformNormal	Transforms the given point(s), under the assumption that they are normal vectors.

fsl.transform.affine.invert(x)

Inverts the given matrix using numpy.linalg.inv.

fsl.transform.affine.concat(*xforms)

Combines the given matrices (returns the dot product).

fsl.transform.affine.veclength(vec)

Returns the length of the given vector(s).

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

fsl.transform.affine.normalise(vec)

Normalises the given vector(s) to unit length.

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

fsl.transform.affine.flip(shape, xform, *axes)

Applies a flip/inversion to an affine transform along specified axes.

Parameters:

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

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

• axes – Indices of axes to flip

fsl.transform.affine.scaleOffsetXform(scales=None, offsets=None)

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.transform.affine.compose(scales, offsets, rotations, origin=None, shears=None, scaleAtOrigin=False)

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. If not provided, the rotation origin is (0, 0, 0).

• shears – Sequence of three shear values

• scaleAtOrigin – If True, the scaling parameters are applied with respect to the origin, i.e. so that the location of origin is unchanged after scaling. If False (the default), the scaling parameters are applied with respect to location (0, 0, 0).

fsl.transform.affine.decompose(xform, angles=True, shears=False)

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.

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.

• shears – Defaults to False. If True, shears are 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.

• If shears is True, a sequence of three shears.

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

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

fsl.transform.affine.rotMatToAxisAngles(rotmat)

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

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

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

fsl.transform.affine.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.transform.affine.mergeBounds(*bounds)

Merge multiple (lo, hi) bounds together. Returns the union of all bounds, i.e. a new set of bounds which encompasses all given bounds.

Each set of bounds can be provided in one of the following formats:

• ((lo, lo, lo), (hi, hi, hi))

• ((lo, hi), (lo, hi), (lo, hi))

The return value will be a tuple of tuples, otherwise having the same format as the inputs.

fsl.transform.affine.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.transform.affine.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.transform.affine._fillPoints(p, axes)

Used by the transform() function. Turns the given array p into a N*3 array of x,y,z coordinates. The array p may be a 1D array, or an N*2 or N*3 array.

fsl.transform.affine.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.

fsl.transform.affine.rescale(oldShape, newShape, origin=None)

Calculates an affine matrix to use for resampling.

This function generates an affine transformation matrix that can be used to resample an N-D array from oldShape to newShape using, for example, scipy.ndimage.affine_transform.

The matrix will contain scaling factors derived from the oldShape / newShape ratio, and an offset determined by the origin.

The default value for origin ('centre') causes the corner voxel of the output to have the same centre as the corner voxel of the input. If the origin is 'corner', we apply an offset which effectively causes the voxel grid corners of the input and output to be aligned.

Parameters:

• oldShape – Shape of input data

• newShape – Shape to resample data to

• origin – Voxel grid alignment - either 'centre' (the default) or 'corner'

Returns:

An affine resampling matrix