linumpy.imaging.orientation#

Utilities for handling 3D volume orientation codes and transformations.

Orientation convention used throughout:

numpy dim 0 → SITK Z → Allen S (Superior)
numpy dim 1 → SITK X → Allen R (Right)
numpy dim 2 → SITK Y → Allen A (Anterior)

The RAS target orientation maps:

output dim 0 ←→ Superior (S)
output dim 1 ←→ Right (R)
output dim 2 ←→ Anterior (A)

Functions#

`parse_orientation_code`(orientation)	Parse an orientation code and return axis permutation and flips for RAS alignment.
`apply_orientation_transform`(volume, permutation[, flips])	Reorient a 3D volume by applying an axis permutation followed by axis flips.
`reorder_resolution`(resolution, permutation)	Reorder a per-axis resolution tuple to match the axis permutation.

Module Contents#

linumpy.imaging.orientation.parse_orientation_code(orientation)[source]#

Parse an orientation code and return axis permutation and flips for RAS alignment.

Parameters:

orientation (str) – 3-letter code (R/L, A/P, S/I) describing what each source axis points to. Example: ‘AIR’ means dim0→Anterior, dim1→Inferior, dim2→Right.

Returns:

axis_permutation (tuple of int) – Source indices for each target dimension, such that np.transpose(volume, axis_permutation) produces a volume whose axes are ordered (S, R, A) – matching the numpy_to_sitk_image convention where:
- numpy dim 0 → SITK Z → Allen S (Superior)
- numpy dim 1 → SITK X → Allen R (Right)
- numpy dim 2 → SITK Y → Allen A (Anterior)
axis_flips (tuple of int) – Sign for each axis after permutation: -1 means flip that axis, +1 means keep.

Raises:

ValueError – If the orientation code is not exactly 3 letters, contains invalid letters, or has duplicate axis directions.

Return type:

tuple[tuple[int, Ellipsis], tuple[int, Ellipsis]]

Examples

>>> parse_orientation_code('SRA')  # source already in (S, R, A) order -- identity
((0, 1, 2), (1, 1, 1))
>>> parse_orientation_code('PIR')  # common OCT orientation
((1, 2, 0), (-1, 1, -1))

linumpy.imaging.orientation.apply_orientation_transform(volume, permutation, flips=None)[source]#

Reorient a 3D volume by applying an axis permutation followed by axis flips.

Parameters:

volume (np.ndarray) – Input 3-D volume (any shape).
permutation (tuple of int) – Axis permutation as returned by parse_orientation_code(). np.transpose(volume, permutation) is applied first.
flips (tuple of int) – Sign for each axis after permutation. A value of -1 means that axis is flipped (np.flip); +1 means the axis is kept as-is.

Returns:

Reoriented volume. The returned array may share memory with volume for the non-contiguous transpose, but np.flip produces a view, so callers should copy if in-place modification is needed.

Return type:

np.ndarray

linumpy.imaging.orientation.reorder_resolution(resolution, permutation)[source]#

Reorder a per-axis resolution tuple to match the axis permutation.

Parameters:

resolution (tuple of float) – Per-axis resolution values, one per spatial dimension.
permutation (tuple of int) – Axis permutation as returned by parse_orientation_code().

Returns:

Resolution values reordered so that reordered[i] == resolution[permutation[i]], i.e. the resolution now corresponds to the target axis ordering.

Return type:

tuple of float