itasc 0.2.0.dev0__py3-none-any.whl

itasc/napari/_stage_loader.py

@@ -0,0 +1,146 @@
+"""Load a pipeline stage's on-disk output(s) into a napari viewer.
+
+The catalog status rail's dots are clickable: clicking a stage's dot loads that
+stage's canonical output(s) for the position into the viewer. This is *per-stage*
+loading (four stages), coarser than the Pipeline Files panel's per-file loading.
+The image-stage targets prefer a committed ``*_labels.tif`` over its working file
+so a finalized position loads its stable output.
+
+Reads are *lazy*: each target is handed to napari as a dask array backed by
+``tifffile``'s zarr store, so clicking a dot builds a per-slice handle instead of
+decoding the whole (often multi-frame) stack on the UI thread. Napari then reads
+only the visible slice as you scrub. This is what keeps the click responsive; a
+full ``imread`` of a long timelapse (× four maps for the cellpose dot) is exactly
+the freeze it avoids. An eager read is the fallback if a file can't be opened as
+a zarr store.
+
+Qt-free: the viewer is used purely by its duck-typed ``layers`` / ``add_labels`` /
+``add_image`` surface, so this is testable with a stub viewer.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from itasc.napari._paths import NucleusArtifactPaths
+from itasc.napari._stage_status import (
+    STAGE_CELL,
+    STAGE_CELL_LABELS,
+    STAGE_CELLPOSE,
+    STAGE_CONTACTS,
+    STAGE_NUCLEUS,
+    STAGE_NUCLEUS_LABELS,
+)
+
+
+@dataclass(frozen=True)
+class LoadTarget:
+    """One file to load, and how to present it."""
+
+    path: Path
+    as_labels: bool
+    colormap: str = "gray"
+
+
+def stage_load_targets(pos_dir: Path | str, stage: str) -> list[LoadTarget]:
+    """Canonical file(s) a stage loads for *pos_dir* (existence not checked here).
+
+    Cellpose loads its divergence maps (foreground → grey, contours → magma) for
+    both channels. Nucleus / Cell load the committed ``*_labels.tif`` when present,
+    else the working stage file, as labels. Contacts has no raw-image output (the
+    ``.h5`` is opened by the Visualize Contacts tool), so it loads nothing.
+    """
+    paths = NucleusArtifactPaths(Path(pos_dir))
+    if stage == STAGE_CELLPOSE:
+        return [
+            LoadTarget(paths.nucleus_foreground, as_labels=False, colormap="gray"),
+            LoadTarget(paths.nucleus_contours, as_labels=False, colormap="magma"),
+            LoadTarget(paths.cell_foreground, as_labels=False, colormap="gray"),
+            LoadTarget(paths.cell_contours, as_labels=False, colormap="magma"),
+        ]
+    if stage == STAGE_NUCLEUS:
+        committed = paths.nucleus_labels
+        chosen = committed if committed.is_file() else paths.tracked
+        return [LoadTarget(chosen, as_labels=True)]
+    if stage == STAGE_CELL:
+        committed = paths.cell_labels
+        chosen = committed if committed.is_file() else paths.cell_tracked
+        return [LoadTarget(chosen, as_labels=True)]
+    # The contact-analysis-only app's label stages load the committed label
+    # images directly (they are its inputs, not a working/committed pair).
+    if stage == STAGE_CELL_LABELS:
+        return [LoadTarget(paths.cell_labels, as_labels=True)]
+    if stage == STAGE_NUCLEUS_LABELS:
+        return [LoadTarget(paths.nucleus_labels, as_labels=True)]
+    if stage == STAGE_CONTACTS:
+        return []
+    return []
+
+
+def _layer_name(pos_dir: Path, path: Path) -> str:
+    """A per-position layer name so two positions' files don't collide."""
+    return f"{Path(pos_dir).name}:{path.stem}"
+
+
+def _read_lazy(path: Path):
+    """A lazy, per-slice-backed array for *path*.
+
+    Uses ``tifffile``'s zarr store wrapped in a dask array so adding a layer
+    doesn't decode the whole stack up front — napari materializes only the
+    slices it displays. Falls back to an eager ``imread`` if the file can't be
+    opened as a zarr store (e.g. an exotic layout aszarr won't handle).
+    """
+    import tifffile
+
+    try:
+        import dask.array as da
+
+        return da.from_zarr(tifffile.imread(str(path), aszarr=True))
+    except Exception:
+        return tifffile.imread(str(path))
+
+
+def _select(viewer, name: str) -> None:
+    """Make *name* the active/visible layer so a dot click has visible effect.
+
+    Guarded: a duck-typed stub viewer without a selection surface is a no-op.
+    """
+    try:
+        layer = viewer.layers[name]
+        layer.visible = True
+        viewer.layers.selection.active = layer
+    except Exception:
+        pass
+
+
+def load_stage(viewer, pos_dir: Path | str | None, stage: str) -> list[str]:
+    """Load *stage*'s existing outputs for *pos_dir* into *viewer*.
+
+    Returns the layer names loaded (empty when the position has no canonical root,
+    no viewer, or nothing on disk yet). An already-present layer of the same name
+    has its data replaced rather than duplicated.
+    """
+    if viewer is None or pos_dir is None:
+        return []
+
+    loaded: list[str] = []
+    for target in stage_load_targets(pos_dir, stage):
+        if not target.path.is_file():
+            continue
+        name = _layer_name(Path(pos_dir), target.path)
+        if name in viewer.layers:
+            try:
+                viewer.layers[name].data = _read_lazy(target.path)
+                _select(viewer, name)
+                loaded.append(name)
+                continue
+            except Exception:
+                viewer.layers.remove(viewer.layers[name])
+        data = _read_lazy(target.path)
+        if target.as_labels:
+            viewer.add_labels(data, name=name)
+        else:
+            viewer.add_image(data, name=name, colormap=target.colormap)
+        _select(viewer, name)
+        loaded.append(name)
+    return loaded

itasc/napari/_stage_status.py

@@ -0,0 +1,110 @@
+"""Qt-free per-position pipeline status — the source the catalog rail reads.
+
+A position moves through four human-in-the-loop stages (Cellpose → Ultrack
+nucleus tracking → cell workflow → contact analysis). :func:`position_stage_status`
+reports how far one position has progressed by header-only file existence + mtime
+checks (no pixel decode), mirroring the on-disk done-signals:
+
+* **cellpose** (2-state) — the nucleus divergence maps
+  (``1_cellpose/nucleus_foreground.tif`` + ``_contours.tif``) exist.
+* **nucleus** / **cell** (3-state) — the working-vs-committed split from the P2
+  commit contract (:func:`itasc.core.commit.commit_state`): a working file in
+  the numbered stage dir, optionally promoted to the base-folder ``*_labels.tif``.
+* **contacts** (2-state) — the contact-analysis ``.h5`` exists.
+
+The widget layer calls this per row on refresh and maps the returned states onto
+dot rendering. A row with no canonical position root (a hand-authored catalog CSV
+pointing at scattered paths) passes ``None`` and gets ``unknown`` for every stage.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from itasc.contact_analysis.catalog import CONTACT_ANALYSIS_RELPATH
+from itasc.core.commit import commit_state
+from itasc.napari._paths import NucleusArtifactPaths
+
+# Stage keys, ordered left→right as the rail renders them.
+STAGE_CELLPOSE = "cellpose"
+STAGE_NUCLEUS = "nucleus"
+STAGE_CELL = "cell"
+STAGE_CONTACTS = "contacts"
+STAGES: tuple[str, ...] = (STAGE_CELLPOSE, STAGE_NUCLEUS, STAGE_CELL, STAGE_CONTACTS)
+
+# The contact-analysis-only vocabulary (the standalone ``itasc-aggregate`` app,
+# which does not run segmentation/tracking). Here the committed label images are
+# *inputs*, not stages this app produces, so the rail reports only their presence:
+# cell labels → nucleus labels → contact analysis.
+STAGE_CELL_LABELS = "cell_labels"
+STAGE_NUCLEUS_LABELS = "nucleus_labels"
+CONTACT_STAGES: tuple[str, ...] = (
+    STAGE_CELL_LABELS,
+    STAGE_NUCLEUS_LABELS,
+    STAGE_CONTACTS,
+)
+
+# State vocabulary. The widget maps each onto a dot glyph:
+MISSING = "missing"  # empty ring — nothing on disk yet
+WORKING = "working"  # hollow — working file present, not committed (3-state only)
+DONE = "done"        # filled — final artifact present
+STALE = "stale"      # committed, but the working file is newer (3-state only)
+UNKNOWN = "unknown"  # grey — no canonical position root to derive from
+
+# commit_state's vocabulary → the rail's.
+_COMMIT_TO_STATE: dict[str, str] = {
+    "missing": MISSING,
+    "uncommitted": WORKING,
+    "committed": DONE,
+    "stale": STALE,
+}
+
+
+def position_stage_status(pos_dir: Path | str | None) -> dict[str, str]:
+    """Return each pipeline stage's status for one canonical position directory.
+
+    ``pos_dir`` of ``None`` yields ``unknown`` for every stage (a hand-authored
+    catalog row with no canonical root). See the module docstring for the
+    per-stage done-signals and the state vocabulary.
+    """
+    if pos_dir is None:
+        return {stage: UNKNOWN for stage in STAGES}
+
+    paths = NucleusArtifactPaths(Path(pos_dir))
+    cellpose = (
+        DONE
+        if paths.nucleus_foreground.is_file() and paths.nucleus_contours.is_file()
+        else MISSING
+    )
+    nucleus = _COMMIT_TO_STATE[commit_state(paths.tracked, paths.nucleus_labels)]
+    cell = _COMMIT_TO_STATE[commit_state(paths.cell_tracked, paths.cell_labels)]
+    contacts = DONE if (paths.pos_dir / CONTACT_ANALYSIS_RELPATH).is_file() else MISSING
+
+    return {
+        STAGE_CELLPOSE: cellpose,
+        STAGE_NUCLEUS: nucleus,
+        STAGE_CELL: cell,
+        STAGE_CONTACTS: contacts,
+    }
+
+
+def position_contact_status(pos_dir: Path | str | None) -> dict[str, str]:
+    """Return the contact-analysis-only stage status for one position directory.
+
+    The standalone aggregate app does not run segmentation/tracking: it consumes
+    the committed ``cell_labels.tif`` (required) and ``nucleus_labels.tif``
+    (optional) as *inputs* and produces the contact-analysis ``.h5``. Each of the
+    three :data:`CONTACT_STAGES` is therefore a plain present/missing check (no
+    working-vs-committed split). ``pos_dir`` of ``None`` yields ``unknown`` for
+    every stage (a hand-authored catalog row with no canonical root).
+    """
+    if pos_dir is None:
+        return {stage: UNKNOWN for stage in CONTACT_STAGES}
+
+    paths = NucleusArtifactPaths(Path(pos_dir))
+    return {
+        STAGE_CELL_LABELS: DONE if paths.cell_labels.is_file() else MISSING,
+        STAGE_NUCLEUS_LABELS: DONE if paths.nucleus_labels.is_file() else MISSING,
+        STAGE_CONTACTS: (
+            DONE if (paths.pos_dir / CONTACT_ANALYSIS_RELPATH).is_file() else MISSING
+        ),
+    }

itasc/napari/_standalone_paths.py

@@ -0,0 +1,89 @@
+"""Shared input/output path-picker scaffolding for standalone napari pieces.
+
+The independently-installable ITASC pieces (``itasc-tracking``,
+``itasc-segmentation``) each expose a standalone seam: when run without the
+orchestrator they show their own labeled file/dir pickers instead of being
+driven through ``refresh(pos_dir)``. This mixin holds the parts that are
+identical across those seams — the labeled line-edit + *Browse* row builder, the
+file/dir browse handlers, and QSettings persistence — leaving each piece to
+declare its own fields and implement its piece-specific "apply these paths to my
+workspace" step.
+
+Ships in ``itasc-core`` (qtpy-only, no ITASC dependencies) so both the
+tracking and segmentation distributions compose on it.
+"""
+from __future__ import annotations
+
+from qtpy.QtCore import QSettings
+from qtpy.QtWidgets import (
+    QFileDialog,
+    QHBoxLayout,
+    QLabel,
+    QLineEdit,
+    QPushButton,
+    QVBoxLayout,
+)
+
+#: Default file filter for the image inputs the pieces consume.
+IMAGE_FILTER = "Images (*.tif *.tiff);;All files (*)"
+
+
+class StandalonePathsMixin:
+    """Reusable path-picker helpers for a standalone workflow widget.
+
+    Mixed into a ``QWidget`` subclass: ``self`` is the dialog parent.
+    """
+
+    def _add_path_row(
+        self,
+        column: QVBoxLayout,
+        label: str,
+        placeholder: str,
+        on_browse,
+        on_edited,
+    ) -> QLineEdit:
+        """Build a ``[label] [line edit] [Browse…]`` row and return the edit."""
+        row = QHBoxLayout()
+        row.setContentsMargins(0, 0, 0, 0)
+        lbl = QLabel(label)
+        lbl.setMinimumWidth(80)
+        row.addWidget(lbl)
+        edit = QLineEdit()
+        edit.setPlaceholderText(placeholder)
+        edit.editingFinished.connect(on_edited)
+        row.addWidget(edit, 1)
+        browse_btn = QPushButton("Browse…")
+        browse_btn.clicked.connect(on_browse)
+        row.addWidget(browse_btn)
+        column.addLayout(row)
+        return edit
+
+    def _browse_file_into(
+        self, edit: QLineEdit, title: str, on_done, *, file_filter: str = IMAGE_FILTER
+    ) -> None:
+        """Pick a file into ``edit`` and run ``on_done`` if one was chosen."""
+        path, _ = QFileDialog.getOpenFileName(self, title, filter=file_filter)
+        if path:
+            edit.setText(path)
+            on_done()
+
+    def _browse_dir_into(self, edit: QLineEdit, title: str, on_done) -> None:
+        """Pick a directory into ``edit`` and run ``on_done`` if one was chosen."""
+        path = QFileDialog.getExistingDirectory(self, title)
+        if path:
+            edit.setText(path)
+            on_done()
+
+    def _load_path_settings(self, app: str, fields: dict[str, QLineEdit]) -> None:
+        """Populate ``fields`` (key → edit) from ``QSettings('itasc', app)``."""
+        s = QSettings("itasc", app)
+        for key, edit in fields.items():
+            value = s.value(key, "", type=str)
+            if value:
+                edit.setText(value)
+
+    def _save_path_settings(self, app: str, fields: dict[str, QLineEdit]) -> None:
+        """Persist ``fields`` (key → edit) into ``QSettings('itasc', app)``."""
+        s = QSettings("itasc", app)
+        for key, edit in fields.items():
+            s.setValue(key, edit.text().strip())

itasc/napari/_state.py

@@ -0,0 +1,146 @@
+"""Serialize/restore nucleus-workflow widget control values.
+
+Pure helpers: ``dump_state`` reads spinbox/checkbox/combo values into a dict,
+``load_state`` writes them back. Each key is guarded so older snapshots that
+predate newer controls still load cleanly.
+
+The dict layout is part of the public state contract — main_widget persists
+it across sessions and tests round-trip it. Keep keys stable; add, don't
+rename.
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from itasc.napari.nucleus_workflow_widget import NucleusWorkflowWidget
+
+
+def dump_state(w: NucleusWorkflowWidget) -> dict:
+    return {
+        "db_generation": {
+            "min_area": w.db_gen_min_area_spin.value(),
+            "max_area": w.db_gen_max_area_spin.value(),
+            "min_frontier": w.db_gen_min_frontier_spin.value(),
+            "ws_hierarchy": w.db_gen_ws_hierarchy_combo.currentText(),
+            "n_workers": w.db_gen_n_workers_spin.value(),
+            "atom_union_max_area": w.atom_union_max_area_spin.value(),
+            "overlap_budget": w.atom_overlap_budget_spin.value(),
+            "max_distance": w.db_gen_max_dist_spin.value(),
+            "max_neighbors": w.db_gen_max_neighbors_spin.value(),
+            "linking_mode": w.db_gen_linking_mode_combo.currentText(),
+            "area_weight": w.db_gen_area_weight_spin.value(),
+            "iou_weight": w.db_gen_iou_weight_spin.value(),
+            "distance_weight": w.db_gen_distance_weight_spin.value(),
+            "quality_weight": w.db_gen_quality_weight_spin.value(),
+            "quality_exponent": w.db_gen_quality_exp_spin.value(),
+            "circularity_weight": w.db_gen_circularity_weight_spin.value(),
+        },
+        "extend": {
+            "area_weight": w.extend_area_weight_spin.value(),
+            "iou_weight": w.extend_iou_weight_spin.value(),
+            "distance_weight": w.extend_distance_weight_spin.value(),
+            "greedy_overwrite": w.extend_greedy_overwrite_check.isChecked(),
+        },
+        "ultrack": {
+            "max_partitions": w.ultrack_max_partitions_spin.value(),
+            "n_frames": w.ultrack_n_frames_spin.value(),
+            "appear_weight": w.ultrack_appear_spin.value(),
+            "disappear_weight": w.ultrack_disappear_spin.value(),
+            "division_weight": w.ultrack_division_spin.value(),
+            "power": w.ultrack_power_spin.value(),
+            "bias": w.ultrack_bias_spin.value(),
+        },
+        "atom_extraction": {
+            "fg_window": w.atom_extraction_widget.fg_window_spin.value(),
+            "fg_cutoff": w.atom_extraction_widget.fg_cutoff_spin.value(),
+            "fg_strength": w.atom_extraction_widget.fg_strength_spin.value(),
+            "contour_window": w.atom_extraction_widget.contour_window_spin.value(),
+            "contour_floor": w.atom_extraction_widget.contour_floor_spin.value(),
+            "contour_strength": w.atom_extraction_widget.contour_strength_spin.value(),
+            "atom_min_area": w.atom_extraction_widget.atom_min_area_spin.value(),
+        },
+        "correction": {
+            "retrack_max_distance": w.retrack_max_dist_spin.value(),
+            "show_track_path": w.nucleus_correction_widget.track_path_btn.isChecked(),
+            "show_spotlight": w.nucleus_correction_widget.spotlight_btn.isChecked(),
+        },
+    }
+
+
+def _set_combo(combo, text: str) -> None:
+    idx = combo.findText(text)
+    if idx >= 0:
+        combo.setCurrentIndex(idx)
+
+
+def load_state(w: NucleusWorkflowWidget, state: dict) -> None:
+    if not isinstance(state, dict):
+        return
+    if "db_generation" in state:
+        dbg = state["db_generation"]
+        if "min_area" in dbg: w.db_gen_min_area_spin.setValue(dbg["min_area"])
+        if "max_area" in dbg: w.db_gen_max_area_spin.setValue(dbg["max_area"])
+        if "min_frontier" in dbg: w.db_gen_min_frontier_spin.setValue(dbg["min_frontier"])
+        if "ws_hierarchy" in dbg: _set_combo(w.db_gen_ws_hierarchy_combo, dbg["ws_hierarchy"])
+        if "n_workers" in dbg: w.db_gen_n_workers_spin.setValue(dbg["n_workers"])
+        if "atom_union_max_area" in dbg: w.atom_union_max_area_spin.setValue(dbg["atom_union_max_area"])
+        if "overlap_budget" in dbg: w.atom_overlap_budget_spin.setValue(dbg["overlap_budget"])
+        # "max_atoms" (removed) in older snapshots is intentionally ignored.
+        if "max_distance" in dbg: w.db_gen_max_dist_spin.setValue(dbg["max_distance"])
+        if "max_neighbors" in dbg: w.db_gen_max_neighbors_spin.setValue(dbg["max_neighbors"])
+        if "linking_mode" in dbg: _set_combo(w.db_gen_linking_mode_combo, dbg["linking_mode"])
+        if "area_weight" in dbg: w.db_gen_area_weight_spin.setValue(dbg["area_weight"])
+        if "iou_weight" in dbg: w.db_gen_iou_weight_spin.setValue(dbg["iou_weight"])
+        if "distance_weight" in dbg: w.db_gen_distance_weight_spin.setValue(dbg["distance_weight"])
+        if "quality_weight" in dbg: w.db_gen_quality_weight_spin.setValue(dbg["quality_weight"])
+        if "quality_exponent" in dbg: w.db_gen_quality_exp_spin.setValue(dbg["quality_exponent"])
+        if "circularity_weight" in dbg: w.db_gen_circularity_weight_spin.setValue(dbg["circularity_weight"])
+    if "extend" in state:
+        ext = state["extend"]
+        if "area_weight" in ext: w.extend_area_weight_spin.setValue(ext["area_weight"])
+        if "iou_weight" in ext: w.extend_iou_weight_spin.setValue(ext["iou_weight"])
+        if "distance_weight" in ext: w.extend_distance_weight_spin.setValue(ext["distance_weight"])
+        if "greedy_overwrite" in ext: w.extend_greedy_overwrite_check.setChecked(ext["greedy_overwrite"])
+    if "ultrack" in state:
+        ul = state["ultrack"]
+        dbg_present = "db_generation" in state
+        if "min_area" in ul and not (dbg_present and "min_area" in state["db_generation"]):
+            w.db_gen_min_area_spin.setValue(ul["min_area"])
+        if "max_partitions" in ul: w.ultrack_max_partitions_spin.setValue(ul["max_partitions"])
+        if "n_frames" in ul: w.ultrack_n_frames_spin.setValue(ul["n_frames"])
+        if "max_distance" in ul and not (dbg_present and "max_distance" in state["db_generation"]):
+            w.db_gen_max_dist_spin.setValue(ul["max_distance"])
+        if "linking_mode" in ul and not (dbg_present and "linking_mode" in state["db_generation"]):
+            _set_combo(w.db_gen_linking_mode_combo, ul["linking_mode"])
+        if "iou_weight" in ul and not (dbg_present and "iou_weight" in state["db_generation"]):
+            w.db_gen_iou_weight_spin.setValue(ul["iou_weight"])
+        if "area_weight" in ul and not (dbg_present and "area_weight" in state["db_generation"]):
+            w.db_gen_area_weight_spin.setValue(ul["area_weight"])
+        if "distance_weight" in ul and not (dbg_present and "distance_weight" in state["db_generation"]):
+            w.db_gen_distance_weight_spin.setValue(ul["distance_weight"])
+        if "appear_weight" in ul: w.ultrack_appear_spin.setValue(ul["appear_weight"])
+        if "disappear_weight" in ul: w.ultrack_disappear_spin.setValue(ul["disappear_weight"])
+        if "division_weight" in ul: w.ultrack_division_spin.setValue(ul["division_weight"])
+        if "max_neighbors" in ul and not (dbg_present and "max_neighbors" in state["db_generation"]):
+            w.db_gen_max_neighbors_spin.setValue(ul["max_neighbors"])
+        if "power" in ul: w.ultrack_power_spin.setValue(ul["power"])
+        if "bias" in ul: w.ultrack_bias_spin.setValue(ul["bias"])
+        if "quality_exponent" in ul and not (dbg_present and "quality_exponent" in state["db_generation"]):
+            w.db_gen_quality_exp_spin.setValue(ul["quality_exponent"])
+    if "atom_extraction" in state:
+        ae = state["atom_extraction"]
+        aw = w.atom_extraction_widget
+        if "fg_window" in ae: aw.fg_window_spin.setValue(ae["fg_window"])
+        if "fg_cutoff" in ae: aw.fg_cutoff_spin.setValue(ae["fg_cutoff"])
+        if "fg_strength" in ae: aw.fg_strength_spin.setValue(ae["fg_strength"])
+        if "contour_window" in ae: aw.contour_window_spin.setValue(ae["contour_window"])
+        if "contour_floor" in ae: aw.contour_floor_spin.setValue(ae["contour_floor"])
+        if "contour_strength" in ae: aw.contour_strength_spin.setValue(ae["contour_strength"])
+        if "atom_min_area" in ae: aw.atom_min_area_spin.setValue(ae["atom_min_area"])
+    if "correction" in state:
+        cor = state["correction"]
+        cw = w.nucleus_correction_widget
+        if "retrack_max_distance" in cor: w.retrack_max_dist_spin.setValue(cor["retrack_max_distance"])
+        if "show_track_path" in cor: cw.track_path_btn.setChecked(cor["show_track_path"])
+        if "show_spotlight" in cor: cw.spotlight_btn.setChecked(cor["show_spotlight"])

itasc/napari/_status_rail.py

@@ -0,0 +1,128 @@
+"""The per-position status rail: one dot per pipeline stage.
+
+Each :class:`StatusDot` renders one stage's :mod:`itasc.napari._stage_status`
+state as a small coloured circle with a plain-language tooltip; :class:`StatusRail`
+lays them out left→right and repaints them from a status dict on refresh. The
+stage set is configurable: the full app passes the four-stage default
+(Cellpose → Nucleus → Cell → Contacts); the standalone aggregate app passes the
+three-stage :data:`~itasc.napari._stage_status.CONTACT_STAGES`
+(cell labels → nucleus labels → contact analysis). Rendering only.
+"""
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from qtpy.QtCore import Qt, Signal
+from qtpy.QtWidgets import QHBoxLayout, QLabel, QWidget
+
+from itasc.napari._stage_status import (
+    DONE,
+    MISSING,
+    STAGE_CELL,
+    STAGE_CELL_LABELS,
+    STAGE_CELLPOSE,
+    STAGE_CONTACTS,
+    STAGE_NUCLEUS,
+    STAGE_NUCLEUS_LABELS,
+    STAGES,
+    STALE,
+    UNKNOWN,
+    WORKING,
+)
+
+#: Human-facing stage names for tooltips.
+_STAGE_LABELS: dict[str, str] = {
+    STAGE_CELLPOSE: "Cellpose",
+    STAGE_NUCLEUS: "Nucleus tracking",
+    STAGE_CELL: "Cell workflow",
+    STAGE_CONTACTS: "Contact analysis",
+    STAGE_CELL_LABELS: "Cell labels",
+    STAGE_NUCLEUS_LABELS: "Nucleus labels",
+}
+
+#: Human-facing state names for tooltips.
+_STATE_LABELS: dict[str, str] = {
+    MISSING: "not started",
+    WORKING: "working (uncommitted)",
+    DONE: "done",
+    STALE: "stale (re-run since commit)",
+    UNKNOWN: "unknown",
+}
+
+#: state → (fill, border) colours. ``MISSING`` is a hollow ring; the rest fill.
+#: Chosen to read on napari's dark theme.
+_STATE_COLOURS: dict[str, tuple[str, str]] = {
+    MISSING: ("transparent", "#7a7a7a"),
+    WORKING: ("#e0a020", "#a8791a"),  # amber — working, not committed
+    DONE: ("#3aa84a", "#2c7d38"),     # green — committed / present
+    STALE: ("#d9534f", "#a83836"),    # red — committed but stale
+    UNKNOWN: ("#5a5a5a", "#4a4a4a"),  # muted grey — no canonical root
+}
+
+_DOT_PX = 12
+
+
+class StatusDot(QLabel):
+    """One stage's status, drawn as a small coloured circle.
+
+    Clicking the dot emits :attr:`clicked` with the stage name — the catalog wires
+    this to load that stage's output into the viewer.
+    """
+
+    clicked = Signal(str)  # stage name
+
+    def __init__(self, stage: str, parent: QWidget | None = None) -> None:
+        super().__init__(parent)
+        self.stage = stage
+        self.state = UNKNOWN
+        self.setFixedSize(_DOT_PX, _DOT_PX)
+        self.setCursor(Qt.PointingHandCursor)
+        self.set_state(UNKNOWN)
+
+    def mousePressEvent(self, event) -> None:
+        # Consume the event (do not fall through to row selection) and load.
+        self.clicked.emit(self.stage)
+        event.accept()
+
+    def set_state(self, state: str) -> None:
+        self.state = state
+        fill, border = _STATE_COLOURS.get(state, _STATE_COLOURS[UNKNOWN])
+        radius = _DOT_PX // 2
+        self.setStyleSheet(
+            f"background-color: {fill}; border: 1px solid {border}; "
+            f"border-radius: {radius}px;"
+        )
+        stage_label = _STAGE_LABELS.get(self.stage, self.stage)
+        state_label = _STATE_LABELS.get(state, state)
+        self.setToolTip(f"{stage_label}: {state_label}")
+
+
+class StatusRail(QWidget):
+    """One :class:`StatusDot` per stage in *stages*, in the given order.
+
+    Defaults to the four-stage pipeline :data:`STAGES`; pass an explicit stage
+    list (e.g. :data:`CONTACT_STAGES`) for a different app's rail.
+    :attr:`dotClicked` re-emits any dot's click with its stage name.
+    """
+
+    dotClicked = Signal(str)  # stage name
+
+    def __init__(
+        self,
+        stages: Sequence[str] = STAGES,
+        parent: QWidget | None = None,
+    ) -> None:
+        super().__init__(parent)
+        layout = QHBoxLayout(self)
+        layout.setContentsMargins(0, 0, 0, 0)
+        layout.setSpacing(3)
+        self.dots: list[StatusDot] = [StatusDot(stage) for stage in stages]
+        for dot in self.dots:
+            dot.clicked.connect(self.dotClicked)
+            layout.addWidget(dot)
+        layout.addStretch(1)
+
+    def set_status(self, status: dict[str, str]) -> None:
+        """Repaint every dot; stages absent from *status* render as ``unknown``."""
+        for dot in self.dots:
+            dot.set_state(status.get(dot.stage, UNKNOWN))