`ngff_zarr.rfc4`¶

RFC 4 implementation for anatomical orientation in OME-NGFF.

This module implements RFC 4 which adds anatomical orientation support to OME-NGFF axes, based on the LinkML schema.

Module Contents¶

Classes¶

`AnatomicalOrientationValues`	Anatomical orientation refers to the specific arrangement and directional alignment of anatomical structures within an imaging dataset. It is crucial for ensuring accurate alignment and comparison of images to anatomical atlases, facilitating consistent analysis and interpretation of biological data.
`AnatomicalOrientation`	Anatomical orientation specification for spatial axes.

Functions¶

`orientation_from_name`	Resolve an anatomical orientation preset name to per-axis orientations.
`itk_lps_to_anatomical_orientation`	Convert ITK LPS coordinate system to anatomical orientation.
`itk_direction_to_anatomical_orientation`	Determine the anatomical orientation from a direction cosine vector.
`anatomical_orientation_to_itk_direction`	Convert an anatomical orientation to an ITK direction cosine vector.
`add_anatomical_orientation_to_axis`	Add anatomical orientation to an axis dictionary.
`remove_anatomical_orientation_from_axis`	Remove anatomical orientation from an axis dictionary.

Data¶

`LPS`	LPS (Left-Posterior-Superior) coordinate system orientations. In LPS, the axes increase from:
`RAS`	RAS (Right-Anterior-Superior) coordinate system orientations. In RAS, the axes increase from:
`_ORIENTATION_PRESETS`
`_LPS_ORIENTATION_PAIRS`	LPS orientation pairs: positive and negative orientations for each physical axis in the LPS coordinate system.
`_MAX_SPATIAL_DIMENSIONS`

API¶

class ngff_zarr.rfc4.AnatomicalOrientationValues¶

Bases: str, enum.Enum

Anatomical orientation refers to the specific arrangement and directional alignment of anatomical structures within an imaging dataset. It is crucial for ensuring accurate alignment and comparison of images to anatomical atlases, facilitating consistent analysis and interpretation of biological data.

Initialization

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

left_to_right¶: ‘left-to-right’

right_to_left¶: ‘right-to-left’

anterior_to_posterior¶: ‘anterior-to-posterior’

posterior_to_anterior¶: ‘posterior-to-anterior’

inferior_to_superior¶: ‘inferior-to-superior’

superior_to_inferior¶: ‘superior-to-inferior’

dorsal_to_ventral¶: ‘dorsal-to-ventral’

ventral_to_dorsal¶: ‘ventral-to-dorsal’

dorsal_to_palmar¶: ‘dorsal-to-palmar’

palmar_to_dorsal¶: ‘palmar-to-dorsal’

dorsal_to_plantar¶: ‘dorsal-to-plantar’

plantar_to_dorsal¶: ‘plantar-to-dorsal’

rostral_to_caudal¶: ‘rostral-to-caudal’

caudal_to_rostral¶: ‘caudal-to-rostral’

cranial_to_caudal¶: ‘cranial-to-caudal’

caudal_to_cranial¶: ‘caudal-to-cranial’

proximal_to_distal¶: ‘proximal-to-distal’

distal_to_proximal¶: ‘distal-to-proximal’

superficial_to_deep¶: ‘superficial-to-deep’

deep_to_superficial¶: ‘deep-to-superficial’

apical_to_basal¶: ‘apical-to-basal’

basal_to_apical¶: ‘basal-to-apical’

apex_to_base¶: ‘apex-to-base’

base_to_apex¶: ‘base-to-apex’

class ngff_zarr.rfc4.AnatomicalOrientation¶

Anatomical orientation specification for spatial axes.

value: ngff_zarr.rfc4.AnatomicalOrientationValues¶: None

type: Literal[anatomical]¶: ‘anatomical’

ngff_zarr.rfc4.LPS: dict[str, ngff_zarr.rfc4.AnatomicalOrientation]¶

None

LPS (Left-Posterior-Superior) coordinate system orientations. In LPS, the axes increase from:

X: right-to-left (L = Left)
Y: anterior-to-posterior (P = Posterior)
Z: inferior-to-superior (S = Superior) This is the standard coordinate system used by ITK and many medical imaging applications.

Example usage: ngff_image = NgffImage( data=data, dims=(“z”, “y”, “x”), scale={“x”: 1.0, “y”: 1.0, “z”: 1.0}, translation={“x”: 0.0, “y”: 0.0, “z”: 0.0}, axes_orientations=LPS )

ngff_zarr.rfc4.RAS: dict[str, ngff_zarr.rfc4.AnatomicalOrientation]¶

None

RAS (Right-Anterior-Superior) coordinate system orientations. In RAS, the axes increase from:

X: left-to-right (R = Right)
Y: posterior-to-anterior (A = Anterior)
Z: inferior-to-superior (S = Superior) This coordinate system is commonly used in neuroimaging applications like FreeSurfer and FSL.

ngff_zarr.rfc4._ORIENTATION_PRESETS: dict[str, dict[str, ngff_zarr.rfc4.AnatomicalOrientation]]¶: None

ngff_zarr.rfc4.orientation_from_name( name: str, ) → dict[str, ngff_zarr.rfc4.AnatomicalOrientation]¶

Resolve an anatomical orientation preset name to per-axis orientations.

Parameters

name : str A preset coordinate-system name. Supported values are "LPS" and "RAS" (case-insensitive).

Returns

dict[str, AnatomicalOrientation] A mapping of spatial axis name to :class:AnatomicalOrientation, suitable for NgffImage.axes_orientations or the orientation argument of :func:ngff_zarr.to_multiscales.

Raises

ValueError If name is not a recognized preset.

ngff_zarr.rfc4.itk_lps_to_anatomical_orientation( axis_name: str, ) → ngff_zarr.rfc4.AnatomicalOrientation | None¶

Convert ITK LPS coordinate system to anatomical orientation.

ITK uses the LPS (Left-Posterior-Superior) coordinate system by default. In LPS, the axes increase from:

X: right-to-left (L = Left)
Y: anterior-to-posterior (P = Posterior)
Z: inferior-to-superior (S = Superior)

Parameters

axis_name : str The axis name (‘x’, ‘y’, or ‘z’)

Returns

Optional[AnatomicalOrientation] The corresponding anatomical orientation, or None for non-spatial axes

ngff_zarr.rfc4._LPS_ORIENTATION_PAIRS¶

[(), (), ()]

LPS orientation pairs: positive and negative orientations for each physical axis in the LPS coordinate system.

Each row is (positive_orientation, negative_orientation) where positive means the direction cosine value is >= 0 and negative means it is < 0.

Row 0 (L/R): positive -> RightToLeft, negative -> LeftToRight
Row 1 (A/P): positive -> AnteriorToPosterior, negative -> PosteriorToAnterior
Row 2 (I/S): positive -> InferiorToSuperior, negative -> SuperiorToInferior

ngff_zarr.rfc4._MAX_SPATIAL_DIMENSIONS¶: 3

ngff_zarr.rfc4.itk_direction_to_anatomical_orientation( direction_column: list[float] | tuple[float, ...], ) → ngff_zarr.rfc4.AnatomicalOrientation¶

Determine the anatomical orientation from a direction cosine vector.

The direction vector is a column of the ITK direction matrix. Its dominant component (largest absolute value) determines which physical axis (L/R, A/P, or S/I) this image axis aligns with, and the sign of that component determines the direction.

In LPS physical space:

Component 0: L/R axis (positive = Right->Left, negative = Left->Right)
Component 1: A/P axis (positive = Anterior->Posterior, negative = Posterior->Anterior)
Component 2: I/S axis (positive = Inferior->Superior, negative = Superior->Inferior)

For 2D images, the direction column will have only 2 components, with the third component implicitly zero.

Parameters

direction_column : list[float] | tuple[float, …] Direction cosine vector for the image axis. Can be 2-element (for 2D images) or 3-element (for 3D images). Must have at least 2 elements.

Returns

AnatomicalOrientation The anatomical orientation corresponding to the dominant direction of this axis.

Raises

ValueError If direction_column has fewer than 2 elements.

ngff_zarr.rfc4.anatomical_orientation_to_itk_direction( orientation: ngff_zarr.rfc4.AnatomicalOrientationValues, ) → list[float] | None¶

Convert an anatomical orientation to an ITK direction cosine vector.

This is the reverse of :func:itk_direction_to_anatomical_orientation. Given an anatomical orientation value, it returns the unit direction column vector in ITK LPS physical space.

Only the six LPS-compatible orientations are supported. For any other orientation (e.g. dorsal, palmar, rostral, etc.) the function returns None, signalling that the caller should fall back to an identity direction matrix.

Parameters

orientation : AnatomicalOrientationValues The anatomical orientation value.

Returns

list[float] | None A 3-element unit direction column vector [lps_x, lps_y, lps_z], or None if the orientation is not one of the six LPS-compatible values.

ngff_zarr.rfc4.add_anatomical_orientation_to_axis( axis_dict: dict, orientation: ngff_zarr.rfc4.AnatomicalOrientation, ) → dict¶

Add anatomical orientation to an axis dictionary.

Parameters

axis_dict : dict The axis dictionary to modify orientation : AnatomicalOrientation The anatomical orientation to add

Returns

dict The modified axis dictionary

ngff_zarr.rfc4.remove_anatomical_orientation_from_axis(axis_dict: dict) → dict¶

Remove anatomical orientation from an axis dictionary.

Parameters

axis_dict : dict The axis dictionary to modify

Returns

dict The modified axis dictionary

ngff_zarr.rfc4¶

Module Contents¶

Classes¶

Functions¶

Data¶

API¶

Parameters

Returns

Raises

Parameters

Returns

Parameters

Returns

Raises

Parameters

Returns

Parameters

Returns

Parameters

Returns

`ngff_zarr.rfc4`¶