RF/ENH: transforms module is now a package, with affine, flirt sub-modules

fsl/utils/transform/__init__.py

+#!/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)

fsl/utils/transform.py → fsl/utils/transform/affine.py

 #!/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

fsl/utils/transform/flirt.py

+#!/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)