spacr.external_masks

Workflow inputs and outputs

External Masks

Assign corresponding images and existing integer label masks, then create and measure a spaCR project without rerunning segmentation.

Open: Import → External Masks.

Inputs and outputs below include conditional alternatives. The guidance and handoff notes say which route applies.

Inputs

• Microscope images — Source image folder; original files, supported vendor files or imported TIFFs.

• Label masks — masks/ when retained, or explicitly saved image/mask pairs. Intermediate masks may be removed by cleanup.

Outputs

• Images and label masks — merged/*.npy in the project; channels and integer label planes share each field array.

• Measured objects — measurements/measurements.db; object tables depend on the enabled cell, nucleus, pathogen and organelle masks. Relevant tables, depending on the route: cell, nucleus, pathogen, cytoplasm. Relevant columns, depending on the route: plateID, rowID, columnID, fieldID.

• Object crops — data/**/*_png when save_png is enabled; png_list indexes saved crops. Supported workflows can instead stream crops from merged arrays and masks. Relevant tables, depending on the route: png_list. Relevant columns, depending on the route: png_path, prcfo.

Before this module

• Direct Cellpose mask generation: Provide the saved label TIFFs and their original images to External Masks, assign object roles and create the merged project before Measure.

After this module

• Measure: Re-measure only when needed; External Masks can already perform measurement.

• Annotate: Keep the newly measured project and crop index together.

API reference.

Module tutorial.

Import externally generated masks and finish a spaCR Measure project.

This is the entry point for segmentation performed outside spaCR. It accepts one or more mixed folders/files, detects intensity images and label images, lets callers override every proposed role/object type, builds the canonical stack/, masks/ and merged/ folders, and then delegates all feature extraction and crop generation to spacr.measure.measure_crop().

The output is therefore the same contract Annotate expects from Measure:

destination/
  data/.../<object>_png/*.png
  images/*.tif
  stack/*.npy
  masks/<object>_mask_stack/*.npy
  merged/*.npy
  measurements/measurements.db

Only object types supplied by the user are measured. cytoplasm is derived by Measure from a cell mask and any supplied interior masks; it is not an input mask plane.

Classes

ExternalMaskPlan	Read-only preview of an external-mask import.
ExternalMaskResult	Files and database produced by prepare_external_masks().
InputGroup	A set of files sharing one proposed role and object type.
MaskMatch	One label-mask file matched to an intensity-image field.

Functions

default_settings(→ Dict[str, Any])	Return importer settings plus the complete Measure setting contract.
detect_inputs(→ List[InputGroup])	Detect image and mask groups without writing anything.
plan_external_masks(→ ExternalMaskPlan)	Validate and preview an external image/mask import without writing.
prepare_external_masks(→ Any)	Plan an external-mask import, print the preview, and run it.
register_settings(→ bool)	Publish this module's settings help through the shared registry.
run_external_masks(→ ExternalMaskResult)	Materialize plan and call the standard Measure pipeline.

Module Contents

class spacr.external_masks.ExternalMaskPlan

Read-only preview of an external-mask import.

Parameters:

• groups – normalized image, mask, and ignored input groups reviewed for this import.

• images – proposed intensity-image conversion plan.

• masks – spaCR object types mapped to canonical field stems and their matched label-mask files.

• destination – root of the spaCR project that would be written.

• n_channels – number of intensity-image channels in each generated merged field.

• mask_dims – merged-array plane index assigned to each supplied mask type.

• errors – blocking problems that make the preview unrunnable.

• warnings – non-blocking ambiguities shown before the import proceeds.

summary() → str

Return a multiline read-only preview of mappings and problems.

property object_types: List[str]

Return supplied mask roles in canonical object-type order.

property ok: bool

Return whether images, shared fields, and importer checks are valid.

property stems: List[str]

Return sorted field stems covered by every supplied mask type.

class spacr.external_masks.ExternalMaskResult

Files and database produced by prepare_external_masks().

Parameters:

• destination – root of the generated spaCR project.

• merged – paths of generated merged image-and-mask arrays.

• db_path – path of the generated measurements database.

• tables – measurement-table names written to that database.

• data_dir – generated annotation-crop directory.

• plan – validated read-only import plan used to produce these outputs.

summary() → str

Return one line naming materialized fields and output locations.

class spacr.external_masks.InputGroup

A set of files sharing one proposed role and object type.

Parameters:

• key – stable identifier derived from the input root, proposed role, and detected file family.

• root – absolute directory from which the files were detected and later scanned.

• paths – absolute paths assigned to this group.

• role – reviewed "image", "mask", or "ignore" role.

• object_type – proposed spaCR object type for a mask group, or None when no mask type is assigned.

• confidence – confidence score for the automatic role proposal; detected multi-file groups retain their lowest member score.

• reason – pixel or filename evidence supporting the automatic proposal.

classmethod from_value(value: Any) → InputGroup

Normalize a group instance or serialized mapping.

Parameters:

value – existing InputGroup or mapping carrying its serialized fields.

to_dict() → Dict[str, Any]

Return every group field as a recursively copied plain mapping.

class spacr.external_masks.MaskMatch

One label-mask file matched to an intensity-image field.

Parameters:

• path – absolute path of the matched source label-mask file; the importer reads this file and reports it in validation errors.

• object_type – valid spaCR object role assigned to the mask group, such as cell or nucleus.

• stem – canonical <plate>_<well>_<field> stem of the intensity field to which the mask was paired.

• match – pairing rule that succeeded, currently "exact" or "normalised" after stripping mask/object-role suffixes.

spacr.external_masks.default_settings(settings: Mapping[str, Any] | None = None) → Dict[str, Any]

Return importer settings plus the complete Measure setting contract.

spacr.external_masks.detect_inputs(paths: Sequence[Any], *, recursive: bool = True) → List[InputGroup]

Detect image and mask groups without writing anything.

Parameters:

paths – input files or directories to inspect and group.

Filename evidence wins when a path explicitly says mask/labels. Otherwise a bounded pixel sample distinguishes compact integer label planes from intensity images. Every result remains editable in the GUI.

spacr.external_masks.plan_external_masks(settings: Mapping[str, Any] | None = None) → ExternalMaskPlan

Validate and preview an external image/mask import without writing.

Parameters:

settings – Partial settings mapping accepted by default_settings().

Returns:

Pairing plan containing canonical image mappings, per-object mask matches, warnings, and blocking errors.

spacr.external_masks.prepare_external_masks(settings: Mapping[str, Any] | None = None) → Any

Plan an external-mask import, print the preview, and run it.

The plan summary is always printed to stdout. Unless preview_only is set, the project is written and Measure is run, and the result summary is printed too.

Parameters:

settings – Partial settings mapping accepted by default_settings().

Returns:

The ExternalMaskPlan when preview_only is set, otherwise the ExternalMaskResult from run_external_masks().

spacr.external_masks.register_settings(replace: bool = False) → bool

Publish this module’s settings help through the shared registry.

External Masks predates the module-registration seam, so its seven importer-specific controls were the only displayed settings in the app registry without authored help. Registering beside the defaults keeps the inventory, validation types, and tooltip prose together; the Measure settings returned by default_settings() retain their existing shared declarations.

Parameters:

replace – replace this module’s existing defaults registration.

Returns:

whether a new registration was made.

spacr.external_masks.run_external_masks(plan: ExternalMaskPlan, settings: Mapping[str, Any] | None = None) → ExternalMaskResult

Materialize plan and call the standard Measure pipeline.

Parameters:

• plan – Validated plan from plan_external_masks(), whose ok property must be True.

• settings – Partial settings mapping accepted by default_settings(); it carries the full Measure contract and supplies overwrite for the intensity conversion and channels, png_dims, crop_mode and cytoplasm for the Measure call.

Returns:

Result describing the written project, its merged arrays, measurements database and tables, and the plan used.

Raises:

ConfigurationError – If the plan is not ok, if a field’s channel count, shapes, dtypes or label IDs violate the Measure uint16 contract, or if Measure finishes without a required table.