acia.segm.formats

Functions for different segmentation formats

acia.segm.formats.parse_simple_segmentation(file_content)

Parse simple segmentation format from string (json)

Parameters:

file_content (str) – simple segmentation file content as string

Returns:

Overlay – the overlay representation of the segmentation

Return type:

Overlay

acia.segm.formats.gen_simple_segmentation(overlay)

Create a simple segmentation string from an Overlay

Parameters:

overlay (Overlay) – the overlay to store

Returns:

str – string containing the stringified simple segmentation json format

Return type:

str

acia.segm.formats.save_segmentation(path, overlay)

Store a segmentation Overlay as a compressed binary polygon archive.

The counterpart of load_segmentation(). Contours are written as one flat float32 coordinate array plus per-detection offsets, alongside the id, label and frame of each detection – so ids and sub-pixel coordinates survive exactly and a reloaded overlay joins against a property table exported from the same segmentation.

Why this rather than the alternatives, measured on a dense 150k-detection scene (1024x1024, 300 cells x 500 frames): gzipped gen_simple_segmentation() JSON is 106 MiB / 43 s to write, this format is 41 MiB / 1.7 s, and a zlib label-mask stack is 18 MiB / 2.0 s. The mask stack is smaller still, but rasterizing renumbers detection ids (overlay_from_masks()) and yields mask-backed Instance objects whose geometry is derived from the full frame, making downstream property extraction ~20x slower. Keeping polygons keeps both the ids and the fast extraction path.

What is not stored: the overlay’s time model (attach it on load from the image source, see load_segmentation()), per-detection scores, and mask topology – Instance masks are serialized as polygons.

Parameters:

• path (str | Path) – output file. A missing .npz suffix is appended, so .../segmentation and .../segmentation.npz are equivalent. Parent directories are created.

• overlay (Overlay) – the segmentation to store.

Returns:

The path actually written (with the normalized suffix).

Raises:

TypeError – if detection ids or labels are of mixed types, which numpy cannot store without pickling.

Return type:

Path

acia.segm.formats.load_segmentation(path, source=None)

Load a segmentation stored by save_segmentation().

The format is detected from the file’s magic bytes, not its suffix, so the binary archive written by save_segmentation() and a plain or gzipped simple-segmentation JSON (gen_simple_segmentation(), the interchange format other tools read) all load through this one function.

Passing source – the image sequence the segmentation was computed on – restores what the artifact cannot carry, and takes precedence over anything stored in the file:

• the frame extent: the returned overlay spans source.size_t. This matters because a movie whose last frames hold no surviving cells would otherwise reload shorter than it really is (the JSON interchange format drops empty frames entirely).

• the time model: source.timepoints is attached (stamping each detection’s time) when the source is time-calibrated. An uncalibrated source leaves the overlay uncalibrated – no time is invented.

Detection ids are stable across this round-trip (see save_segmentation()).

Parameters:

• path (str | Path) – the artifact to read. If the literal path does not exist, the .npz-normalized name is tried, so this mirrors whatever save_segmentation() accepted.

• source (ImageSequenceSource | None) – image sequence used to restore frame extent and time calibration. None falls back to the extent stored in the archive (or, for JSON input, the last populated frame).

Returns:

The segmentation overlay.

Raises:

FileNotFoundError – if neither the literal nor the normalized path exists.

Return type:

Overlay

acia.segm.formats.load_ctc_segmentation(segmentation_path)

Parameters:

segmentation_path (Path)

Return type:

Overlay

acia.segm.formats.read_ctc_segmentation_native(segmentation_path)

Fast loading of CTC segmentation masks into an Overlay

Parameters:

segmentation_path (Path) – Path to the folder containing all the *.tif masks

Returns:

Overlay – Overlay containing all masks

Return type:

Overlay

acia.segm.formats.overlay_from_masks(segm_masks)

Create a multi-frame overlay from an array of masks

Parameters:

segm_masks (np.ndarray) – mask array [T x H x W]

Returns:

Overlay – returns the multi-frame overly with cell instances

Return type:

Overlay