# NiBabel

### Access a cacophony of neuro-imaging file formats

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

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

## apply_orientation

nibabel.orientations.apply_orientation(arr, ornt)

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

  Parameters:
    arr array-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_arr ndarray

      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

    labels optional, 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)

    shape length 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

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

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