Geometry

Note

This page is a reference documentation. It only explains the class signature, and not how to use it. Please refer to the Habitat Guide and Python API guide (v2.0) for usage.

class Geometry(shape: Tuple[int, ...], spacing: Tuple[float, ...], origin: Tuple[float, ...], direction: Tuple[float, ...], frame_of_reference: str | None = None)[source]

Bases: object

Spatial definition shared by every volumetric object of one subject.

Two volumetric objects may only be combined when their geometries are compatible. Making geometry an explicit, comparable value is what lets HABIT accept images produced by other tools (nnU-Net, MONAI, 3D Slicer) without a directory convention acting as the implicit contract.

Axis-order convention follows the existing public habit.image contract: shape is the NumPy array shape in (z, y, x) order, while spacing, origin and direction keep the SimpleITK physical-space axis order (x, y, z) so that round-tripping through SimpleITK.Image never transposes metadata.

shape

Voxel grid size as the NumPy array shape (z, y, x).

Type:

Tuple[int, …]

spacing

Physical voxel size in mm, SimpleITK axis order (x, y, z).

Type:

Tuple[float, …]

origin

Physical coordinate of voxel (0, 0, 0), SimpleITK order.

Type:

Tuple[float, …]

direction

Row-major direction cosine matrix, flattened (9 values for 3D volumes).

Type:

Tuple[float, …]

frame_of_reference

Optional identifier tying several series to the same physical space, used to detect silently mismatched registrations.

Type:

str | None

is_compatible_with(other: Geometry, *, tolerance: float = 1e-05, direction_tolerance: float = 0.0001) → bool[source]

Report whether two geometries describe the same voxel grid.

Spacing and origin use tolerance (default 1e-5 absolute). Direction cosines use the looser direction_tolerance (default 1e-4 absolute): DICOM / ITK round-trips routinely differ by ~1e-5 in individual cosine entries without any meaningful grid misalignment, while a true axis swap or oblique mismatch remains far above 1e-4.

Parameters:

  • other – Geometry to compare against.

  • tolerance – Absolute tolerance for spacing and origin.

  • direction_tolerance – Absolute tolerance for the flattened direction cosine matrix. Kept separate from tolerance so spacing/origin stay strict while DICOM noise in direction is tolerated.

Returns:

True when the grids coincide within the stated tolerances.

classmethod from_array(shape: Tuple[int, ...], *, spacing: Tuple[float, ...] | None = None, origin: Tuple[float, ...] | None = None, direction: Tuple[float, ...] | None = None, frame_of_reference: str | None = None) → Geometry[source]

Build a geometry from an array shape with identity defaults.

Parameters:

  • shape – Voxel grid size as the NumPy array shape (z, y, x).

  • spacing – Physical voxel size; defaults to 1 mm isotropic.

  • origin – Physical origin; defaults to the zero vector.

  • direction – Flattened direction cosine matrix; defaults to identity.

  • frame_of_reference – Optional shared-space identifier.

Returns:

A geometry describing the grid.

__init__(shape: Tuple[int, ...], spacing: Tuple[float, ...], origin: Tuple[float, ...], direction: Tuple[float, ...], frame_of_reference: str | None = None) → None

Examples using habit.contracts.Geometry

Load from NumPy arrays

Load from NumPy arrays

Per-habitat radiomics

Per-habitat radiomics

Whole-habitat radiomics

Whole-habitat radiomics