acia.selection#

Selection manifest — persist curation and reconstruct lazy crops.

A SelectionManifest records a set of ROI selections (position + rotated rectangle) plus the source metadata baked in (pixel size, timing, axes), so downstream analysis reconstructs only the selected crops — lazily — without re-opening the original (possibly hundreds-of-GB) file for calibration.

load_selection() turns a manifest back into a list of lazy cropped ImageSequenceSource views, optionally against a different file (“load file, apply selection, work only on the crops”). No pixel data is read while building the crops; each is a lazy rotated-rectangle view.

class acia.selection.RoiSelection[source]#

Bases: object

One curated ROI: a rotated-rectangle crop of a single position.

Variables:

  • position (int) – Index of the position the ROI was drawn on.

  • roi (acia.base.RotatedCropSpec) – The rotated rectangle, in the pixel coordinate system of the frame it was drawn on – see anchor_frame.

  • label (str) – Free-text label, shown in the curation UI and available to export naming templates.

  • id (str) – Stable identifier; also names the preview PNG.

  • notes (str) – Free-text notes.

  • preview (str | None) – Optional file name of a preview image for this ROI.

  • anchor_frame (int) – The frame index roi was drawn on. Cropping the raw source ignores this – the spec is already in that source’s coordinates. It matters after drift correction: a RegisteredSequenceSource puts every frame into the reference frame’s coordinate system, so a spec anchored anywhere else must first be carried across with acia.registration.apply_correction_to_spec() or the crop lands off by the drift accumulated up to this frame. Defaults to 0, which is what every selection written before this field existed in fact was – frame 0 was the only frame the editor showed.

position: int#
roi: RotatedCropSpec#
label: str = ''#
id: str = ''#
notes: str = ''#
preview: str | None = None#
anchor_frame: int = 0#
property spec: RotatedCropSpec#

The rotated-crop spec (image pixels), usable by crop_rotated.

to_dict()[source]#
Return type:

dict

classmethod from_dict(data)[source]#
Parameters:

data (dict)

Return type:

RoiSelection

__init__(position, roi, label='', id='', notes='', preview=None, anchor_frame=0)#
Parameters:
Return type:

None

class acia.selection.SelectionManifest[source]#

Bases: object

A curation result: selections + baked-in source metadata.

source: dict#
selections: list[RoiSelection]#
roi_mode: str = 'single'#
schema: str = 'acia.selection/v1'#
created: str | None = None#
property source_path: str#

Path of the original file the selections were made against.

to_dict()[source]#
Return type:

dict

classmethod from_dict(data)[source]#
Parameters:

data (dict)

Return type:

SelectionManifest

save(path)[source]#

Write the manifest as pretty JSON; returns the written path.

Parameters:

path (str | PathLike)

Return type:

str

classmethod load(path)[source]#

Read a manifest from a selection.json file.

Parameters:

path (str | PathLike) – The selection.json file, or the directory containing it — i.e. the same directory save_selection() was given, so a caller can round-trip an output dir without restating the filename.

Return type:

SelectionManifest

__init__(source, selections=<factory>, roi_mode='single', schema='acia.selection/v1', created=None)#
Parameters:
Return type:

None

acia.selection.make_source_block(seqfile)[source]#

Build the manifest source block from a SequenceFile.

Bakes in the metadata (pixel size, timing, axes, channels) and a (size, mtime) fingerprint so a moved/changed file can be detected later.

Return type:

dict

acia.selection.save_selection(manifest, directory, *, previews=None)[source]#

Write selection.json (+ optional previews/*.png) into directory.

Parameters:

  • manifest (SelectionManifest) – The manifest to persist.

  • directory (str | PathLike) – Output directory (created if missing) — typically beside the notebook.

  • previews (dict[str, bytes] | None) – Optional mapping of selection id -> PNG bytes written under directory/previews/.

Returns:

The path to the written selection.json.

Return type:

str

acia.selection.load_selection(manifest, source=None)[source]#

Reconstruct lazy cropped sources from a manifest.

Each selection becomes seqfile.position(i).crop_rotated(spec) — a lazy rotated-rectangle view; no pixel data is read here. Calibration comes from the (possibly overriding) source. The returned sources carry .selection and .label attributes so the ROI’s identity is recoverable.

Parameters:

  • manifest (SelectionManifest) – The manifest to reconstruct.

  • source – None to open the manifest’s original file, a path/str to apply the selections to a different file, or an already-open SequenceFile.

Returns:

A list of lazy cropped ImageSequenceSource (one per selection).

Return type:

list

Note

Each selection’s anchor_frame is deliberately ignored here: the crop is taken from the raw source, whose coordinate system is the one the ROI was drawn in, so the spec already applies as-is. It only needs translating once the source has been drift-corrected onto a reference frame – see acia.registration.apply_correction_to_spec().

Raises:

ValueError – If a selection’s position is out of range for the source.

Parameters:

manifest (SelectionManifest)

Return type:

list