zarr module¶

Module for turning ZARRs into ants images and vice versa.

The low-level Zarr opening and metadata helpers (_open_zarr, zarr_to_numpy, _zarr_to_scaled, ensure_native_endian, direction_from_*, _unit_conversion, _units_to_meter) live in aind_zarr_utils.io.zarr and aind_zarr_utils.io.metadata and are re-exported here for backwards compatibility. New code should import them from their new homes.

aind_zarr_utils.zarr.scaled_points_to_indices(scaled_points, zarr_uri, *, scale_unit='millimeter', opened_zarr=None)[source]¶

Convert scaled (non-anatomical) coordinates to zarr indices.

Scaled coordinates are voxel indices multiplied by voxel spacing, without anatomical direction information from ND metadata. This function divides by spacing to recover continuous indices.

Parameters:

scaled_points (dict[str, ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]]]) – Mapping layer name → (N, 3) array of scaled coordinates in (z, y, x) order. Coordinates are in the units specified by scale_unit.
zarr_uri (str) – URI of the Zarr file. Used to extract voxel spacing from metadata.
scale_unit (str) – Units of the scaled coordinates. Default is “millimeter”.
opened_zarr (tuple[Node, dict] | None) – Pre-opened Zarr (image_node, zarr_meta). If provided, avoids re-opening the Zarr file.

Returns:

Mapping layer name → (N, 3) array of continuous (floating-point) indices in (z, y, x) order. These can be passed to indices_to_ccf_auto_metadata() or similar functions.

Return type:

dict[str, ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]]]

See also

indices_to_ccf_auto_metadata: Transform indices to CCF coordinates.
swc_data_to_zarr_indices: Similar function for SWC coordinates.
neuroglancer_annotations_to_scaled: Extract scaled coords from Neuroglancer.

Examples

Convert scaled coordinates to indices, then to CCF:

>>> scaled_pts = {"layer1": np.array([[1.0, 2.0, 3.0]])}  # in mm
>>> indices = scaled_points_to_indices(scaled_pts, zarr_uri)
>>> ccf_coords = indices_to_ccf_auto_metadata(indices, zarr_uri)

Notes

Scaled coordinates are physical distances but lack anatomical orientation
The returned indices are continuous (float), not rounded to integers
Uses only Zarr scale metadata, not ND acquisition metadata

aind_zarr_utils.zarr.zarr_to_ants(uri, nd_metadata, level=3, scale_unit='millimeter', set_origin=None, set_corner=None, set_corner_lps=None, opened_zarr=None)[source]¶

Convert a ZARR file to an ANTs image.

Parameters:

uri (str) – URI of the ZARR file.
nd_metadata (dict) – Neural Dynamics metadata.
level (int) – Resolution level to read, by default 3.
scale_unit (str) – Unit for scaling, by default “millimeter”.
set_origin (tuple[float, float, float] | None) – Origin of the image, by default None. Exclusive of set_corner and set_corner_lps.
set_corner (str | None) – Which corner to use, by default None. If set, must specify both set_corner and set_corner_lps, exclusive of set_origin.
set_corner_lps (tuple[float, float, float] | None) – Coordinates of the corner in LPS. If set, must specify both set_corner and set_corner_lps, exclusive of set_origin.
opened_zarr (tuple[Node, dict] | None) – Pre-opened ZARR file (image_node, zarr_meta), by default None. If provided, this will be used instead of opening the ZARR file again.

Returns:

ANTs image object.

Return type:

ANTsImage

aind_zarr_utils.zarr.zarr_to_sitk(uri, nd_metadata, level=3, scale_unit='millimeter', set_origin=None, set_corner=None, set_corner_lps=None, opened_zarr=None)[source]¶

Convert a ZARR file to a SimpleITK image.

Parameters:

uri (str) – URI of the ZARR file.
nd_metadata (dict) – Neural Dynamics metadata.
level (int) – Resolution level to read, by default 3.
scale_unit (str) – Unit for scaling, by default “millimeter”.
set_origin (tuple[float, float, float] | None) – Origin of the image, by default None. Exclusive of set_corner and set_corner_lps.
set_corner (str | None) – Which corner to use, by default None. If set, must specify both set_corner and set_corner_lps, exclusive of set_origin.
set_corner_lps (tuple[float, float, float] | None) – Coordinates of the corner in LPS. If set, must specify both set_corner and set_corner_lps, exclusive of set_origin.
opened_zarr (tuple[Node, dict] | None) – Pre-opened ZARR file (image_node, zarr_meta), by default None. If provided, this will be used instead of opening the ZARR file again.

Returns:

SimpleITK image object.

Return type:

Image

aind_zarr_utils.zarr.zarr_to_sitk_stub(uri, nd_metadata, level=0, scale_unit='millimeter', set_origin=None, set_corner=None, set_corner_lps=None, opened_zarr=None)[source]¶

Create a stub SimpleITK image with the same metadata as the ZARR file.

Parameters:

uri (str) – URI of the ZARR file.
nd_metadata (dict) – Neural Dynamics metadata.
level (int) – Resolution level to read, by default 0.
scale_unit (str) – Unit for scaling, by default “millimeter”.
set_origin (tuple[float, float, float] | None) – Origin of the image, by default None. Exclusive of set_corner and set_corner_lps.
set_corner (str | None) – Which corner to use, by default None. If set, must specify both set_corner and set_corner_lps, exclusive of set_origin.
set_corner_lps (tuple[float, float, float] | None) – Coordinates of the corner in LPS. If set, must specify both set_corner and set_corner_lps, exclusive of set_origin.
opened_zarr (tuple[Node, dict] | None) – Pre-opened ZARR file (image_node, zarr_meta), by default None. If provided, this will be used instead of opening the ZARR file again.

Return type:

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

Returns:

sitk.Image – SimpleITK stub image object.
tuple – The size of the image data in each dimension of the underlying array, in SimpleITK order (column-major).

Overview¶

The zarr module provides the core functionality for converting ZARR datasets to ANTs and SimpleITK images. It handles multi-resolution data, coordinate system transformations, and metadata extraction while maintaining anatomical accuracy.

Key Concepts¶

Resolution Levels

ZARR files contain multiple resolution levels. Higher numbers = lower resolution:

Level 0: Full resolution
Level 3: Typical working resolution (default)
Level 5+: Preview/thumbnail resolution

Coordinate Systems

All functions output LPS (Left-Posterior-Superior) coordinates:

ANTs: Uses LPS natively
SimpleITK: Requires axis reversal due to Fortran-style indexing

Scale Units

Supports automatic unit conversion:

"micrometer": Original acquisition units
"millimeter": Standard for medical imaging (default)

Examples¶

Basic ZARR to image conversion:

from aind_zarr_utils.zarr import zarr_to_ants, zarr_to_sitk
from aind_s3_cache.json_utils import get_json

# Load metadata
metadata = get_json("s3://bucket/metadata.json")
zarr_uri = "s3://bucket/data.ome.zarr/0"

# Convert to ANTs image (for registration/analysis)
ants_img = zarr_to_ants(zarr_uri, metadata, level=3, scale_unit="millimeter")

# Convert to SimpleITK image (for ITK operations)
sitk_img = zarr_to_sitk(zarr_uri, metadata, level=3, scale_unit="millimeter")

Memory-efficient coordinate transformations:

from aind_zarr_utils.zarr import zarr_to_sitk_stub

# Create stub image (minimal memory, same coordinate system)
stub_img, size = zarr_to_sitk_stub(zarr_uri, metadata, level=0)

# Use stub for coordinate transformations without loading pixel data
physical_point = stub_img.TransformIndexToPhysicalPoint([100, 200, 50])

Custom origin positioning:

# Position image corner at specific anatomical location
ants_img = zarr_to_ants(
    zarr_uri, metadata,
    set_corner="RAS",  # Right-Anterior-Superior corner
    set_corner_lps=(10.0, 5.0, 15.0)  # Position in LPS coordinates
)