From dbaa3029b2b6fb7d23a98fa073cec1d979519bb8 Mon Sep 17 00:00:00 2001
From: Paul McCarthy <pauldmccarthy@gmail.com>
Date: Tue, 9 Apr 2019 14:57:11 +0100
Subject: [PATCH] RF/ENH: transforms module is now a package, with affine,
flirt sub-modules
---
fsl/utils/transform/__init__.py | 32 +++++
.../{transform.py => transform/affine.py} | 73 +---------
fsl/utils/transform/flirt.py | 132 ++++++++++++++++++
3 files changed, 169 insertions(+), 68 deletions(-)
create mode 100644 fsl/utils/transform/__init__.py
rename fsl/utils/{transform.py => transform/affine.py} (85%)
create mode 100644 fsl/utils/transform/flirt.py
diff --git a/fsl/utils/transform/__init__.py b/fsl/utils/transform/__init__.py
new file mode 100644
index 000000000..b0ebfbb8e
--- /dev/null
+++ b/fsl/utils/transform/__init__.py
@@ -0,0 +1,32 @@
+#!/usr/bin/env python
+#
+# __init__.py - Functions for working with linear and non-linear FSL
+# transformations.
+#
+# Author: Paul McCarthy <pauldmccarthy@gmail.com>
+#
+"""This module contains functions for working with linear and non-linear FSL
+transformations.
+"""
+
+
+from .affine import ( # noqa
+ invert,
+ concat,
+ veclength,
+ normalise,
+ scaleOffsetXform,
+ compose,
+ decompose,
+ rotMatToAffine,
+ rotMatToAxisAngles,
+ axisAnglesToRotMat,
+ axisBounds,
+ transform,
+ transformNormal,
+ rmsdev)
+from .flirt import ( # noqa
+ fromFlirt,
+ toFlirt,
+ flirtMatrixToSform,
+ sformToFlirtMatrix)
diff --git a/fsl/utils/transform.py b/fsl/utils/transform/affine.py
similarity index 85%
rename from fsl/utils/transform.py
rename to fsl/utils/transform/affine.py
index 8c9be2c44..5e4f272e5 100644
--- a/fsl/utils/transform.py
+++ b/fsl/utils/transform/affine.py
@@ -1,17 +1,16 @@
#!/usr/bin/env python
#
-# transform.py - Functions for working with affine transformation matrices.
+# affine.py - Utility functions for working with affine transformations.
#
# Author: Paul McCarthy <pauldmccarthy@gmail.com>
#
-"""This module provides functions related to 3D image transformations and
-spaces. The following functions are provided:
+"""This module contains utility functions for working with affine
+transformations. The following funcyions are available:
.. autosummary::
:nosignatures:
transform
- transformNormal
scaleOffsetXform
invert
concat
@@ -21,8 +20,6 @@ spaces. The following functions are provided:
rotMatToAxisAngles
axisAnglesToRotMat
axisBounds
- flirtMatrixToSform
- sformToFlirtMatrix
rmsdev
And a few more functions are provided for working with vectors:
@@ -32,8 +29,10 @@ And a few more functions are provided for working with vectors:
veclength
normalise
+ transformNormal
"""
+
import numpy as np
import numpy.linalg as linalg
import collections.abc as abc
@@ -539,68 +538,6 @@ def _fillPoints(p, axes):
return newp
-def 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)
-
- :arg flirtMat: A ``(4, 4)`` transformation matrix
- :arg srcImage: Source :class:`.Image`
- :arg refImage: Reference :class:`.Image`
- """
-
- srcScaledVoxelMat = srcImage.voxToScaledVoxMat
- refInvScaledVoxelMat = refImage.scaledVoxToVoxMat
- refVoxToWorldMat = refImage.voxToWorldMat
-
- return concat(refVoxToWorldMat,
- refInvScaledVoxelMat,
- flirtMat,
- srcScaledVoxelMat)
-
-
-def sformToFlirtMatrix(srcImage, refImage, srcXform=None):
- """Under the assumption that the given ``srcImage`` and ``refImage`` share a
- common world coordinate system (defined by their
- :attr:`.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.
-
- :arg srcImage: Source :class:`.Image`
- :arg refImage: Reference :class:`.Image`
- :arg srcXform: Optionally used in place of the ``srcImage``
- :attr:`.Nifti.voxToWorldMat`
- """
-
- srcScaledVoxToVoxMat = srcImage.scaledVoxToVoxMat
- srcVoxToWorldMat = srcImage.voxToWorldMat
- refWorldToVoxMat = refImage.worldToVoxMat
- refVoxToScaledVoxMat = refImage.voxToScaledVoxMat
-
- if srcXform is not None:
- srcVoxToWorldMat = srcXform
-
- return concat(refVoxToScaledVoxMat,
- refWorldToVoxMat,
- srcVoxToWorldMat,
- srcScaledVoxToVoxMat)
-
-
def 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
diff --git a/fsl/utils/transform/flirt.py b/fsl/utils/transform/flirt.py
new file mode 100644
index 000000000..c669eb9c4
--- /dev/null
+++ b/fsl/utils/transform/flirt.py
@@ -0,0 +1,132 @@
+#!/usr/bin/env python
+#
+# flirt.py - Functions for working with FLIRT matrices.
+#
+# Author: Paul McCarthy <pauldmccarthy@gmail.com>
+#
+"""This module contains functions for working with FLIRT affime transformation
+matrices. The following functions are available:
+
+.. autosummary::
+ :nosignatures:
+
+ fromFlirt
+ toFlirt
+ flirtMatrixToSform
+ sformToFlirtMatrix
+"""
+
+
+from .affine import concat
+
+
+def fromFlirt(xform, src, ref, from_='voxel', to='world'):
+ """Convert a FLIRT affine matrix into another affine.
+
+ Given a FLIRT matrix, and the source and reference images with which the
+ FLIRT matrix is associated, converts the matrix into an affine matrix
+ which can transform coordinates from the source image ``from_`` coordinate
+ system to the reference image ``to`` coordinate system.
+
+ The ``from_`` and ``to`` arguments specify the desired spaces that the
+ returned affine should transform between. The default values
+ (``from_='voxel'`` and ``to='world'`` will generate an affine which
+ transforms from voxels in the source image to world-coordinates in the
+ reference image.
+
+ Valid values for the ``from_`` and ``to`` arguments are:
+
+ - ``voxel``: The voxel coordinate system
+ - ``fsl``: The FSL coordiante system (voxels scaled by pixdims, with
+ the X axis inverted if the image sform/qform has a positive
+ determinant)
+ - ``world`` The world coordinate system
+
+ See the :class:`.Nifti` class documentation and the
+ :meth:`.Nifti.getAffine` method for more details.
+
+ :arg xform: ``numpy`` array of shape ``(4, 4)`` containing a FLIRT
+ transformation matrix.
+ :arg src: :class:`.Nifti` object, the ``xform`` source image
+ :arg ref: :class:`.Nifti` object, the ``xform`` reference image
+ :arg from_: Desired source coordinate system
+ :arg to: Desired target coordinate system
+ :returns: ``numpy`` array of shape ``(4, 4)`` containing a matrix
+ encoding a transformation from the source ``from_`` to
+ the reference ``to`` coordinate systems.
+ """
+ premat = src.getAffine(from_, 'fsl')
+ postmat = ref.getAffine('fsl', to)
+ return concat(postmat, xform, premat)
+
+
+def toFlirt(xform, src, ref, from_='voxel', to='world'):
+ """Convert an affine affine matrix into a FLIRT matrix.
+
+ :returns: ``numpy`` array of shape ``(4, 4)`` containing a matrix
+ encoding a transformation from the source ``from_`` to
+ the reference ``to`` coordinate systems.
+ :arg src: :class:`.Nifti` object, the ``xform`` source image
+ :arg ref: :class:`.Nifti` object, the ``xform`` reference image
+ :arg from_: ``xform`` source coordinate system
+ :arg to: ``xform`` target coordinate system
+ :returns: A ``numpy`` array of shape ``(4, 4)`` containing a FLIRT
+ transformation matrix from ``src`` to ``ref``.
+ """
+ premat = src.getAffine('fsl', from_)
+ postmat = ref.getAffine(to, 'fsl')
+ return concat(postmat, xform, premat)
+
+
+def 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)
+
+ :arg flirtMat: A ``(4, 4)`` transformation matrix
+ :arg srcImage: Source :class:`.Image`
+ :arg refImage: Reference :class:`.Image`
+ """
+ return fromFlirt(flirtMat, srcImage, refImage, 'voxel', 'world')
+
+
+def sformToFlirtMatrix(srcImage, refImage, srcXform=None):
+ """Under the assumption that the given ``srcImage`` and ``refImage`` share a
+ common world coordinate system (defined by their
+ :attr:`.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.
+
+ :arg srcImage: Source :class:`.Image`
+ :arg refImage: Reference :class:`.Image`
+ :arg srcXform: Optionally used in place of the ``srcImage``
+ :attr:`.Nifti.voxToWorldMat`
+ """
+
+ srcScaledVoxToVoxMat = srcImage.scaledVoxToVoxMat
+ srcVoxToWorldMat = srcImage.voxToWorldMat
+ refWorldToVoxMat = refImage.worldToVoxMat
+ refVoxToScaledVoxMat = refImage.voxToScaledVoxMat
+
+ if srcXform is not None:
+ srcVoxToWorldMat = srcXform
+
+ return concat(refVoxToScaledVoxMat,
+ refWorldToVoxMat,
+ srcVoxToWorldMat,
+ srcScaledVoxToVoxMat)
--
GitLab