acia.segm.open#

Format-agnostic lazy opener for multi-position acquisitions.

open_sequence() dispatches by filename suffix to a per-format backend and returns a SequenceFile — a lazy handle that exposes unified metadata and a per-position time series without loading pixels. A “position” is the ND2 P axis and the CZI S (scene) axis, unified here so the notebook and dashboard never branch on format.

A path that is a directory is opened as a folder of per-timepoint TIFFs (one file per frame); a folder whose immediate subfolders hold the TIFFs exposes one position per subfolder, so folder trees, ND2 and CZI all reach the notebook through the same SequenceFile.position() surface.

Reading SequenceFile.metadata / SequenceFile.positions performs no pixel reads for ND2/CZI; SequenceFile.thumbnail() reads exactly one (downscaled) frame. (The TIFF backends read frame 0 to determine its shape — a TIFF stack or a single per-timepoint file is small, unlike the hundred-gigabyte ND2/CZI files this module is built for.)

class acia.segm.open.SequenceMetadata[source]#

Bases: object

File-level metadata, unified across formats. JSON-safe via to_dict().

sizes: dict[str, int]#

pixel_size: object | None#

frame_interval: object | None#

channels: list[str]#

dtype: str#

num_positions: int#

num_timepoints: int#

to_dict()[source]#

Emit the manifest source metadata block (plain floats + strings).

Return type:: dict

__init__(sizes, pixel_size, frame_interval, channels, dtype, num_positions, num_timepoints)#

Parameters:

sizes (dict[str, int])
pixel_size (object | None)
frame_interval (object | None)
channels (list[str])
dtype (str)
num_positions (int)
num_timepoints (int)

Return type:

None

class acia.segm.open.PositionInfo[source]#

Bases: object

Lightweight per-position descriptor for the gallery (no pixel reads).

index: int#

name: str | None = None#

stage_xy: tuple[float, float] | None = None#

__init__(index, name=None, stage_xy=None)#

Parameters:

index (int)
name (str | None)
stage_xy (tuple[float, float] | None)

Return type:

None

class acia.segm.open.SequenceFile[source]#

Bases: object

Lazy handle over a multi-position acquisition (format-agnostic).

Construct via open_sequence(). Reading metadata/positions performs no pixel reads for ND2/CZI. Per-position sources are created on demand and cached (one source per position).

__init__(path, fmt, *, pixel_size=None, frame_interval=None, pattern=None)[source]#

Parameters:

path (str | PathLike)
fmt (str)

Return type:

None

position(index)[source]#

Return the per-position lazy ImageSequenceSource for index.

Parameters:: index (int)

property metadata: SequenceMetadata#: Unified file-level metadata (no pixel reads for ND2/CZI).

property num_positions: int#: Number of positions (ND2 P / CZI S / folder subfolders / 1).

property positions: list[PositionInfo]#: Per-position descriptors, lazily built (no pixel reads).

thumbnail(index, *, downscale=8, frame=0)[source]#

A downscaled (h, w, 3) uint8 preview of one frame (lazy).

Reads exactly one frame of index, takes the display channel (0), min-max normalizes, strides by downscale, and returns an RGB preview.

Parameters:

index (int)
downscale (int)
frame (int)

Return type:

ndarray

thumbnail_png(index, *, downscale=8, frame=0)[source]#

PNG-encoded bytes of thumbnail() (for the widget’s byte channel).

Parameters:

index (int)
downscale (int)
frame (int)

Return type:

bytes

close()[source]#

Release cached per-position readers.

Return type:: None

acia.segm.open.open_sequence(path, *, pixel_size=None, frame_interval=None, pattern=None)[source]#

Open an acquisition by filename suffix (ND2/CZI/TIFF) or as a folder.

A path that is a directory is opened as a folder of per-timepoint TIFFs – one file per frame, or one subfolder per position (see acia.segm.folder_source.resolve_layout()). ND2/CZI dispatch purely on suffix and stay strictly IO-free, so opening a hundred-gigabyte acquisition costs nothing until metadata or a position is touched; only an unknown or TIFF-like name is probed with a stat.

Returns a lazy SequenceFile. User pixel_size/frame_interval override any file metadata and propagate to every per-position source.

Parameters:

path – file to open, or a directory of per-timepoint TIFFs.
pixel_size – physical pixel size overriding the file’s own metadata.
frame_interval – scalar time between frames, likewise overriding.
pattern – frame-filename glob, folders only (None -> .tif/.tiff).

Raises:

ValueError – If the suffix maps to no supported reader and the path is not a directory, or if pattern is given for a non-folder path.

Return type:

SequenceFile