points module¶

Points, Space, and the transform graph.

This module makes coordinate spaces first-class. Each Points instance carries a Space tag identifying what its values mean, and the package’s Asset exposes a single transform(points, to=Space.X) method that walks a small graph of named edges to project them.

Graph topology — a tree rooted at ZARR_INDICES:

LS_SCALED_MM ─── ZARR_INDICES ──┬── LS_ANATOMICAL_MM
                                 └── LS_PIPELINE_ANATOMICAL_MM ── CCF_MM

The two anatomical spaces are both attached to ZARR_INDICES rather than chained, because they are derived from different headers (the raw Zarr metadata vs. the pipeline-corrected one); going from one to the other is most naturally expressed as a round-trip through indices.

Each edge function is a small wrapper around an existing low-level helper, with the asset’s cached opened_zarr and transforms threaded through so a multi-hop walk doesn’t re-open the Zarr or re-download transform files.

class aind_zarr_utils.points.Space(*values)[source]

Bases: Enum

Coordinate spaces a Points instance can live in.

ZARR_INDICES: Continuous (sub-voxel) (z, y, x) indices into the Zarr at level 0.

LS_SCALED_MM: Voxel indices multiplied by per-axis level-0 spacing, in millimeters and (z, y, x) order. No anatomical orientation is encoded; this is the format SWC files are typically saved in.

LS_ANATOMICAL_MM: ITK LPS millimeters derived from the raw Zarr metadata header (no pipeline overlay corrections).

LS_PIPELINE_ANATOMICAL_MM: ITK LPS millimeters derived from the pipeline-corrected header. This is the space ANTs registration was trained against.

CCF_MM: Allen Common Coordinate Framework, in LPS millimeters.

ZARR_INDICES = 'zarr_indices'

LS_SCALED_MM = 'ls_scaled_mm'

LS_ANATOMICAL_MM = 'ls_anatomical_mm'

LS_PIPELINE_ANATOMICAL_MM = 'ls_pipeline_anatomical_mm'

CCF_MM = 'ccf_mm'

class aind_zarr_utils.points.Points(values, space, descriptions=None)[source]

Bases: object

A set of named (N, 3) point arrays, all in the same coordinate space.

values

Mapping layer_name → (N, 3) array. The interpretation of the columns depends on space.

Type:: dict[str, NDArray]

space

What the values mean. See Space.

Type:: Space

descriptions

Per-point descriptions when relevant (e.g. Neuroglancer annotation labels). Keyed by layer name; each list parallels the (N, 3) array for that layer.

Type:: dict[str, list[str | None]] or None, optional

Notes

Frozen for reassignment-safety; the inner dict and arrays are not deep-copied — by convention, treat instances as immutable.

values: Mapping[str, ndarray[tuple[Any, ...], dtype[_ScalarT]]]

space: Space

descriptions: dict[str, list[str | None]] | None

classmethod from_neuroglancer(ng_state, layer_names=None, return_description=True)[source]

Build a Points from Neuroglancer annotation state.

Returns points in Space.ZARR_INDICES. Wraps neuroglancer_annotations_to_indices() and converts its description NDArray[object] values into list[str | None] for cleaner typing.

Return type:: Points

classmethod from_swc(swc_data, *, axis_order='zyx', units='micrometer')[source]

Build a Points from raw SWC neuron coordinates.

Performs unit conversion to millimeters and reorders the columns to (z, y, x); no Zarr access is required. The resulting Space.LS_SCALED_MM points can then be projected onto Zarr indices, anatomical space, or CCF via transform().

Parameters:

swc_data (dict[str, ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]]] | ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]]) – (N, 3) array (single neuron) or mapping neuron_id → (N, 3) array.
axis_order (str) – Axis order of the input columns (any permutation of "zyx"). Default "zyx".
units (str) – Length unit of the input coordinates. Default "micrometer".

Return type:

Points

__init__(values, space, descriptions=None)

aind_zarr_utils.points.transform_points(asset, points, *, to)[source]

Project points to to, walking the transform graph step by step.

Parameters:

asset (Asset) – The acquisition context. Provides the cached opened Zarr, pipeline-corrected stubs, and ANTs transform-chain paths.
points (Points) – Source points. points.space is the starting node.
to (Space) – Destination space.

Returns:

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

Return type:

Points

Overview¶

Points stores named (N, 3) arrays and a Space tag. The constructor validates shape and coerces values to floating point.

Supported spaces:

Space.ZARR_INDICES
Space.LS_SCALED_MM
Space.LS_ANATOMICAL_MM
Space.LS_PIPELINE_ANATOMICAL_MM
Space.CCF_MM

Examples¶

Manual points:

import numpy as np
from aind_zarr_utils import Points, Space

points = Points(
    {"soma": np.array([[100, 200, 50]])},
    Space.ZARR_INDICES,
)

Neuroglancer points:

points = Points.from_neuroglancer(ng_state)

SWC points:

points = Points.from_swc(
    swc_array,
    axis_order="zyx",
    units="micrometer",
)

Transform through an asset:

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