orientations

Utilities for calculating and applying affine orientations

OrientationError

aff2axcodes(aff[, labels, tol])

axis direction codes for affine aff

apply_orientation(arr, ornt)

Apply transformations implied by ornt to the first n axes of the array arr

axcodes2ornt(axcodes[, labels])

Convert axis codes axcodes to an orientation

flip_axis(arr[, axis])

Flip contents of axis in array arr

inv_ornt_aff(ornt, shape)

Affine transform reversing transforms implied in ornt

io_orientation(affine[, tol])

Orientation of input axes in terms of output axes for affine

ornt2axcodes(ornt[, labels])

Convert orientation ornt to labels for axis directions

ornt_transform(start_ornt, end_ornt)

Return the orientation that transforms from start_ornt to end_ornt.

OrientationError

class nibabel.orientations.OrientationError

Bases: Exception

__init__(*args, **kwargs)

aff2axcodes

nibabel.orientations.aff2axcodes(aff, labels=None, tol=None)

axis direction codes for affine aff

Parameters:
aff(N,M) array-like

affine transformation matrix

labelsoptional, None or sequence of (2,) sequences

Labels for negative and positive ends of output axes of aff. See docstring for ornt2axcodes for more detail

tolNone 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')

apply_orientation

nibabel.orientations.apply_orientation(arr, ornt)

Apply transformations implied by ornt to the first n axes of the array arr

Parameters:
arrarray-like of data with ndim >= n
ornt(n,2) orientation array

orientation transform. ornt[N,1]` is flip of axis N of the array implied by `shape`, where 1 means no flip and -1 means flip.  For example, if ``N==0 and ornt[0,1] == -1, and there’s an array arr of shape shape, the flip would correspond to the effect of np.flipud(arr). ornt[:,0] is the transpose that needs to be done to the implied array, as in arr.transpose(ornt[:,0])

Returns:
t_arrndarray

data array arr transformed according to ornt

axcodes2ornt

nibabel.orientations.axcodes2ornt(axcodes, labels=None)

Convert axis codes axcodes to an orientation

Parameters:
axcodes(N,) tuple

axis codes - see ornt2axcodes docstring

labelsoptional, None or sequence of (2,) sequences

(2,) sequences are labels for (beginning, end) of output axis. That is, if the first element in axcodes is front, and the second (2,) sequence in labels is (‘back’, ‘front’) then the first row of ornt will be [1, 1]. If None, equivalent to (('L','R'),('P','A'),('I','S')) - that is - RAS axes.

Returns:
ornt(N,2) array-like

orientation array - see io_orientation docstring

Examples

>>> axcodes2ornt(('F', 'L', 'U'), (('L','R'),('B','F'),('D','U')))
array([[ 1.,  1.],
       [ 0., -1.],
       [ 2.,  1.]])

flip_axis

nibabel.orientations.flip_axis(arr, axis=0)

Flip contents of axis in array arr

flip_axis is deprecated. Please use numpy.flip instead.

  • deprecated from version: 3.2

  • Raises <class ‘nibabel.deprecator.ExpiredDeprecationError’> as of version: 5.0

inv_ornt_aff

nibabel.orientations.inv_ornt_aff(ornt, shape)

Affine transform reversing transforms implied in ornt

Imagine you have an array arr of shape shape, and you apply the transforms implied by ornt (more below), to get tarr. tarr may have a different shape shape_prime. This routine returns the affine that will take a array coordinate for tarr and give you the corresponding array coordinate in arr.

Parameters:
ornt(p, 2) ndarray

orientation transform. ornt[P, 1]` is flip of axis N of the array implied by `shape`, where 1 means no flip and -1 means flip.  For example, if ``P==0 and ornt[0, 1] == -1, and there’s an array arr of shape shape, the flip would correspond to the effect of np.flipud(arr). ornt[:,0] gives us the (reverse of the) transpose that has been done to arr. If there are any NaNs in ornt, we raise an OrientationError (see notes)

shapelength p sequence

shape of array you may transform with ornt

Returns:
transform_affine(p + 1, p + 1) ndarray

An array arr (shape shape) might be transformed according to ornt, resulting in a transformed array tarr. transformed_affine is the transform that takes you from array coordinates in tarr to array coordinates in arr.

Notes

If a row in ornt contains NaN, this means that the input row does not influence the output space, and is thus effectively dropped from the output space. In that case one tarr coordinate maps to many arr coordinates, we can’t invert the transform, and we raise an error

io_orientation

nibabel.orientations.io_orientation(affine, tol=None)

Orientation of input axes in terms of output axes for affine

Valid for an affine transformation from p dimensions to q dimensions (affine.shape == (q + 1, p + 1)).

The calculated orientations can be used to transform associated arrays to best match the output orientations. If p > q, then some of the output axes should be considered dropped in this orientation.

Parameters:
affine(q+1, p+1) ndarray-like

Transformation affine from p inputs to q outputs. Usually this will be a shape (4,4) matrix, transforming 3 inputs to 3 outputs, but the code also handles the more general case

tol{None, float}, optional

threshold below which SVD values of the affine are considered zero. If tol is None, and S is an array with singular values for affine, and eps is the epsilon value for datatype of S, then tol set to S.max() * max((q, p)) * eps

Returns:
orientations(p, 2) ndarray

one row per input axis, where the first value in each row is the closest corresponding output axis. The second value in each row is 1 if the input axis is in the same direction as the corresponding output axis and -1 if it is in the opposite direction. If a row is [np.nan, np.nan], which can happen when p > q, then this row should be considered dropped.

ornt2axcodes

nibabel.orientations.ornt2axcodes(ornt, labels=None)

Convert orientation ornt to labels for axis directions

Parameters:
ornt(N,2) array-like

orientation array - see io_orientation docstring

labelsoptional, 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')

ornt_transform

nibabel.orientations.ornt_transform(start_ornt, end_ornt)

Return the orientation that transforms from start_ornt to end_ornt.

Parameters:
start_ornt(n,2) orientation array

Initial orientation.

end_ornt(n,2) orientation array

Final orientation.

Returns:
orientations(p, 2) ndarray

The orientation that will transform the start_ornt to the end_ornt.