spacr.qt.secondary_masks

Pair a read-only primary mask with one editable secondary-mask field.

Folder sources match the image’s stem. Explicit files are bound to one image so moving through a queue cannot accidentally reuse yesterday’s nuclei on a same-sized new field. The immutable snapshot records class names and the source checksum; neither loading nor validation writes a primary mask.

Classes

PrimaryMaskSource

A validated primary mask and the field and object classes it belongs to.

Functions

read_primary_source(source, image_path, shape, ...[, ...])

Load a field's primary labels without modifying either mask file.

Module Contents

class spacr.qt.secondary_masks.PrimaryMaskSource

A validated primary mask and the field and object classes it belongs to.

Parameters:

• path – resolved source-mask path.

• image_path – resolved image path identifying this field.

• primary_class – primary object class, for example nucleus.

• secondary_class – distinct output object class, for example cell.

• sha256 – checksum of the source file actually read.

• labels – owned, read-only uint16 primary labels matching the image.

crop(box)

Copy primary labels inside a rectangle for a worker request.

Parameters:

box – (x0,y0,x1,y1) pixel bounds, with exclusive upper bounds.

Returns:

independent label array preserving the source object IDs.

Raises:

ValueError – the rectangle is empty or extends outside the image.

provenance()

Return JSON-safe source identity for the mask’s curation ledger.

validate_destination(path)

Refuse any output that would overwrite the primary, including aliases.

Parameters:

path – proposed secondary-mask destination, as a string or path.

Raises:

ValueError – the destination is the primary file, a symbolic link to it or an existing hard link to it.

property identity

Hashable field/source/class token for asynchronous request keys.

spacr.qt.secondary_masks.read_primary_source(source, image_path, shape, output_path, *, primary_class='nucleus', secondary_class='cell', bound_image=None)

Load a field’s primary labels without modifying either mask file.

Parameters:

• source – one TIFF/PNG/NPY/Cellpose bundle or a folder containing a matching <image stem> mask. Multiple matching files are refused.

• image_path – image currently being edited; field identity is its path.

• shape – expected (height,width) of the primary mask.

• output_path – destination of the editable secondary mask. Must not alias the primary through a path, symbolic link or hard link.

• primary_class – nonempty name of the source object class.

• secondary_class – distinct nonempty name of the output class.

• bound_image – field for which an explicit file was chosen. Required for file sources; ignored for folders that resolve each field by name.

Returns:

immutable PrimaryMaskSource with read-only uint16 labels.

Raises:

• ValueError – ambiguous/missing pairing, incompatible classes, shape, labels, field binding, output alias or a source changed during reading.

• OSError – an input cannot be read.