asset module

Asset façade — a single object that owns an opened Zarr plus its metadata.

This module is the user-facing entry point introduced by the API redesign. An Asset instance carries:

  • the URI of the alignment-channel Zarr,

  • optionally, the source Zarr URI used to discover that alignment channel,

  • the parsed metadata.nd.json (ND/acquisition metadata),

  • the parsed processing.json,

  • an opened ome-zarr Node (lazily acquired, cached for the lifetime of the asset),

  • per-asset configuration: overlay selector, S3 client, anonymous flag, cache directory, and template selection.

The methods on Asset (image, stub, apply_overlays) and the lazy transforms property delegate to the existing free functions in aind_zarr_utils.zarr, aind_zarr_utils.image, and aind_zarr_utils.io.transforms, threading opened_zarr=self.opened_zarr everywhere so that no S3 resource is read twice in a logical workflow.

Three eager constructors handle the common discovery patterns:

  • Asset.from_zarr() — pass any acquisition-Zarr URI; the alignment channel is auto-resolved from the asset root.

  • Asset.from_root() — pass the asset root directly.

  • Asset.from_neuroglancer() — pull a Zarr URI from the image_sources of a Neuroglancer state and resolve from there.

The bare constructor Asset(alignment_zarr_uri, metadata, processing) is the no-I/O path: pass already-loaded values explicitly. The Zarr is still opened lazily on first access.

Notes

Asset is not thread-safe. ome-zarr’s Reader holds an fsspec filesystem object that is fork-unsafe; do not pass an opened Asset across processes.

class aind_zarr_utils.asset.TransformPaths(point_paths, point_invert, image_paths, image_invert)[source]

Bases: object

Local filesystem paths for the pipeline’s ANTs transform chains.

Both the image (forward) and point (reverse) chain files are materialised together so that round-tripping points through CCF reuses the same downloaded files.

point_paths

Paths to the transform files in the order ANTs expects when warping points (CCF → individual: image-direction inverse).

Type:

list[str]

point_invert

Whether each entry in point_paths should be inverted by ANTs.

Type:

list[bool]

image_paths

Paths to the transform files in the order ANTs expects when warping images (individual → CCF: forward direction).

Type:

list[str]

image_invert

Whether each entry in image_paths should be inverted by ANTs.

Type:

list[bool]

point_paths: list[str]
point_invert: list[bool]
image_paths: list[str]
image_invert: list[bool]
__init__(point_paths, point_invert, image_paths, image_invert)
class aind_zarr_utils.asset.Asset(alignment_zarr_uri, metadata, processing, source_zarr_uri=None, overlay_selector=<factory>, s3_client=None, anonymous=True, cache_dir=None, template_used='SmartSPIM-template_2024-05-16_11-26-14', template_base=None)[source]

Bases: object

A SmartSPIM acquisition with eager metadata and lazy Zarr/transform I/O.

Parameters:

  • alignment_zarr_uri (str) – URI of the alignment-channel Zarr. Use the classmethods from_zarr() / from_root() / from_neuroglancer() to discover this from a different starting point.

  • metadata (Mapping[str, Any]) – Parsed metadata.nd.json.

  • processing (Mapping[str, Any]) – Parsed processing.json.

  • source_zarr_uri (str | None) – Original acquisition Zarr URI used for discovery. Set by from_zarr() and from_neuroglancer(); None for from_root() and explicit construction unless supplied.

  • overlay_selector (OverlaySelector) – Pipeline-overlay selector. Defaults to the cached singleton returned by get_selector(); the factory call avoids the import-time binding trap of using = get_selector() as a default-arg expression.

  • s3_client (S3Client | None) – S3 access knobs forwarded to pipeline_transforms_local_paths().

  • anonymous (bool) – S3 access knobs forwarded to pipeline_transforms_local_paths().

  • cache_dir (str | PathLike | None) – S3 access knobs forwarded to pipeline_transforms_local_paths().

  • template_used (str) – Key naming the template→CCF transform set to use. Defaults to "SmartSPIM-template_2024-05-16_11-26-14".

  • template_base (str | PathLike | None) – Override base path for the template transforms (e.g. a local mirror). If None, the canonical S3 location is used.

alignment_zarr_uri: str
metadata: Mapping[str, Any]
processing: Mapping[str, Any]
source_zarr_uri: str | None
overlay_selector: OverlaySelector
s3_client: S3Client | None
anonymous: bool
cache_dir: str | PathLike | None
template_used: str
template_base: str | PathLike | None
classmethod from_zarr(zarr_uri, *, anonymous=True, s3_client=None, cache_dir=None, overlay_selector=None, template_used='SmartSPIM-template_2024-05-16_11-26-14', template_base=None)[source]

Discover the asset’s metadata + alignment Zarr from any acquisition Zarr URI.

Walks up two directory levels from zarr_uri to find the asset root, loads metadata.nd.json and processing.json, infers the alignment channel from the processing metadata, and pre-opens the alignment Zarr (eager). The zarr_uri you pass need not itself be the alignment channel.

Return type:

Asset

classmethod from_root(asset_uri, *, anonymous=True, s3_client=None, cache_dir=None, overlay_selector=None, template_used='SmartSPIM-template_2024-05-16_11-26-14', template_base=None)[source]

Discover the asset’s metadata + alignment Zarr from the asset root URI.

Return type:

Asset

classmethod from_neuroglancer(ng_state, *, asset_uri=None, anonymous=True, s3_client=None, cache_dir=None, overlay_selector=None, template_used='SmartSPIM-template_2024-05-16_11-26-14', template_base=None)[source]

Discover the asset from a Neuroglancer state.

If asset_uri is given, behaves like from_root(). Otherwise the first image_sources URL in ng_state is used as the starting point (passed to from_zarr()).

Return type:

Asset

property opened_zarr: tuple[Node, dict]

The opened ome-zarr (Node, metadata) tuple, opened on first access.

property transforms: TransformPaths

The pipeline’s ANTs transform chains as local file paths.

First access downloads (or locates in the aind_s3_cache cache) all required transform files; the result is cached for the lifetime of the asset.

image(*, level=3, library='sitk', pipeline=False, origin=None, scale_unit='millimeter')[source]

Build a full image from the asset’s Zarr at the given pyramid level.

Parameters:

  • level (int) – Resolution level (0 = full resolution; higher = coarser). Default 3.

  • library (Literal['sitk', 'ants']) – Backend. Default "sitk".

  • pipeline (bool) – If True, apply pipeline overlay corrections in-place after constructing the image. Default False.

  • origin (Origin | None) – Origin specification. Defaults to Origin.default(). Only valid when pipeline=False; pipeline images use the corrected header’s origin.

  • scale_unit (str) – Output spacing unit. Default "millimeter".

Returns:

The constructed image, with pipeline corrections applied if pipeline=True.

Return type:

Image | ANTsImage

stub(*, pipeline=False, origin=None, scale_unit='millimeter', level=0)[source]

Build a header-only SimpleITK stub for the asset’s Zarr.

Return type:

tuple[Image, tuple[int, int, int]]

Returns:

  • stub (sitk.Image) – A 1×1×1 SimpleITK image whose spatial header matches what a full-resolution image would have, optionally with pipeline corrections applied.

  • size_ijk (tuple of three ints) – The level-0 native voxel dimensions of the acquisition, in SimpleITK index order.

Notes

Only SimpleITK is currently supported for stubs (mirrors the existing zarr_to_sitk_stub API). origin is only valid when pipeline=False; pipeline stubs use the corrected header’s origin.

apply_overlays(img, *, level=3)[source]

Apply pipeline overlay corrections in-place to img.

Type-dispatches on img to handle SimpleITK and ANTs. See aind_zarr_utils.image.apply_pipeline_overlays() for the per-level math; this method threads the asset’s overlay_selector and cached opened_zarr through.

Return type:

None

transform(points, *, to)[source]

Project points to coordinate space to.

Walks the small transform graph defined in aind_zarr_utils.points, applying one edge at a time. The asset’s cached opened_zarr and transforms are reused at every hop, so a multi-hop walk performs at most one Zarr open and one transform-chain download.

Parameters:

  • points (Points) – Source points. points.space determines the starting node in the graph.

  • to (Space) – Destination coordinate space.

Returns:

New Points with the same values keys (and per-point descriptions, if any) projected to to.

Return type:

Points

__init__(alignment_zarr_uri, metadata, processing, source_zarr_uri=None, overlay_selector=<factory>, s3_client=None, anonymous=True, cache_dir=None, template_used='SmartSPIM-template_2024-05-16_11-26-14', template_base=None)

Overview

Asset is the recommended user-facing entry point. It owns the alignment-channel Zarr URI, parsed metadata, parsed processing metadata, the opened Zarr cache, and transform-chain cache.

Common constructors:

from aind_zarr_utils import Asset

asset = Asset.from_zarr("s3://bucket/dataset/image.ome.zarr/0")
asset = Asset.from_root("s3://bucket/dataset")
asset = Asset.from_neuroglancer(ng_state)

No-I/O construction is available when metadata is already loaded:

asset = Asset(
    alignment_zarr_uri="s3://bucket/dataset/alignment.ome.zarr/0",
    metadata=metadata,
    processing=processing,
)

Examples

Build images and stubs:

from aind_zarr_utils import Origin

sitk_img = asset.image(level=3)
ants_img = asset.image(level=3, library="ants")
stub, size_ijk = asset.stub(level=0)
pipeline_stub, native_size_ijk = asset.stub(pipeline=True)

anchored = asset.image(
    level=3,
    origin=Origin.at_corner("RAS", (0.0, 0.0, 0.0)),
)

Transform points:

from aind_zarr_utils import Points, Space

points = Points.from_neuroglancer(ng_state)
ccf = asset.transform(points, to=Space.CCF_MM)