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\).- scales – A tuple of up to three values specifying the scale factors
for each dimension. If less than length 3, is padded with
-
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
(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
- A sequence of three rotations, in radians. Or, if
angles is False
, a rotation matrix.
- xform – A
-
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 byxform
.If the
origin
parameter is set tocentre
(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 tocorner
, 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 tohigh
, the high voxel bounds are reduced by a small amount (specified by theoffset
parameter) before they are transformed to the world coordinate system. Ifboundary
is set tolow
, the low bounds are increased by a small amount. Theboundary
parameter can also be set to'both'
, orNone
. 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’`, orNone
. - 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.- shape – The
-
fsl.utils.transform.
transform
(p, xform, axes=None, vector=False)¶ Transforms the given set of points
p
according to the given affine transformationxform
.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 inp
. - 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
, orN*2
array asp
, and use this argument to specify which axis/axes that the data inp
correspond to. - vector – Defaults to
False
. IfTrue
, 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 byxform
, as anumpy
array with the same data type as the input.Note
The
axes
argument should only be used if the source coordinate system (the points inp
) axes are orthogonal to the target coordinate system (defined by thexform
).In other words, you can only use the
axes
argument if thexform
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:
- Source voxels -> Source scaled voxels
- Source scaled voxels -> Reference scaled voxels (the FLIRT matrix)
- Reference scaled voxels -> Reference voxels
- Reference voxels -> Reference world (the reference image sform)
Parameters:
-
fsl.utils.transform.
sformToFlirtMatrix
(srcImage, refImage, srcXform=None)¶ Under the assumption that the given
srcImage
andrefImage
share a common world coordinate system (defined by theirNifti.voxToWorldMat
attributes), this function will calculate and return a transformation matrix from thesrcImage
scaled voxel coordinate system to therefImage
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
- srcImage – Source
-
fsl.utils.transform.
rmsdev
(T1, T2, R=None, xc=None)¶ Calculates the RMS deviation of the given affine transforms
T1
andT2
. This can be used as a measure of the ‘distance’ between two affines.The
T1
andT2
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
andT2
.