NF - orientations to labels routine with tests

Author: matthew-brett

nibabel/__init__.py

@@ -49,10 +49,10 @@
 from .nifti1 import Nifti1Header, Nifti1Image, Nifti1Pair
 from .minc import MincImage
 from .funcs import (squeeze_image, concat_images, four_to_three,
-                           as_closest_canonical)
+                    as_closest_canonical)
 from .orientations import (io_orientation, orientation_affine,
-                                  flip_axis, OrientationError,
-                                  apply_orientation)
+                           flip_axis, OrientationError,
+                           apply_orientation, aff2axcodes)
 from .imageclasses import class_map, ext_map
 from . import trackvis
 

nibabel/orientations.py

@@ -260,3 +260,76 @@ def flip_axis(arr, axis=0):
     return arr.swapaxes(axis, 0)
 
 
+def ornt2axcodes(ornt, labels=None):
+    """ Convert orientation `ornt` to labels for axis directions
+
+    Parameters
+    ----------
+    ornt : (N,2) array-like
+        orientation array - see io_orientation docstring
+    labels : optional, None or sequence of (2,) sequences
+        (2,) sequences are labels for (beginning, end) of output axis.  That is,
+        if the first row in `ornt` is ``[1, 1]``, and the second (2,) sequence
+        in `labels` is ('back', 'front') then the first returned axis code will
+        be ``'front'``.  If the first row in `ornt` had been ``[1, -1]`` then
+        the first returned value would have been ``'back'``.  If None,
+        equivalent to ``(('L','R'),('P','A'),('I','S'))`` - that is - RAS axes.
+
+    Returns
+    -------
+    axcodes : (N,) tuple
+        labels for positive end of voxel axes.  Dropped axes get a label of
+        None.
+
+    Examples
+    --------
+    >>> ornt2axcodes([[1, 1],[0,-1],[2,1]], (('L','R'),('B','F'),('D','U')))
+    ('F', 'L', 'U')
+    """
+    if labels is None:
+        labels = zip('LPI', 'RAS')
+    axcodes = []
+    for axno, direction in np.asarray(ornt):
+        if np.isnan(axno):
+            axcodes.append(None)
+            continue
+        axint = int(np.round(axno))
+        if axint != axno:
+            raise ValueError('Non integer axis number %f' % axno)
+        elif direction == 1:
+            axcode = labels[axint][1]
+        elif direction == -1:
+            axcode = labels[axint][0]
+        else:
+            raise ValueError('Direction should be -1 or 1')
+        axcodes.append(axcode)
+    return tuple(axcodes)
+
+
+def aff2axcodes(aff, labels=None, tol=None):
+    """ axis direction codes for affine `aff`
+
+    Parameters
+    ----------
+    aff : (N,M) array-like
+        affine transformation matrix
+    labels : optional, None or sequence of (2,) sequences
+        Labels for negative and positive ends of output axes of `aff`.  See
+        docstring for ``ornt2axcodes`` for more detail
+    tol : None or float
+        Tolerance for SVD of affine - see ``io_orientation`` for more detail.
+
+    Returns
+    -------
+    axcodes : (N,) tuple
+        labels for positive end of voxel axes.  Dropped axes get a label of
+        None.
+
+    Examples
+    --------
+    >>> aff = [[0,1,0,10],[-1,0,0,20],[0,0,1,30],[0,0,0,1]]
+    >>> aff2axcodes(aff, (('L','R'),('B','F'),('D','U')))
+    ('B', 'R', 'U')
+    """
+    ornt = io_orientation(aff, tol)
+    return ornt2axcodes(ornt, labels)

nibabel/tests/test_orientations.py

@@ -16,7 +16,8 @@
 
 from ..orientations import (io_orientation, orientation_affine,
                             flip_axis, _ornt_to_affine,
-                            apply_orientation, OrientationError)
+                            apply_orientation, OrientationError,
+                            ornt2axcodes, aff2axcodes)
 
 
 IN_ARRS = [np.eye(4),
@@ -165,6 +166,45 @@ def test_io_orientation():
             assert_true(same_transform(taff, ornt, shape))
 
 
+def test_ornt2axcodes():
+    # Recoding orientation to axis codes
+    labels = (('left', 'right'),('back', 'front'), ('down', 'up'))
+    assert_equal(ornt2axcodes([[0,1],
+                               [1,1],
+                               [2,1]], labels), ('right', 'front', 'up'))
+    assert_equal(ornt2axcodes([[0,-1],
+                               [1,-1],
+                               [2,-1]], labels), ('left', 'back', 'down'))
+    assert_equal(ornt2axcodes([[2,-1],
+                               [1,-1],
+                               [0,-1]], labels), ('down', 'back', 'left'))
+    assert_equal(ornt2axcodes([[1,1],
+                               [2,-1],
+                               [0,1]], labels), ('front', 'down', 'right'))
+    # default is RAS output directions
+    assert_equal(ornt2axcodes([[0,1],
+                               [1,1],
+                               [2,1]]), ('R', 'A', 'S'))
+    # dropped axes produce None
+    assert_equal(ornt2axcodes([[0,1],
+                               [np.nan,np.nan],
+                               [2,1]]), ('R', None, 'S'))
+    # Non integer axes raises error
+    assert_raises(ValueError, ornt2axcodes, [[0.1,1]])
+    # As do directions not in range
+    assert_raises(ValueError, ornt2axcodes, [[0,0]])
+
+
+def test_aff2axcodes():
+    labels = (('left', 'right'),('back', 'front'), ('down', 'up'))
+    assert_equal(aff2axcodes(np.eye(4)), tuple('RAS'))
+    aff = [[0,1,0,10],[-1,0,0,20],[0,0,1,30],[0,0,0,1]]
+    assert_equal(aff2axcodes(aff, (('L','R'),('B','F'),('D','U'))),
+                 ('B', 'R', 'U'))
+    assert_equal(aff2axcodes(aff, (('L','R'),('B','F'),('D','U'))),
+                 ('B', 'R', 'U'))
+
+
 def test_drop_coord():
     # given a 5x4 affine from slicing an fmri,
     # the orientations code should easily reorder and drop the t