Low-level image I/O helpers

Convenience re-exports for image volumes and file I/O.

Canonical types live in habit.contracts.image. File I/O and resampling live in habit.adapters.volume_io. Import this package from notebooks or CLI helpers that need both in one place; L0-L3 code must import types from habit.contracts and must not import this package (it pulls adapters).

User guide: Data model (habit.contracts). Prefer contracts volumes inside pipelines; use these when you need SimpleITK-backed read / geometry checks outside a Subject.

Classes

`GeometryPolicy`	Define how an image/mask geometry mismatch is handled.
`GeometryReport`	Describe image/mask geometry compatibility and any correction applied.
`ImageVolume`	An image array with explicit physical-space metadata.
`MaskVolume`	An image-space segmentation mask with explicit label semantics.
`ImageMaskPair`	Pair one image and mask with the geometry result used by downstream code.

`FeatureResult`	Structured output from radiomics extraction for one image/mask pair.
`FeatureTableResult`	Structured batch output with successful feature rows and failures.

Functions

`read_image`	Read an image file into a geometry-aware `ImageVolume`.
`read_mask`	Read a mask file into a geometry-aware `MaskVolume`.
`validate_geometry`	Return an explicit geometry comparison without changing either input.
`align_image_mask`	Validate or explicitly correct image/mask geometry according to `policy`.

`extract_features`	Extract segment-based radiomics features from one image/mask pair.
`extract_batch`	Extract radiomics features deterministically for an ordered image/mask batch.

File I/O helpers (read_image / read_mask / geometry checks). Prefer contracts volumes inside pipelines (Data model (habit.contracts)); use these when you need SimpleITK-backed read / geometry checks outside a Subject.

from habit.image import (
    GeometryPolicy,
    ImageMaskPair,
    align_image_mask,
    read_image,
    read_mask,
    validate_geometry,
)

image = read_image("data/subj001/T2.nii.gz", modality="T2")
mask = read_mask("data/subj001/mask_T2.nii.gz")

report = validate_geometry(image, mask)
print(report.compatible, report.mismatches)

pair = align_image_mask(
    ImageMaskPair(image, mask),
    policy=GeometryPolicy.RESAMPLE_MASK,
)
aligned_image, aligned_mask = pair.image, pair.mask
print(pair.geometry_report)

GeometryPolicy modes

Policy	Behaviour on mismatch
`STRICT`	Raise `GeometryError` (default for this API and for `extract_features` / `extract_batch`)
`WARN`	Emit `RuntimeWarning`; leave arrays/metadata unchanged; `geometry_report.compatible` is `False`, `action="warn"`
`RESAMPLE_MASK`	Resample mask onto the image grid (nearest neighbour); report `compatible=True`, `action="resample_mask"`
`RESAMPLE_IMAGE`	Resample image onto the mask grid (linear); report `compatible=True`, `action="resample_image"`
`HARMONIZE`	When shapes match, copy the image spacing, origin, and direction onto the mask array without resampling (`action="harmonize"`). When shapes differ, fall through to `RESAMPLE_MASK`.

Exports: GeometryPolicy, GeometryReport, ImageVolume, MaskVolume, ImageMaskPair, read_image, read_mask, validate_geometry, align_image_mask.

Warning

Top-level ImageVolume / MaskVolume here are the API types. Pipeline code should use habit.contracts.ImageVolume / habit.contracts.MaskVolume.

Low-level radiomics extraction

Component API (not the YAML workflow):

from habit.image import GeometryPolicy
from habit.radiomics.extract import extract_batch, extract_features

result = extract_features(image, mask, params="params.yaml")
batch = extract_batch(
    cases,
    params="params.yaml",
    geometry_policy=GeometryPolicy.STRICT,
    fail_fast=True,   # default: raise on first pair failure
)

fail_fast=False keeps successful rows and records per-subject errors in FeatureTableResult.failures (see Fault tolerance patterns).

Returns FeatureResult / FeatureTableResult.