itasc 0.2.0.dev0__py3-none-any.whl

itasc/napari/correction/_correction_events.py

@@ -0,0 +1,39 @@
+"""Domain events for the nucleus correction widget.
+
+The widget emits one of these when something *happens* — a hand mask edit, a
+track rebuild, a selection change — and the display collaborators subscribe to
+repaint themselves. They already pull the current layer / selection / frame /
+enabled-state through their provider callbacks (see how the controllers are
+constructed), so an event only has to say *when* to refresh, not *what* changed.
+
+This inverts the older shape, where every operation hand-called each controller's
+refresh, scattering display coupling across the edit logic. With events, an
+operation announces what it did and stays ignorant of who listens; the
+subscriber map lives in one place (``NucleusCorrectionWidget._wire_events``).
+"""
+
+from __future__ import annotations
+
+from qtpy.QtCore import QObject, Signal
+
+
+class CorrectionEvents(QObject):
+    """Signals announcing correction-domain changes (see module docstring)."""
+
+    # A hand mask edit landed at one frame: ``(t, changed_ids)``.
+    labels_edited = Signal(object, object)
+    # The selected track's geometry changed across frames (extend / retrack):
+    # repaint the live track views (comet, lineage canvas, candidate gallery).
+    tracks_rebuilt = Signal()
+    # Per-frame validation / anchor *flags* changed, but not the labels
+    # themselves (validate / invalidate). Flag-only, so the lineage canvas
+    # recolours (status refresh) rather than rebuilding the whole stack.
+    validation_changed = Signal()
+    # One swap candidate was stepped to (Z / C, or a gallery pick). A cheap
+    # refresh — comet + the selected track's detail strip + gallery — without
+    # the whole-stack lineage rebuild, so keystroke stepping stays responsive.
+    swap_stepped = Signal()
+    # The whole label stack was rewritten (reassign IDs / remove-unvalidated /
+    # commit / anchor): full refresh — recolour, validated overlay + counter,
+    # and a whole-stack lineage rebuild.
+    stack_relabeled = Signal()

itasc/napari/correction/_correction_keymap.py

@@ -0,0 +1,80 @@
+"""Auto-repeat for held navigation keys in correction focus mode.
+
+napari only auto-repeats *bare* arrows (not Shift+arrow), so the correction
+widget drives a steady repeat itself: a press fires the action once and arms a
+one-shot for an initial hold delay; if the key is still held when that elapses,
+the timer settles into a steady repeat paced to the viewer's playback fps. The
+matching release disarms it.
+
+The state machine and its timer are isolated here so the widget only wires the
+key bindings. The QTimer is injected (the widget passes ``QTimer(self)``) so the
+logic can be unit-tested with a mock timer and no event loop.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+KEY_REPEAT_DELAY_MS = 300  # hold threshold before repeating kicks in
+
+
+class HeldKeyRepeater:
+    """Drive a steady repeat for whichever navigation key is currently held.
+
+    ``interval_provider`` returns the steady repeat interval (ms) at the moment
+    repeating begins, so it can track the viewer's live playback fps.
+    """
+
+    def __init__(self, timer, interval_provider: Callable[[], int]) -> None:
+        self._timer = timer
+        self._timer.timeout.connect(self._on_tick)
+        self._interval_provider = interval_provider
+        self._key: str | None = None
+        self._action: Callable[[], None] | None = None
+
+    def begin(self, key: str, action: Callable[[], None]) -> None:
+        # An OS auto-repeat re-press of the same held key would re-enter here;
+        # ignore it so the steady timer stays the single source of repeats.
+        if self._key == key:
+            return
+        self._key = key
+        self._action = action
+        action()
+        # Arm a one-shot for the initial hold delay; a tap released before it
+        # elapses never repeats. The first tick then settles into the steady
+        # fps-paced repeat (see _on_tick).
+        self._timer.setSingleShot(True)
+        self._timer.start(KEY_REPEAT_DELAY_MS)
+
+    def end(self, key: str) -> None:
+        if self._key == key:
+            self.stop()
+
+    def stop(self) -> None:
+        self._timer.stop()
+        self._key = None
+        self._action = None
+
+    def _on_tick(self) -> None:
+        if self._action is None:
+            return
+        self._action()
+        if self._timer.isSingleShot():
+            # The initial delay just elapsed; from here repeat steadily at the
+            # viewer's playback fps until the key is released.
+            self._timer.setSingleShot(False)
+            self._timer.start(self._interval_provider())
+
+    def key_handler(self, key: str, slot: Callable[[], None]):
+        """A napari generator keybinding: press starts repeat, release stops it.
+
+        napari runs the pre-``yield`` half on key press and the post-``yield``
+        half on release (it stashes the paused generator per key). Between them
+        the repeat timer drives ``slot`` at a steady rate.
+        """
+        def handler(_layer, _key=key, _slot=slot):
+            self.begin(_key, _slot)
+            yield
+            self.end(_key)
+
+        return handler

itasc/napari/correction/_correction_layer_lifecycle.py

@@ -0,0 +1,137 @@
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class LayerViewState:
+    visibility: dict[str, bool]
+    active: str | None
+    selected: tuple[str, ...]
+
+
+def capture_layer_view_state(layers: Any) -> LayerViewState:
+    """Capture layer visibility and selection before entering correction mode."""
+    active = layers.selection.active
+    return LayerViewState(
+        visibility={layer.name: bool(layer.visible) for layer in layers},
+        active=active.name if active is not None else None,
+        selected=tuple(layer.name for layer in layers.selection),
+    )
+
+
+def hide_all_layers(layers: Any) -> None:
+    """Hide all current layers while correction-mode layers are loaded."""
+    for layer in list(layers):
+        layer.visible = False
+
+
+def restore_layer_view_state(layers: Any, state: LayerViewState | None) -> None:
+    """Restore captured visibility and selection for layers that still exist."""
+    if state is None:
+        return
+    for name, visible in state.visibility.items():
+        if name in layers:
+            layers[name].visible = bool(visible)
+    layers.selection.clear()
+    for name in state.selected:
+        if name in layers:
+            layers.selection.add(layers[name])
+    if state.active is not None and state.active in layers:
+        layers.selection.active = layers[state.active]
+
+
+def remove_owned_layers(layers: Any, owned_layer_names: set[str]) -> None:
+    """Remove registered correction-owned layers and clear the ownership set."""
+    for name in list(owned_layer_names):
+        if name in layers:
+            layers.remove(layers[name])
+    owned_layer_names.clear()
+
+
+def detach_higher_dim_stacks(
+    layers: Any, *, max_ndim: int, keep_names: Any = ()
+) -> list:
+    """Remove and return layers with more dimensions than the correction stack.
+
+    Correction shows a ``(T, Y, X)`` stack — a single slider whose axis 0 is the
+    frame. A pre-loaded 3D z-stack carried as ``(T, Z, Y, X)`` data has a higher
+    rank, so napari (which aligns layer axes to the right) treats its trailing
+    ``(T, Y, X)`` as the global ``(Z, Y, X)`` and the frame slider no longer
+    scrubs the correction frames. Such higher-rank layers are *removed* — not
+    merely hidden, because napari derives the dims sliders from every layer
+    regardless of visibility.
+
+    Only layers whose rank *exceeds* ``max_ndim`` (the correction stack's own
+    rank) are detached, so same-rank intensity/label layers — even ones with a
+    different frame count — are left alone. The detached ``Layer`` objects are
+    returned verbatim so they can be re-appended on restore with their data,
+    contrast limits and colormap intact (nothing is reloaded from disk).
+    ``keep_names`` (e.g. the correction-owned layers) are never detached.
+    """
+    keep = set(keep_names)
+    detached: list = []
+    for layer in list(layers):
+        if getattr(layer, "name", None) in keep:
+            continue
+        ndim = getattr(getattr(layer, "data", None), "ndim", None)
+        if ndim is not None and ndim > int(max_ndim):
+            detached.append(layer)
+            layers.remove(layer)
+    return detached
+
+
+def reattach_layers(layers: Any, detached: list) -> None:
+    """Re-add layers removed by :func:`detach_higher_dim_stacks`, verbatim.
+
+    Skips any whose name is already back in the list (e.g. re-loaded meanwhile),
+    so restore is idempotent.
+    """
+    for layer in detached:
+        if getattr(layer, "name", None) not in layers:
+            layers.append(layer)
+
+
+class CorrectionViewStateMixin:
+    """Shared correction-mode view-state + owned-layer handling.
+
+    Mixed into both the cell and nucleus correction widgets, which were carrying
+    byte-identical copies of these methods. The host must expose ``self.viewer``
+    and ``self.correction_status_lbl``, and track ``self._correction_view_state``
+    (captured on activate, restored + cleared on deactivate),
+    ``self._correction_owned_layers`` (the layer names the widget added and must
+    tear down) and the ``self._correction_dirty`` flag.
+    """
+
+    _correction_view_state: LayerViewState | None
+    _correction_owned_layers: set[str]
+    _correction_dirty: bool
+
+    def _capture_correction_view_state(self) -> None:
+        self._correction_view_state = capture_layer_view_state(self.viewer.layers)
+
+    def _restore_correction_view_state(self) -> None:
+        restore_layer_view_state(self.viewer.layers, self._correction_view_state)
+        self._correction_view_state = None
+
+    def _remove_correction_owned_layers(self) -> None:
+        remove_owned_layers(self.viewer.layers, self._correction_owned_layers)
+
+    def _current_t(self) -> int:
+        step = getattr(getattr(self.viewer, "dims", None), "current_step", (0,))
+        return int(step[0]) if len(step) >= 1 else 0
+
+    def _correction_status(self, msg: str) -> None:
+        self.correction_status_lbl.setText(msg)
+        self.correction_status_lbl.setVisible(bool(msg))
+        lowered = msg.lower()
+        if "unsaved" in lowered:
+            self._correction_dirty = True
+        elif lowered.startswith("saved") or lowered.startswith("loaded"):
+            self._correction_dirty = False
+        if msg:
+            logger.info(msg)

itasc/napari/correction/_correction_layer_loader.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+import numpy as np
+from napari.utils.colormaps import Colormap
+
+from itasc.napari.correction._correction_centroids import (
+    refresh_label_colormap,
+)
+
+
+@dataclass(frozen=True)
+class TrackedLayerLoadResult:
+    labels_layer: Any
+    color_map: dict[int | None, tuple[float, float, float, float] | str]
+
+
+def add_correction_image_layer(
+    viewer: Any,
+    data: np.ndarray,
+    *,
+    name: str,
+    colormap: str,
+    owned_layer_names: set[str],
+) -> Any:
+    """Add a correction-owned reference image layer."""
+    arr = np.asarray(data, dtype=np.float32)
+    cmap: str | Colormap = colormap
+    if cmap == "bop_blue":
+        cmap = Colormap(
+            [[0.0, 0.0, 0.0, 1.0], [0.0, 0.25, 1.0, 1.0]],
+            name="bop_blue",
+        )
+    layer = viewer.add_image(arr, name=name, colormap=cmap, blending="minimum")
+    owned_layer_names.add(name)
+    return layer
+
+
+def add_tracked_labels_and_track_layer(
+    viewer: Any,
+    labels: np.ndarray,
+    *,
+    labels_layer_name: str,
+    owned_layer_names: set[str],
+    color_scale: float = 0.65,
+) -> TrackedLayerLoadResult:
+    """Add the correction labels layer with its deterministic colormap.
+
+    The trajectory overlay is no longer rasterised here — it's a live napari
+    ``Tracks`` layer owned by ``AllTracksController`` (built on demand from this
+    same label data), so this just lays down the labels and returns the colour
+    map both share.
+    """
+    labels_arr = np.asarray(labels)
+    labels_layer = viewer.add_labels(
+        labels_arr,
+        name=labels_layer_name,
+        blending="additive",
+    )
+    labels_layer.blending = "additive"
+    owned_layer_names.add(labels_layer_name)
+    color_map = refresh_label_colormap(
+        labels_layer,
+        labels_arr,
+        color_scale=color_scale,
+    )
+    return TrackedLayerLoadResult(labels_layer=labels_layer, color_map=color_map)
+
+
+def remove_other_correction_label_layers(
+    viewer: Any,
+    *,
+    owned_layer_names: set[str],
+    label_layer_type: type,
+    prefix: str = "[Correction]",
+) -> None:
+    """Remove stale correction-prefixed labels not owned by the active session."""
+    for layer in list(viewer.layers):
+        if (
+            layer.name.startswith(prefix)
+            and layer.name not in owned_layer_names
+            and isinstance(layer, label_layer_type)
+        ):
+            viewer.layers.remove(layer)

itasc/napari/correction/_correction_navigation.py

@@ -0,0 +1,97 @@
+"""Frame the selected track in the napari image viewer.
+
+Camera math for the focus-mode navigation: given the active tracked Labels layer
+and a selected cell id, pan the viewer onto the track's whole-stack bounding box
+and zoom so it fills a fixed fraction of the canvas. These are pure functions of
+``(viewer, layer)`` with no widget state, so they live here rather than on the
+correction widget; the widget's navigation handlers (``_navigate_to_cell``,
+``_step_track``) call :func:`center_viewer_on_cell` after selecting a cell.
+"""
+
+from __future__ import annotations
+
+import logging
+
+import numpy as np
+
+logger = logging.getLogger(__name__)
+
+# The selected track's bbox is zoomed to span ~this fraction of the canvas in
+# its limiting dimension (≈25% of the canvas area), leaving margin around it.
+TRACK_VIEWPORT_FRACTION = 0.5
+
+
+def canvas_size_px(viewer):
+    """``(height, width)`` of the viewer canvas in pixels, or ``None``.
+
+    napari's ``_qt_viewer.canvas`` is private and its shape varies across
+    versions, so a missing/odd attribute degrades to "leave the zoom alone".
+    """
+    try:
+        h, w = viewer.window._qt_viewer.canvas.size
+        h, w = int(h), int(w)
+        if h > 0 and w > 0:
+            return h, w
+    except Exception:
+        logger.debug("track framing: canvas size unavailable", exc_info=True)
+    return None
+
+
+def center_viewer_on_cell(viewer, layer, t: int, cell_id: int) -> None:
+    """Frame the whole selected track in the image viewer.
+
+    Centers the napari camera on the track's full spatial bounding box — its
+    union across *every* frame it appears in, not just frame ``t`` — and zooms so
+    that box spans about :data:`TRACK_VIEWPORT_FRACTION` of the canvas in both
+    directions (≈25% of the canvas area), leaving margin around the track. ``t``
+    only fixes the camera's non-spatial axes (the current frame); the y/x framing
+    comes from the whole track.
+    """
+    if layer is None or not cell_id:
+        return
+    try:
+        data = np.asarray(layer.data)
+        coords = np.nonzero(data == int(cell_id))
+        if coords[-1].size == 0:
+            return
+        ys, xs = coords[-2], coords[-1]
+        ymin, ymax = float(ys.min()), float(ys.max())
+        xmin, xmax = float(xs.min()), float(xs.max())
+
+        def to_world(y: float, x: float):
+            coord = (int(t), y, x) if data.ndim >= 3 else (y, x)
+            return layer.data_to_world(coord)
+
+        world_c = to_world((ymin + ymax) / 2.0, (xmin + xmax) / 2.0)
+        center = list(viewer.camera.center)
+        center[-2:] = [float(world_c[-2]), float(world_c[-1])]
+        viewer.camera.center = tuple(center)
+        zoom_to_track_bbox(viewer, ymin, ymax, xmin, xmax, to_world)
+    except Exception:
+        logger.exception("lineage navigation: camera framing failed")
+
+
+def zoom_to_track_bbox(viewer, ymin, ymax, xmin, xmax, to_world) -> None:
+    """Zoom so the track's world bbox fills ~:data:`TRACK_VIEWPORT_FRACTION`.
+
+    napari's ``camera.zoom`` is canvas pixels per world unit, so the world span
+    visible along an axis is ``canvas_px / zoom``. Picking the smaller of the
+    per-axis zooms keeps the larger bbox side at exactly the target fraction and
+    the other side within it (the camera zoom is uniform). Degenerate
+    (zero-extent) sides are skipped; if no canvas size is available the zoom is
+    left untouched.
+    """
+    canvas = canvas_size_px(viewer)
+    if canvas is None:
+        return
+    canvas_h, canvas_w = canvas
+    w0, w1 = to_world(ymin, xmin), to_world(ymax, xmax)
+    bbox_h = abs(float(w1[-2]) - float(w0[-2]))
+    bbox_w = abs(float(w1[-1]) - float(w0[-1]))
+    candidates = []
+    if bbox_h > 0:
+        candidates.append(TRACK_VIEWPORT_FRACTION * canvas_h / bbox_h)
+    if bbox_w > 0:
+        candidates.append(TRACK_VIEWPORT_FRACTION * canvas_w / bbox_w)
+    if candidates:
+        viewer.camera.zoom = min(candidates)

itasc/napari/correction/_correction_paint.py

@@ -0,0 +1,46 @@
+"""Paint label assignments into a single tracked-labels frame.
+
+Shared by the extend paths (keyboard A/D and the candidate-gallery pick): each
+assignment carries a ``cell_id`` and a boolean ``mask_2d``. The frame is mutated
+in place — every assigned id is first cleared, then repainted either greedily
+(overwriting anything not protected) or only into background — and the set of
+ids whose pixels actually changed is returned so the caller can recolour just
+those. Kept pure (no widget / napari state) so it is unit-tested directly.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+import numpy as np
+
+
+def paint_assignments(
+    frame: np.ndarray,
+    assignments: Iterable,
+    protected_mask: np.ndarray,
+    *,
+    greedy: bool,
+) -> set[int]:
+    """Paint ``assignments`` into ``frame``; return the changed cell ids.
+
+    ``greedy`` overwrites everything outside ``protected_mask``; otherwise an
+    assignment only fills background (``frame == 0``) pixels.
+    """
+    assignments = tuple(assignments)
+    before = np.asarray(frame).copy()
+    for a in assignments:
+        frame[frame == int(a.cell_id)] = 0
+    if greedy:
+        for a in assignments:
+            frame[a.mask_2d & ~protected_mask] = int(a.cell_id)
+    else:
+        for a in assignments:
+            frame[a.mask_2d & (frame == 0)] = int(a.cell_id)
+    changed = before != frame
+    changed_ids = (
+        set(int(v) for v in np.unique(before[changed]))
+        | set(int(v) for v in np.unique(np.asarray(frame)[changed]))
+    )
+    changed_ids.discard(0)
+    return changed_ids

itasc/napari/correction/_correction_playback.py

@@ -0,0 +1,68 @@
+"""Read the napari viewer's frame-playback settings (fps + loop mode).
+
+These are pure queries over the viewer's frame (axis-0) slider — the widget that
+the right-click play-button popup writes to — falling back to napari's global
+preferences when the slider is absent. They carry no widget state, so they live
+here as free functions rather than on the correction widget; the held-key
+auto-repeat (:mod:`itasc.napari.correction._correction_keymap`) paces itself from
+:func:`nav_repeat_interval_ms`, and the film-strip stepping reads
+:func:`playback_loops` to decide whether to wrap at the ends.
+"""
+
+from __future__ import annotations
+
+DEFAULT_NAV_FPS = 10.0  # napari's default when no slider/preference exists
+
+
+def frame_slider_widget(viewer):
+    """The frame (axis-0) playback slider widget, or ``None`` if absent.
+
+    It carries the viewer's live fps / loop mode (the right-click play-button
+    popup writes here, defaulting from the global preference).
+    """
+    try:
+        sliders = viewer.window._qt_viewer.dims.slider_widgets
+        return sliders[0] if sliders else None
+    except Exception:
+        return None
+
+
+def playback_fps(viewer) -> float:
+    """The viewer's playback fps — the slider's, else the global preference."""
+    slider = frame_slider_widget(viewer)
+    if slider is not None:
+        try:
+            fps = abs(float(slider.fps))
+            if fps > 0:
+                return fps
+        except Exception:
+            pass
+    try:
+        from napari.settings import get_settings
+
+        return float(get_settings().application.playback_fps)
+    except Exception:
+        return DEFAULT_NAV_FPS
+
+
+def playback_loops(viewer) -> bool:
+    """True when the viewer's playback loop mode wraps at the ends.
+
+    ``once`` stops at an end; ``loop`` / ``back_and_forth`` both wrap around.
+    """
+    slider = frame_slider_widget(viewer)
+    mode = getattr(slider, "loop_mode", None) if slider is not None else None
+    if mode is None:
+        try:
+            from napari.settings import get_settings
+
+            mode = get_settings().application.playback_mode
+        except Exception:
+            return True
+    return str(getattr(mode, "value", mode)).lower() != "once"
+
+
+def nav_repeat_interval_ms(viewer) -> int:
+    """Held-key repeat interval (ms) matching the viewer's playback fps."""
+    fps = max(playback_fps(viewer), 1.0)
+    return max(int(round(1000.0 / fps)), 1)

itasc/napari/correction/_correction_protection.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+
+import numpy as np
+
+from itasc.tracking_ultrack.corrections import Correction
+
+
+def protected_cell_ids_at_frame(
+    validated_tracks: Mapping[int, Iterable[int]],
+    corrections: Iterable[Correction],
+    *,
+    frame: int,
+    exclude_cell_id: int | None = None,
+) -> set[int]:
+    """Return cell IDs that should not be overwritten at *frame*."""
+    target_frame = int(frame)
+    excluded = int(exclude_cell_id) if exclude_cell_id is not None else None
+    protected: set[int] = set()
+
+    for raw_cell_id, frames in validated_tracks.items():
+        cell_id = int(raw_cell_id)
+        if excluded is not None and cell_id == excluded:
+            continue
+        if target_frame in {int(raw_frame) for raw_frame in frames}:
+            protected.add(cell_id)
+
+    for correction in corrections:
+        cell_id = int(correction.cell_id)
+        if excluded is not None and cell_id == excluded:
+            continue
+        if correction.kind == "anchor" and int(correction.t) == target_frame:
+            protected.add(cell_id)
+
+    return protected
+
+
+def protected_cell_mask(frame: np.ndarray, protected_ids: Iterable[int]) -> np.ndarray:
+    """Return a boolean mask of protected labels in *frame*."""
+    ids = [int(cell_id) for cell_id in protected_ids]
+    if not ids:
+        return np.zeros_like(frame, dtype=bool)
+    return np.isin(frame, ids)

itasc/napari/correction/_correction_takeover.py

@@ -0,0 +1,64 @@
+"""Hide and restore napari's native dock chrome for correction *focus mode*.
+
+The correction widget is effectively a standalone app: when it activates we hand
+its panels the whole right column by hiding napari's built-in layer-list and
+layer-controls docks, and restore them (to exactly their prior visibility) when
+it deactivates. Everything is defensive — napari's private ``_qt_viewer`` dock
+attributes differ across versions, so a missing attribute degrades to "leave it
+alone" rather than raising into the correction lifecycle.
+"""
+from __future__ import annotations
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+# napari ``QtViewer`` dock attributes for the chrome we reclaim. ``dockConsole``
+# is intentionally left alone (it starts hidden and users toggle it themselves).
+_NATIVE_DOCKS = ("dockLayerList", "dockLayerControls")
+
+
+def _qt_viewer(viewer):
+    return getattr(getattr(viewer, "window", None), "_qt_viewer", None)
+
+
+def hide_native_docks(viewer) -> dict[str, bool]:
+    """Hide napari's native docks, returning their prior visibility for restore.
+
+    The returned mapping is opaque — pass it back to :func:`restore_native_docks`.
+    An empty mapping means nothing was hidden (and restore is a no-op).
+    """
+    qt = _qt_viewer(viewer)
+    if qt is None:
+        return {}
+    prior: dict[str, bool] = {}
+    for name in _NATIVE_DOCKS:
+        dock = getattr(qt, name, None)
+        if dock is None:
+            continue
+        try:
+            prior[name] = bool(dock.isVisible())
+            dock.setVisible(False)
+        except Exception:
+            logger.exception("could not hide native dock %s", name)
+    return prior
+
+
+def restore_native_docks(viewer, prior: dict[str, bool] | None) -> None:
+    """Restore docks hidden by :func:`hide_native_docks` to their prior state."""
+    if not prior:
+        return
+    qt = _qt_viewer(viewer)
+    if qt is None:
+        return
+    for name, was_visible in prior.items():
+        dock = getattr(qt, name, None)
+        if dock is None:
+            continue
+        try:
+            dock.setVisible(bool(was_visible))
+        except Exception:
+            logger.exception("could not restore native dock %s", name)
+
+
+__all__ = ["hide_native_docks", "restore_native_docks"]