# 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 orientation_affine(ornt, shape) orientation_affine deprecated. 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)

Initialize self. See help(type(self)) for accurate signature.

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

• deprecated from version: 3.2

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

Equivalent to np.flip(arr, axis).

Parameters
arrarray-like
axisint, optional

axis to flip. Default axis == 0

Returns
farrarray

Array with axis axis flipped

## 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.

## orientation_affine¶

nibabel.orientations.orientation_affine(ornt, shape)

• deprecated from version: 3.0

• Will raise <class ‘nibabel.deprecator.ExpiredDeprecationError’> as of version: 4.0

## 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.