annotations module

Module for working with points in ZARR files.

aind_zarr_utils.annotations.annotation_indices_to_anatomical(img, annotations)[source]

Transform annotation indices from image space to anatomical space.

Parameters:

  • img (Image) – The reference image.

  • annotations (dict[str, ndarray[tuple[Any, ...], dtype[TypeVar(_ScalarT, bound= generic)]]]) – Dictionary where keys are annotation names and values are numpy arrays of indices. Indices can be continuous (floating-point) values representing sub-voxel positions, or integer voxel coordinates.

Returns:

anatomical_points – Dictionary where keys are annotation names and values are anatomical points (in LPS coordinate system).

Return type:

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

aind_zarr_utils.annotations.annotations_and_descriptions_to_dict(annotation_points, descriptions)[source]

Convert annotation points and descriptions into a description-to-point dictionary.

Parameters:

  • annotation_points (dict[str, list[list[float]]]) – Dictionary where keys are annotation names and values are lists of points.

  • descriptions (dict[str, list[str | None]]) – Dictionary where keys are annotation names and values are lists of descriptions.

Returns:

Dictionary where keys are annotation names and values are point dictionaries.

Return type:

dict[str, dict[str, list[float]]]

Overview

The annotations module provides utilities for transforming point annotations from image space to anatomical space. It works with SimpleITK images to handle coordinate transformations while maintaining proper LPS (Left-Posterior-Superior) coordinate conventions.

Coordinate Systems

This module works exclusively with LPS (Left-Posterior-Superior) coordinates, which is the standard for medical imaging and ITK/SimpleITK:

  • L: Left direction is positive X

  • P: Posterior direction is positive Y

  • S: Superior direction is positive Z

Examples

Transform annotation points from image indices to anatomical coordinates:

import SimpleITK as sitk
import numpy as np
from aind_zarr_utils.annotations import annotation_indices_to_anatomical

# Create sample annotation points (as image indices)
points = {
    "region1": np.array([[10, 20, 30], [40, 50, 60]]),
    "region2": np.array([[100, 200, 300]])
}

# Transform to anatomical space using SimpleITK image header
anatomical_points = annotation_indices_to_anatomical(sitk_image, points)

# Result is in LPS coordinates (millimeters)
print(anatomical_points["region1"])  # Physical coordinates in LPS