acia.segm.nd2_source

Lazy, memory-bounded image source for Nikon ND2 files.

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

The ND2 file is opened lazily on first access and read one frame at a time via the nd2 dask interface, so peak memory stays at a single frame regardless of file size (ND2 files may be tens of gigabytes). nd2 is an optional dependency, imported lazily inside ND2SequenceSource._ensure_reader().

class acia.segm.nd2_source.ND2SequenceSource

Bases: ImageSequenceSource, JupyterVisualizationMixin

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

Axis mapping is done by name (using the file’s sizes dict), never by a fixed axis order. For each frame the source selects P == 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 frame is materialized at a time via nd2’s dask interface; the whole array is never loaded.

Parameters:

• path – Path to the .nd2 file.

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

• pixel_size – Optional pint length per pixel that overrides the file’s voxel size. 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 ND2 axis-size mapping (e.g. {'P': 2, 'T': 5, ...}).

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 of the pixel data (from metadata, no pixel read).

property channel_names: list[str]

Channel names from ND2 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 (position, frame).

Only the requested frame is materialized (via the dask interface); the whole array 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