spacr.qt.widgets.qc_field_browser

Browse segmentation-QC fields and reversibly quarantine bad arrays.

The Measure banner already has every field verdict in its scorecards. This dialog turns those records into a triage loop: one implicated field at a time, every object-type verdict together, the merged intensities under toggleable mask outlines, and left/right/Q keyboard operation.

Nothing in this dialog touches the filesystem on the GUI thread. Loading, render preparation AND the quarantine move itself all run on workers, and the 400 ms button poll answers out of spacr.qt.path_probe rather than stat-ing – see QCFieldBrowser._file_state for the freeze that bought. No mask is opened merely because the Measure screen itself was shown.

Classes

QCFieldBrowser	Non-modal triage dialog for the flagged fields in one QC digest.
QCFieldImage	Worker-safe display payload for one merged field.
QCFieldTarget	One unique plate/field target and everything QC said about it.
QCFieldVerdict	One object type's persisted verdict for the field on screen.

Functions

finding_targets(→ Tuple[QCFieldTarget, ...])	Return the browser targets belonging to one rendered finding.
load_qc_field(→ QCFieldImage)	Read one target into a bounded display payload; safe on a worker.
render_qc_field() → numpy.ndarray)	Render a uint8 RGB composite with object-type-coloured outlines.
targets_from_digest(→ Tuple[QCFieldTarget, ...])	Return every unique field implicated by a digest, plate-aware.

Module Contents

class spacr.qt.widgets.qc_field_browser.QCFieldBrowser(targets: Sequence[QCFieldTarget], *, initial_field: str = '', initial_plate_root: str = '', run_active: Callable[[], bool] | None = None, threaded: bool = True, parent=None)

Bases: PySide6.QtWidgets.QDialog

Non-modal triage dialog for the flagged fields in one QC digest.

Parameters:

• targets – unique plate/field records from targets_from_digest().

• initial_field – the field whose banner link was activated.

• initial_plate_root – disambiguates identical stems in two plates.

• run_active – callable returning whether Measure is in flight. File mutation is disabled while it returns True.

• threaded – False is a test seam; production image loads are threaded.

• parent – parent widget; ownership only.

Build the browser over a list of fields to triage.

Parameters:

• targets – the fields to review.

• initial_field – which one to open first.

• initial_plate_root – the plate they belong to.

• run_active – whether a run is still writing to them.

• threaded – whether loading and rendering run on workers.

• parent – parent widget.

closeEvent(event) → None

Retire an in-flight image load before Qt destroys the dialog.

Parameters:

event – the close event; passed on to the base class after the timers and image-load workers are stopped.

eventFilter(watched, event) → bool

Watch the widgets this filter is installed on.

Parameters:

• watched – the object the event is for.

• event – the event.

Returns:

True to stop the event going further.

keyPressEvent(event) → None

Keep the triage keys working when the dialog itself has focus.

Parameters:

event – the key press; a triage key (Left and Right to move between fields, or a verdict key such as Q) is handled and accepted, anything else goes to the base class.

next_field() → None

Move to the next implicated field, if one exists.

open_at(field: str, plate_root: str = '') → bool

Reposition an existing browser at a banner-link target.

Parameters:

• field – the field name, without .npy, as held in QCFieldTarget.field.

• plate_root – the plate’s project root, compared as an absolute path; empty matches the first target with that field in any plate.

previous_field() → None

Move to the previous implicated field, if one exists.

toggle_quarantine() → None

Quarantine or restore the current field; also bound to Q.

THE MOVE RUNS ON A WORKER. It did not until 2026-09-04, and that made the whole path_probe gate in _sync_action pointless: the poll in front of this button stopped freezing and the button itself still did, because quarantine_dir_for is a Path.resolve() realpath walk and the rename that follows adds a mkdir, a stat, a link, an fsync-ed ledger write and an unlink – on the plate path the user chose, which is the sleeping autofs share by assumption. See _move_field.

property current_field: str

The current field stem, for tests and external status panels.

property current_target: QCFieldTarget | None

The plate-aware field currently shown, or None.

class spacr.qt.widgets.qc_field_browser.QCFieldImage

Worker-safe display payload for one merged field.

class spacr.qt.widgets.qc_field_browser.QCFieldTarget

One unique plate/field target and everything QC said about it.

Parameters:

• field – the field name, with any .npy suffix removed.

• plate_root – the project root of the plate the field belongs to.

• merged_dir – the folder of merged field arrays, <plate_root>/merged.

• verdicts – each object type’s verdict for this field, sorted by object type.

• reasons – the flags or kinds of the findings that point at this field, as <object_type>:<flag> when the finding names an object type.

• finding_texts – headlines of the findings that point at this field.

property audit_flags: Tuple[str, ...]

Object-qualified flags/reasons written to the quarantine ledger.

class spacr.qt.widgets.qc_field_browser.QCFieldVerdict

One object type’s persisted verdict for the field on screen.

Parameters:

• object_type – the object type the verdict is for, e.g. "cell"; may be empty.

• severity – "ok", "warn" or "fail", as the field’s QC recorded it.

• flags – the flags QC raised for this object type in this field.

• note – QC’s free-text note, or empty.

spacr.qt.widgets.qc_field_browser.finding_targets(digest: Any, finding: Any, targets: Sequence[QCFieldTarget] | None = None) → Tuple[QCFieldTarget, ...]

Return the browser targets belonging to one rendered finding.

Parameters:

• digest – the QC digest (a spacr.seg_qc.QCDigest); its scorecards and findings are read by attribute.

• finding – one finding of that digest; a flag finding matches its exact fields, a positional one every field of its plate and object type.

• targets – the targets to choose from; None builds them with targets_from_digest().

spacr.qt.widgets.qc_field_browser.load_qc_field(target: QCFieldTarget, language: str = 'en') → QCFieldImage

Read one target into a bounded display payload; safe on a worker.

Separate mask stacks are preferred because those are the artifacts the scorecards date. A merged-plane fallback supports plates whose stack folders have since been archived while the self-describing merged array remains.

Parameters:

• target – the field to read; its merged array is looked up in merged_dir (active or quarantined).

• language – UI language code for the error and warning messages.

spacr.qt.widgets.qc_field_browser.render_qc_field(payload: QCFieldImage, channel: int = -1, visible_masks: Iterable[str] = ()) → numpy.ndarray

Render a uint8 RGB composite with object-type-coloured outlines.

Parameters:

• payload – a field loaded by load_qc_field(); one without intensities raises ValueError.

• channel – the channel to show in grey, or -1 for the composite; a channel past the last raises IndexError.

• visible_masks – the object types whose outlines are drawn; a type with no mask, or a mask of the wrong shape, is skipped.

spacr.qt.widgets.qc_field_browser.targets_from_digest(digest: Any) → Tuple[QCFieldTarget, ...]

Return every unique field implicated by a digest, plate-aware.

A field flagged for cell and nucleus appears once with two verdict rows. Positional findings, which have no per-field flag, contribute all fields in their plate/object-type group so the browser does not quietly omit the very pattern the banner asked the user to inspect.

Parameters:

digest – the QC digest (a spacr.seg_qc.QCDigest); its scorecards and findings are read by attribute.