itasc 0.2.0.dev0__py3-none-any.whl

itasc/napari/_flow_layout.py

@@ -0,0 +1,98 @@
+"""A wrapping flow layout — lays items left→right and wraps to new rows.
+
+Qt ships no wrapping layout out of the box; this is the canonical
+``heightForWidth`` flow layout (per the Qt examples) trimmed to what the
+correction workspace needs. Used to stack candidate thumbnails into rows that
+reflow as the strip is resized.
+"""
+from __future__ import annotations
+
+from qtpy.QtCore import QMargins, QPoint, QRect, QSize, Qt
+from qtpy.QtWidgets import QLayout
+
+
+class FlowLayout(QLayout):
+    """Left-to-right layout that wraps its items onto new rows as needed."""
+
+    def __init__(
+        self,
+        parent=None,
+        *,
+        margin: int = 0,
+        h_spacing: int = 4,
+        v_spacing: int = 4,
+    ) -> None:
+        super().__init__(parent)
+        self._items: list = []
+        self._h_spacing = int(h_spacing)
+        self._v_spacing = int(v_spacing)
+        self.setContentsMargins(QMargins(margin, margin, margin, margin))
+
+    # -- QLayout plumbing ---------------------------------------------------
+    def addItem(self, item) -> None:
+        self._items.append(item)
+
+    def count(self) -> int:
+        return len(self._items)
+
+    def itemAt(self, index: int):
+        if 0 <= index < len(self._items):
+            return self._items[index]
+        return None
+
+    def takeAt(self, index: int):
+        if 0 <= index < len(self._items):
+            return self._items.pop(index)
+        return None
+
+    def expandingDirections(self):
+        return Qt.Orientation(0)
+
+    def hasHeightForWidth(self) -> bool:
+        return True
+
+    def heightForWidth(self, width: int) -> int:
+        return self._do_layout(QRect(0, 0, width, 0), test_only=True)
+
+    def setGeometry(self, rect: QRect) -> None:
+        super().setGeometry(rect)
+        self._do_layout(rect, test_only=False)
+
+    def sizeHint(self) -> QSize:
+        return self.minimumSize()
+
+    def minimumSize(self) -> QSize:
+        size = QSize()
+        for item in self._items:
+            size = size.expandedTo(item.minimumSize())
+        margins = self.contentsMargins()
+        size += QSize(
+            margins.left() + margins.right(), margins.top() + margins.bottom()
+        )
+        return size
+
+    # -- layout maths -------------------------------------------------------
+    def _do_layout(self, rect: QRect, *, test_only: bool) -> int:
+        margins = self.contentsMargins()
+        effective = rect.adjusted(
+            margins.left(), margins.top(), -margins.right(), -margins.bottom()
+        )
+        x = effective.x()
+        y = effective.y()
+        line_height = 0
+        for item in self._items:
+            hint = item.sizeHint()
+            next_x = x + hint.width() + self._h_spacing
+            if next_x - self._h_spacing > effective.right() and line_height > 0:
+                x = effective.x()
+                y = y + line_height + self._v_spacing
+                next_x = x + hint.width() + self._h_spacing
+                line_height = 0
+            if not test_only:
+                item.setGeometry(QRect(QPoint(x, y), hint))
+            x = next_x
+            line_height = max(line_height, hint.height())
+        return y + line_height - rect.y() + margins.bottom()
+
+
+__all__ = ["FlowLayout"]

itasc/napari/_icons.py

@@ -0,0 +1,126 @@
+"""Crisp, accent-tinted vector icons for toolbar / stage-header action buttons.
+
+Ported from napariTFM for visual parity across the two tools. Rendered from
+inline SVG via QtSvg so they re-tint with the active theme and stay sharp at any
+DPI — no bundled raster assets. Each body carries a ``{c}`` colour placeholder;
+stroke icons inherit the wrapper stroke, filled icons override ``fill`` on their
+own element.
+"""
+from __future__ import annotations
+
+from qtpy.QtCore import QByteArray, QRectF, Qt
+from qtpy.QtGui import QIcon, QPainter, QPixmap
+from qtpy.QtSvg import QSvgRenderer
+
+_ICON_BODIES = {
+    # magnifier — "show this stage's data"
+    "files": '<circle cx="11" cy="11" r="7"/><line x1="21" y1="21" x2="16.5" y2="16.5"/>',
+    # sliders — "tune this stage's parameters"
+    "params": (
+        '<line x1="3" y1="8" x2="21" y2="8"/>'
+        '<circle cx="9" cy="8" r="2.4" fill="{c}" stroke="none"/>'
+        '<line x1="3" y1="16" x2="21" y2="16"/>'
+        '<circle cx="15" cy="16" r="2.4" fill="{c}" stroke="none"/>'
+    ),
+    # eye — "preview this stage"
+    "preview": (
+        '<path d="M2 12 C5 6 19 6 22 12 C19 18 5 18 2 12 Z"/>'
+        '<circle cx="12" cy="12" r="3"/>'
+    ),
+    # play triangle — "run this stage"
+    "run": '<path d="M8 5 L19 12 L8 19 Z" fill="{c}" stroke="none"/>',
+    # stop square — "cancel the running stage"
+    "cancel": '<rect x="6.5" y="6.5" width="11" height="11" rx="1.5" fill="{c}" stroke="none"/>',
+    # power — "enable / disable this stage"
+    "power": (
+        '<path d="M12 3 L12 11"/>'
+        '<path d="M6.4 6.8 A8 8 0 1 0 17.6 6.8"/>'
+    ),
+    # plus — "add folders"
+    "plus": '<line x1="12" y1="5" x2="12" y2="19"/><line x1="5" y1="12" x2="19" y2="12"/>',
+    # crosshair target — "auto-select the optimal regularization (GCV)"
+    "gcv": (
+        '<circle cx="12" cy="12" r="6.5"/>'
+        '<line x1="12" y1="1.5" x2="12" y2="5"/>'
+        '<line x1="12" y1="19" x2="12" y2="22.5"/>'
+        '<line x1="1.5" y1="12" x2="5" y2="12"/>'
+        '<line x1="19" y1="12" x2="22.5" y2="12"/>'
+    ),
+    # page with a folded corner + plus — "start a new project"
+    "new": (
+        '<path d="M6 3 H14 L18 7 V21 H6 Z"/>'
+        '<path d="M14 3 V7 H18"/>'
+        '<path d="M9 15 H15"/>'
+        '<path d="M12 12 V18"/>'
+    ),
+    # tabbed folder — "load / open a project or a preset"
+    "load": '<path d="M3 6 H9 L11 8 H21 V19 H3 Z"/>',
+    # floppy disk — "save a project or a preset"
+    "save": (
+        '<path d="M5 4 H15.5 L20 8.5 V20 H5 Z"/>'
+        '<path d="M8 20 V14 H16 V20"/>'
+        '<path d="M9 4 V8 H13.5 V4"/>'
+    ),
+    # counterclockwise rewind — "reset parameters / reload"
+    "reset": (
+        '<path d="M5.5 6.5 A8.5 8.5 0 1 0 18 6"/>'
+        '<path d="M6.06 8.89 L6.80 4.01 L2.94 7.08"/>'
+    ),
+}
+
+_SVG_TEMPLATE = (
+    '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" '
+    'fill="none" stroke="{c}" stroke-width="{w}" '
+    'stroke-linecap="{cap}" stroke-linejoin="{join}">{body}</svg>'
+)
+
+ICON_NAMES = tuple(_ICON_BODIES)
+
+
+def _render(svg: str, size: int) -> QPixmap:
+    pixmap = QPixmap(size, size)
+    pixmap.fill(Qt.transparent)
+    renderer = QSvgRenderer(QByteArray(svg.encode("utf-8")))
+    painter = QPainter(pixmap)
+    renderer.render(painter, QRectF(0, 0, size, size))
+    painter.end()
+    return pixmap
+
+
+def stage_action_pixmap(
+    name: str,
+    color: str,
+    size: int = 18,
+    stroke_width: float = 2.0,
+    linecap: str = "round",
+    linejoin: str = "round",
+) -> QPixmap:
+    """Render a single tinted action icon to a transparent pixmap."""
+    body = _ICON_BODIES[name].format(c=color)
+    svg = _SVG_TEMPLATE.format(
+        c=color, w=stroke_width, cap=linecap, join=linejoin, body=body
+    )
+    return _render(svg, size)
+
+
+def stage_action_icon(
+    name: str,
+    color: str,
+    disabled_color: str | None = None,
+    size: int = 18,
+    stroke_width: float = 2.0,
+    linecap: str = "round",
+    linejoin: str = "round",
+) -> QIcon:
+    """A QIcon for an action button, optionally carrying a dimmed disabled mode."""
+    icon = QIcon(
+        stage_action_pixmap(name, color, size, stroke_width, linecap, linejoin)
+    )
+    if disabled_color is not None:
+        icon.addPixmap(
+            stage_action_pixmap(
+                name, disabled_color, size, stroke_width, linecap, linejoin
+            ),
+            QIcon.Disabled,
+        )
+    return icon

itasc/napari/_napari_compat.py

@@ -0,0 +1,118 @@
+"""Compatibility patches for napari/Qt integration edge cases."""
+from __future__ import annotations
+
+from qtpy.QtCore import Qt
+from qtpy.QtGui import QPixmap
+
+
+def _index_size_hint(index):
+    if index is None or (hasattr(index, "isValid") and not index.isValid()):
+        return None
+    size_hint = index.data(Qt.ItemDataRole.SizeHintRole)
+    if size_hint is None or not hasattr(size_hint, "height"):
+        return None
+    return size_hint
+
+
+def patch_napari_layer_delegate() -> None:
+    """Make napari's layer delegate tolerate transient indexes without size hints."""
+    try:
+        from napari._qt.containers._layer_delegate import LayerDelegate
+        from napari._qt.containers.qt_layer_model import LoadedRole, ThumbnailRole
+    except Exception:
+        return
+
+    if getattr(LayerDelegate, "_itasc_missing_size_hint_patch", False):
+        return
+
+    def _paint_loading(self, painter, option, index):
+        loaded = index.data(LoadedRole)
+        if loaded:
+            return
+
+        size_hint = _index_size_hint(index)
+        if size_hint is None:
+            return
+
+        self._load_movie.start()
+        load_rect = option.rect.translated(4, 8)
+        h = size_hint.height() - 16
+        load_rect.setWidth(h)
+        load_rect.setHeight(h)
+        painter.drawPixmap(load_rect, self._load_movie.currentPixmap())
+
+    def _paint_thumbnail(self, painter, option, index):
+        loaded = index.data(LoadedRole)
+        if not loaded:
+            return
+
+        size_hint = _index_size_hint(index)
+        if size_hint is None:
+            return
+
+        all_loaded = index.model().sourceModel().all_loaded()
+        if all_loaded:
+            self._load_movie.setPaused(True)
+
+        thumb_rect = option.rect.translated(-2, 2)
+        h = size_hint.height() - 4
+        thumb_rect.setWidth(h)
+        thumb_rect.setHeight(h)
+        image = index.data(ThumbnailRole)
+        painter.drawPixmap(thumb_rect, QPixmap.fromImage(image))
+
+    LayerDelegate._paint_loading = _paint_loading
+    LayerDelegate._paint_thumbnail = _paint_thumbnail
+    LayerDelegate._itasc_missing_size_hint_patch = True
+
+    patch_vispy_units_scale_guard()
+
+
+def patch_vispy_units_scale_guard() -> None:
+    """Stop a canvas-draw ``IndexError`` from a layer whose per-axis units scale
+    is shorter than its displayed dims.
+
+    napari's ``VispyBaseLayer._on_matrix_change`` indexes
+    ``self._world_to_layer_units_scale`` by ``self.layer._slice_input.displayed``.
+    When physical units (e.g. an OME-TIFF's ``(pixel, pixel)``) reach a layer with
+    more dimensions than the units tuple — a calibrated 2D stack shown in a 3D
+    viewer — ``_recalculate_units_scale``'s ``strict=False`` zip yields a units
+    scale shorter than ``dims_displayed``, and indexing ``[2]`` overruns:
+
+        IndexError: tuple index out of range  (canvas.py → _on_matrix_change)
+
+    The unresolved axes have no calibration, so their scale is just napari's
+    default of ``1.0``. Pad the units scale up to the displayed-dim extent with
+    ``1.0`` before delegating — semantically the identity, so the only behaviour
+    change is that the draw no longer crashes."""
+    try:
+        from napari._vispy.layers.base import VispyBaseLayer
+    except Exception:  # pragma: no cover - napari layout changed / unavailable
+        return
+    if getattr(VispyBaseLayer, "_itasc_units_scale_guard", False):
+        return
+
+    original_on_matrix_change = VispyBaseLayer._on_matrix_change
+
+    def _guarded_on_matrix_change(self):
+        try:
+            self._world_to_layer_units_scale = _padded_units_scale(
+                self._world_to_layer_units_scale, self.layer._slice_input.displayed
+            )
+        except Exception:  # pragma: no cover - never let the guard itself break draw
+            pass
+        return original_on_matrix_change(self)
+
+    VispyBaseLayer._on_matrix_change = _guarded_on_matrix_change
+    VispyBaseLayer._itasc_units_scale_guard = True
+
+
+def _padded_units_scale(scale, displayed) -> tuple:
+    """*scale* extended with ``1.0`` (the no-calibration default) so every index
+    in *displayed* is in range; unchanged when it already covers them."""
+    scale = tuple(scale)
+    needed = (max(displayed) + 1) if len(displayed) else 0
+    if len(scale) >= needed:
+        return scale
+    return scale + (1.0,) * (needed - len(scale))
+

itasc/napari/_paths.py

@@ -0,0 +1,231 @@
+"""On-disk artifact paths for ITASC position directories.
+
+Canonical file layout under ``<pos_dir>/``:
+
+    0_input/              — cell_zavg.tif, nucleus_zavg.tif, NLS_zavg.tif
+    1_cellpose/           — nucleus_prob.tif, nucleus_dp.tif,
+                            cell_prob.tif, cell_dp.tif,
+                            nucleus_contours.tif, nucleus_foreground.tif,
+                            cell_contours.tif, cell_foreground.tif
+    2_nucleus/            — contour_sources.tif, foreground_sources.tif,
+                            tracked_labels.tif, ultrack_workdir/data.db
+    3_cell/               — filtered_dp.tif, foreground_masks.tif,
+                            contours.tif, foreground_scores.tif,
+                            tracked_labels.tif
+    nucleus_labels.tif    — FINAL output: committed nucleus tracked labels
+    cell_labels.tif       — FINAL output: committed cell tracked labels
+    contact_analysis.h5   — FINAL output: contact graph built from the labels
+
+The numbered stage dirs hold re-runnable *working* artifacts; the base-folder
+``nucleus_labels.tif`` / ``cell_labels.tif`` are the committed, downstream-stable
+*final* outputs (see :func:`itasc.core.commit.promote_labels`), and
+``contact_analysis.h5`` — the graph derived from them — sits beside them. Contact
+Analysis discovery defaults to these committed names.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class NucleusArtifactPaths:
+    """Resolve nucleus-workflow artifact locations under a position directory."""
+
+    pos_dir: Path
+
+    # 0_input
+    @property
+    def cell_zavg(self) -> Path:
+        return self.pos_dir / "0_input" / "cell_zavg.tif"
+
+    @property
+    def nucleus_zavg(self) -> Path:
+        return self.pos_dir / "0_input" / "nucleus_zavg.tif"
+
+    @property
+    def nls_zavg(self) -> Path:
+        return self.pos_dir / "0_input" / "NLS_zavg.tif"
+
+    # 1_cellpose — Cellpose outputs
+    @property
+    def prob(self) -> Path:
+        return self.pos_dir / "1_cellpose" / "nucleus_prob.tif"
+
+    @property
+    def cell_prob(self) -> Path:
+        return self.pos_dir / "1_cellpose" / "cell_prob.tif"
+
+    @property
+    def dp(self) -> Path:
+        return self.pos_dir / "1_cellpose" / "nucleus_dp.tif"
+
+    @property
+    def cell_dp(self) -> Path:
+        return self.pos_dir / "1_cellpose" / "cell_dp.tif"
+
+    # 1_cellpose — Divergence-map outputs (per channel)
+    @property
+    def nucleus_contours(self) -> Path:
+        return self.pos_dir / "1_cellpose" / "nucleus_contours.tif"
+
+    @property
+    def nucleus_foreground(self) -> Path:
+        return self.pos_dir / "1_cellpose" / "nucleus_foreground.tif"
+
+    @property
+    def cell_contours(self) -> Path:
+        return self.pos_dir / "1_cellpose" / "cell_contours.tif"
+
+    @property
+    def cell_foreground(self) -> Path:
+        return self.pos_dir / "1_cellpose" / "cell_foreground.tif"
+
+    # Aliases for the nucleus channel — historical names retained for callers
+    # that don't need a channel suffix (e.g. tracking-input writers).
+    @property
+    def contours(self) -> Path:
+        return self.nucleus_contours
+
+    @property
+    def foreground(self) -> Path:
+        return self.nucleus_foreground
+
+    # 2_nucleus
+    @property
+    def nucleus_dir(self) -> Path:
+        return self.pos_dir / "2_nucleus"
+
+    @property
+    def contour_sources(self) -> Path:
+        return self.nucleus_dir / "contour_sources.tif"
+
+    @property
+    def foreground_sources(self) -> Path:
+        return self.nucleus_dir / "foreground_sources.tif"
+
+    @property
+    def tracked(self) -> Path:
+        return self.nucleus_dir / "tracked_labels.tif"
+
+    @property
+    def ultrack_workdir(self) -> Path:
+        return self.nucleus_dir / "ultrack_workdir"
+
+    @property
+    def ultrack_db(self) -> Path:
+        return self.ultrack_workdir / "data.db"
+
+    @property
+    def nucleus_atoms(self) -> Path:
+        return self.nucleus_dir / "atoms.tif"
+
+    # 3_cell working output (the cell-workflow tracked labels, pre-commit)
+    @property
+    def cell_tracked(self) -> Path:
+        return self.pos_dir / "3_cell" / "tracked_labels.tif"
+
+    # Final outputs (committed) — base folder, downstream-stable
+    @property
+    def nucleus_labels(self) -> Path:
+        return self.pos_dir / "nucleus_labels.tif"
+
+    @property
+    def cell_labels(self) -> Path:
+        return self.pos_dir / "cell_labels.tif"
+
+
+@dataclass(frozen=True)
+class NucleusWorkspace:
+    """Single base directory for the nucleus tracking/correction piece.
+
+    All artifacts (database, tracked labels, atoms, source maps) and the
+    annotation store (validation/correction JSONs) live directly under
+    ``nucleus_dir``; the two foreground/contour *inputs* are explicit paths.
+
+    Three layouts are supported via the constructors:
+
+    * :meth:`staged` — the full orchestrator: ``nucleus_dir`` is
+      ``<pos>/2_nucleus`` and the inputs come from ``<pos>/1_cellpose``.
+    * :meth:`flat` — a standalone working directory that holds
+      ``foreground.tif`` + ``contours.tif`` and receives every output.
+    * :meth:`files` — the standalone tracking piece: explicit foreground and
+      contour file paths (any name, any location) plus an output directory that
+      receives every output.
+    """
+
+    nucleus_dir: Path
+    foreground: Path
+    contours: Path
+    # Optional cross-stage cell foreground, used purely as a correction-mode
+    # background overlay. Only the staged orchestrator supplies it.
+    cell_foreground: Path | None = None
+
+    @classmethod
+    def staged(cls, pos_dir: Path) -> NucleusWorkspace:
+        paths = NucleusArtifactPaths(Path(pos_dir))
+        return cls(
+            nucleus_dir=paths.nucleus_dir,
+            foreground=paths.nucleus_foreground,
+            contours=paths.nucleus_contours,
+            cell_foreground=paths.cell_foreground,
+        )
+
+    @classmethod
+    def flat(cls, work_dir: Path) -> NucleusWorkspace:
+        work_dir = Path(work_dir)
+        return cls(
+            nucleus_dir=work_dir,
+            foreground=work_dir / "foreground.tif",
+            contours=work_dir / "contours.tif",
+        )
+
+    @classmethod
+    def files(
+        cls,
+        *,
+        foreground: Path | str,
+        contours: Path | str,
+        output_dir: Path | str | None = None,
+    ) -> NucleusWorkspace:
+        """Explicit foreground/contour file paths + an output directory.
+
+        The two inputs may have any name and live anywhere; every output is
+        written under ``output_dir`` (defaulting to the foreground file's parent
+        when omitted).
+        """
+        foreground = Path(foreground)
+        contours = Path(contours)
+        nucleus_dir = Path(output_dir) if output_dir else foreground.parent
+        return cls(
+            nucleus_dir=nucleus_dir,
+            foreground=foreground,
+            contours=contours,
+        )
+
+    # Artifacts (outputs), all directly under nucleus_dir
+    @property
+    def contour_sources(self) -> Path:
+        return self.nucleus_dir / "contour_sources.tif"
+
+    @property
+    def foreground_sources(self) -> Path:
+        return self.nucleus_dir / "foreground_sources.tif"
+
+    @property
+    def tracked(self) -> Path:
+        return self.nucleus_dir / "tracked_labels.tif"
+
+    @property
+    def ultrack_workdir(self) -> Path:
+        return self.nucleus_dir / "ultrack_workdir"
+
+    @property
+    def ultrack_db(self) -> Path:
+        return self.ultrack_workdir / "data.db"
+
+    @property
+    def atoms(self) -> Path:
+        return self.nucleus_dir / "atoms.tif"
+
+

itasc/napari/_preview_cache.py

@@ -0,0 +1,60 @@
+"""A per-frame result cache for the live-preview widgets.
+
+Every live preview recomputes the current frame off the GUI thread on each param
+edit or time scrub. Without a cache, scrubbing back to a frame that was just
+computed re-runs the (often heavy) pipeline for an identical result. This cache
+holds whatever a compute produced for each visited frame, keyed on a *signature*
+of the parameters that determine the result, so:
+
+* scrubbing back to an already-computed frame repaints instantly, and
+* any param edit (a changed signature) drops every cached frame at once.
+
+It mirrors the per-frame cache the cell-segmentation preview
+(:mod:`itasc.napari.cell_workflow_widget`) grew first; the other previews
+share this implementation rather than re-deriving it.
+
+Stale-write safety: a worker started under an old signature may finish *after* an
+edit has moved the cache to a new one. The owner adopts the current signature up
+front with :meth:`sync`, reads with :meth:`get`, and stores with :meth:`put`
+passing the signature the result was computed under — :meth:`put` ignores the
+write when that signature is no longer current, so a late worker can never poison
+the fresh cache.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+_UNSET = object()
+
+
+class FramePreviewCache:
+    """Frame ``t`` → result, valid only while the parameter signature holds."""
+
+    def __init__(self) -> None:
+        self._key: Any = _UNSET
+        self._frames: dict[int, Any] = {}
+
+    def sync(self, key: Any) -> None:
+        """Adopt *key* as the current signature, dropping all frames if it changed."""
+        if key != self._key:
+            self._key = key
+            self._frames = {}
+
+    def get(self, t: int) -> Any | None:
+        """The cached result for frame *t* under the current signature, or ``None``."""
+        return self._frames.get(t)
+
+    def put(self, key: Any, t: int, value: Any) -> None:
+        """Store *value* for frame *t* — ignored when *key* is no longer current.
+
+        Call :meth:`sync` with the live signature before reading; pass the
+        signature the *value* was computed under here so a worker that finishes
+        after an edit cannot overwrite the re-keyed cache.
+        """
+        if key == self._key:
+            self._frames[t] = value
+
+    def clear(self) -> None:
+        """Forget every frame and the signature (e.g. when the preview deactivates)."""
+        self._key = _UNSET
+        self._frames = {}

itasc/napari/_spotlight.py

@@ -0,0 +1,46 @@
+"""Shared selection-highlight rendering: turn a boolean cell mask into the RGBA
+overlay the correction studio paints over the labels.
+
+Two visual cues, independently toggleable:
+
+* ``dim`` — uniformly dim everything *outside* the mask (the "spotlight"), so the
+  selected cell stays at full brightness while its surroundings recede.
+* ``border`` — draw an opaque yellow ring just outside the mask.
+
+The correction widget uses one cue at a time (its ``spotlight`` / ``border``
+styles); the aggregate-quantification click-to-load uses both at once so a picked
+cell reads clearly against the full labels movie it sits in.
+"""
+from __future__ import annotations
+
+import numpy as np
+from scipy.ndimage import binary_dilation
+
+#: Alpha applied outside the mask in spotlight (``dim``) mode.
+SPOTLIGHT_OPACITY = 0.7
+
+
+def spotlight_rgba(
+    mask: np.ndarray,
+    *,
+    dim: bool = True,
+    border: bool = False,
+    opacity: float = SPOTLIGHT_OPACITY,
+    ring_iterations: int = 2,
+) -> np.ndarray:
+    """RGBA (``mask.shape + (4,)``, float32) overlay highlighting *mask*.
+
+    With *dim*, everything outside the mask is washed at *opacity* and the mask
+    itself left fully transparent. With *border*, an opaque yellow ring of
+    *ring_iterations* px is drawn just outside the mask. An all-False mask yields
+    an all-zero (fully transparent) overlay.
+    """
+    data = np.zeros(mask.shape + (4,), dtype=np.float32)
+    if dim:
+        alpha = np.full(mask.shape, opacity, dtype=np.float32)
+        alpha[mask] = 0.0
+        data[..., 3] = alpha
+    if border:
+        ring = binary_dilation(mask, iterations=ring_iterations) & ~mask
+        data[ring] = (1.0, 1.0, 0.0, 1.0)  # opaque yellow outline
+    return data