acia.segm.czi_source

Lazy, memory-bounded image source for Zeiss CZI files.

A CZI file may contain several scenes (stage positions); the ROI workflow processes a single scene, which itself is a time series. CZISequenceSource selects one scene and exposes that scene’s (T, H, W, C) time series through the standard ImageSequenceSource contract.

The CZI file is opened lazily on first access and read one plane at a time via aicspylibczi’s read_image (which reads only the addressed subblocks), so peak memory stays at a single frame regardless of file size (CZI files may be hundreds of gigabytes). aicspylibczi is an optional dependency, imported lazily inside CZISequenceSource._ensure_reader().

This mirrors acia.segm.nd2_source: a “position” is the CZI scene (S) axis, the exact analogue of ND2’s P.

class acia.segm.czi_source.CZISequenceSource

Bases: ImageSequenceSource, JupyterVisualizationMixin

A single CZI scene exposed as a lazy (T, H, W, C) time series.

Axis mapping is done by name (using the reader’s dims string), never by a fixed axis order. For each frame the source selects S == position and T == frame, moves the channel axis last, and adds a trailing channel axis for grayscale planes so every frame is shaped (H, W, C).

The reader is opened lazily and only a single plane is materialized at a time via read_image; the whole scene/file is never loaded.

Parameters:

• path – Path to the .czi file.

• position – Index of the scene to expose. A file with no S axis is treated as a single scene (only 0 is valid).

• pixel_size – Optional pint length per pixel that overrides the file’s scaling metadata. Strings like "0.5 um" are accepted.

• frame_interval – Optional scalar time between frames (pint or string) that overrides metadata-derived timing.

• timepoints – Optional explicit per-frame pint Quantity array that overrides metadata-derived timing.

__init__(path, position=0, *, pixel_size=None, frame_interval=None, timepoints=None)

Parameters:

• path (str)

• position (int)

Return type:

None

property sizes: dict[str, int]

The CZI axis-size mapping (e.g. {'S': 107, 'T': 294, ...}).

property n_scenes: int

Number of scenes (positions) in the file; 1 if there is no S axis.

property scene_names: dict[int, str | None]

Mapping of scene index -> name (e.g. {0: 'P1', 1: 'P2', ...}).

property pixel_size

Pint length per pixel, resolved from the file (or override).

property timepoints

Per-frame pint timepoints, or None if uncalibrated.

property dtype: str

Numpy dtype string mapped from the CZI pixel type (best-effort).

property channel_names: list[str]

Channel names from CZI metadata (best-effort; empty if unavailable).

property size_t: int

Number of frames (T); 1 if the file has no T axis.

property size_h: int

Image height (Y).

property size_w: int

Image width (X).

property size_c: int

Number of channels (C); 1 if the file has no C axis.

property num_channels: int

Number of channels (alias of size_c).

get_frame(frame)

Read a single (H, W, C) plane for (scene=position, frame).

Only the requested plane is materialized (via read_image); the whole scene/file is never loaded.

Parameters:

frame (int) – Time index of the frame to read.

Returns:

BaseImage – A LocalImage wrapping the (H, W, C) plane.

Return type:

BaseImage