image module

Backend-agnostic pipeline-overlay application for SimpleITK / ANTs images.

This module is the single home for the math that takes a pipeline-corrected AnatomicalHeader (built in SimpleITK convention from a Zarr stub at level 0) and projects it onto either a SimpleITK or ANTs image at an arbitrary pyramid level.

The two backends agree at level 0 — there it’s a straightforward AnatomicalHeader.from_<backend>(img) → apply_overlays → update_<backend>(img) loop. They diverge at level > 0:

  • SimpleITK: spacing scaled by 2**level; origin and direction copied through verbatim.

  • ANTs: spacing reversed (because ANTs and SimpleITK transpose numpy arrays relative to each other) then scaled by 2**level; origin recomputed via fix_corner_compute_origin() so that the opposite anatomical corner of the ANTs image lands at the level-0 SimpleITK origin; direction left untouched (and assumed to match the corrected header’s direction — true for the default rule set, where overlays only modify origin and spacing).

The level > 0 ANTs math lives in _to_ants_convention(), a small pure helper that’s directly testable.

aind_zarr_utils.image.apply_pipeline_overlays(img, zarr_uri, processing_data, metadata, level=3, *, overlay_selector=OverlaySelector(rules=(OverlayRule(name='Fixed world image spacing (0.0144, 0.0144, 0.016)', spec=<SpecifierSet('<0.0.32, >=0.0.18')>, factory=<function _base_rules.<locals>.<lambda>>, start=None, end=None, predicate=None, rule_priority=55, group=None, stop_after=False), OverlayRule(name='anchor RAS corner to recorded bug point', spec=<SpecifierSet('>=0.0.18')>, factory=<function _base_rules.<locals>.<lambda>>, start=None, end=None, predicate=None, rule_priority=90, group=None, stop_after=False))), opened_zarr=None)[source]

Apply pipeline overlay corrections in-place to img.

Type-dispatches on img to handle SimpleITK and ANTs:

  • SimpleITK + level=0 — build a base header from img via AnatomicalHeader.from_sitk, run overlays, write back via update_sitk.

  • SimpleITK + level>0 — fetch the level-0 corrected header via _build_pipeline_header(), scale spacing by 2**level, copy origin/direction through.

  • ANTs + level=0 — same as SITK but using from_ants / update_ants.

  • ANTs + level>0 — fetch the level-0 SITK-convention corrected header, then project to ANTs via _to_ants_convention().

Parameters:

  • img (Image | ANTsImage) – Image whose spatial header will be modified in place.

  • zarr_uri (str) – URI of the raw Zarr store.

  • processing_data (dict) – Processing metadata.

  • metadata (dict) – ND (instrument/acquisition) metadata.

  • level (int) – Pyramid level of img. Default is 3.

  • overlay_selector (OverlaySelector) – Selector for overlay rules. Defaults to the global cached selector.

  • opened_zarr (tuple[Node, dict] | None) – Pre-opened (image_node, zarr_meta) to avoid re-opening the Zarr.

Returns:

img’s spatial metadata is mutated in place.

Return type:

None

Overview

The image module contains shared implementation details used by Asset.image(), Asset.stub(), and the legacy pipeline_transformed shim. Most user code should call methods on Asset instead of importing this module directly.