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 . |
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 . |
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. |
transformNormal |
Transforms the given point(s), under the assumption that they are normal vectors. |
-
fsl.transform.affine.
concat
(*xforms)[source]¶ Combines the given matrices (returns the dot product).
-
fsl.transform.affine.
veclength
(vec)[source]¶ 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)[source]¶ Normalises the given vector(s) to unit length.
Multiple vectors may be passed in, with a shape of
(n, 3)
.
-
fsl.transform.affine.
scaleOffsetXform
(scales, offsets)[source]¶ 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.transform.affine.
compose
(scales, offsets, rotations, origin=None)[source]¶ 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.transform.affine.
decompose
(xform, angles=True)[source]¶ 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
ifxform
was a(3, 3)
matrix) - A sequence of three rotations, in radians. Or, if
angles is False
, a rotation matrix.
- xform – A
-
fsl.transform.affine.
rotMatToAffine
(rotmat, origin=None)[source]¶ Convenience function which encodes the given
(3, 3)
rotation matrix into a(4, 4)
affine.
-
fsl.transform.affine.
rotMatToAxisAngles
(rotmat)[source]¶ Given a
(3, 3)
rotation matrix, decomposes the rotations into an angle in radians about each axis.
-
fsl.transform.affine.
axisAnglesToRotMat
(xrot, yrot, zrot)[source]¶ 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)[source]¶ 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.transform.affine.
transform
(p, xform, axes=None, vector=False)[source]¶ 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.transform.affine.
transformNormal
(p, xform, axes=None)[source]¶ 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)[source]¶ Used by the
transform()
function. Turns the given array p into aN*3
array ofx,y,z
coordinates. The array p may be a 1D array, or anN*2
orN*3
array.
-
fsl.transform.affine.
rmsdev
(T1, T2, R=None, xc=None)[source]¶ 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
.