From 0bc388c25414654c24a91c9c4d5e44233003f99b Mon Sep 17 00:00:00 2001
From: Christian Tabedzki <35670232+tabedzki@users.noreply.github.com>
Date: Thu, 29 Oct 2026 22:58:23 -0400
Subject: [PATCH 1/4] fix: download cold atlases off the event loop on atlas
switch
With an anatomy overlay on screen, picking a not-yet-cached atlas from
the dropdown live-recomputed the overlay synchronously
(_on_atlas_change -> _recompute_anatomy_if_active ->
compute_anatomy_overlay), so the atlas download ran on the Bokeh event
loop and froze every session and the healthcheck for 5-10 s per switch.
_recompute_anatomy_if_active now only draws inline when the atlas is
already local; otherwise it schedules the Compute button's async handler,
which downloads in a worker thread and redraws under the document lock.
The handler also keeps fetching until the currently selected atlas is
local, since the user can switch again mid-download and the subsequent
draw reads the dropdown, and it skips starting a second download while
one is in flight.
Assisted-by: ClaudeCode:claude-opus-5-5
---
pixelmap/gui/gui.py | 30 ++++++++-
tests/test_gui_overlays.py | 131 +++++++++++++++++++++++++++++++++++++
2 files changed, 159 insertions(+), 2 deletions(-)
diff --git a/pixelmap/gui/gui.py b/pixelmap/gui/gui.py
index 3b4f12b..49c84e0 100644
--- a/pixelmap/gui/gui.py
+++ b/pixelmap/gui/gui.py
@@ -1261,11 +1261,24 @@ async def _on_compute_anatomy_click(self, event):
if anatomy_atlas.is_downloaded(name):
self.compute_anatomy_overlay()
return
+ if self._anatomy_download_in_flight:
+ # The running download re-reads the dropdown when it finishes and
+ # fetches whatever is selected by then, so a second one is redundant.
+ return
+ self._anatomy_download_in_flight = True
self.compute_anatomy_button.name = "Downloading atlas… (first use only)"
self.compute_anatomy_button.disabled = True
try:
- await asyncio.to_thread(anatomy_atlas.ensure_downloaded, name)
+ # The atlas can change mid-download, and the draw below reads the
+ # dropdown, not ``name``: keep fetching until what is selected is
+ # what is local, or the draw would download it on the loop.
+ while True:
+ await asyncio.to_thread(anatomy_atlas.ensure_downloaded, name)
+ latest = str(self.atlas_name_input.value).strip()
+ if latest == name or anatomy_atlas.is_downloaded(latest):
+ break
+ name = latest
except Exception as exc: # noqa: BLE001 - any download failure is reported to the user
print(f"Atlas download failed: {exc}")
self.compute_anatomy_button.name = "Download & compute atlas 🧠 ⏳"
@@ -1275,6 +1288,7 @@ async def _on_compute_anatomy_click(self, event):
)
return
finally:
+ self._anatomy_download_in_flight = False
self.compute_anatomy_button.disabled = False
self.compute_anatomy_overlay()
@@ -1831,9 +1845,18 @@ def _recompute_anatomy_if_active(self, *events):
"""Re-run the overlay on input changes, but only once one exists."""
if getattr(self, "_suppress_anatomy_recompute", False):
return
- if getattr(self, "_anatomy_overlay_active", False):
+ if not getattr(self, "_anatomy_overlay_active", False):
+ return
+ if self._atlas_is_downloaded():
# compute_anatomy_overlay refreshes the depth readout on its way out.
self.compute_anatomy_overlay()
+ else:
+ # A cold atlas (typically just picked from the dropdown) would be
+ # downloaded inline by compute_anatomy_overlay — on the server that
+ # is the event loop, freezing every session for the whole fetch.
+ # Take the Compute button's route instead: download in a worker
+ # thread, then draw under the document lock.
+ pn.state.execute(functools.partial(self._on_compute_anatomy_click, None))
def _update_anatomy_legend(self, bands: list):
"""Render a deduplicated region legend on the right-side panel."""
@@ -2708,6 +2731,9 @@ def create_widgets(self):
# pose / bregma / squish / tilt input changes, so edits are visible
# immediately instead of only on the next Compute click.
self._anatomy_overlay_active = False
+ # Set while _on_compute_anatomy_click is fetching an atlas, so live
+ # updates arriving mid-download don't start a second one.
+ self._anatomy_download_in_flight = False
# atlas_name + bregma toggle do their own batched recompute (via
# _on_atlas_change / _on_bregma_toggle), so they're not in this list.
for _w in (self.tip_ap_input, self.tip_ml_input, self.tip_dv_input,
diff --git a/tests/test_gui_overlays.py b/tests/test_gui_overlays.py
index eae78dc..238f068 100644
--- a/tests/test_gui_overlays.py
+++ b/tests/test_gui_overlays.py
@@ -683,6 +683,137 @@ def _boom(name):
assert gui.compute_anatomy_button.name == "Download & compute atlas 🧠 ⏳"
+class TestAtlasSwitchNeverDownloadsOnTheEventLoop:
+ """Regression tests for a server-wide freeze on atlas switch.
+
+ With an overlay on screen, picking a not-yet-cached atlas from the dropdown
+ live-recomputed the overlay *synchronously* — so the multi-second atlas
+ download ran on the Bokeh event loop, freezing every session and the
+ healthcheck (the watchdog logged 5–10 s stalls in
+ ``_on_atlas_change → _recompute_anatomy_if_active → compute_anatomy_overlay``).
+ The Compute button already pushed downloads to a worker thread; the live
+ update path has to do the same.
+ """
+
+ COLD = "cold_gui_atlas"
+ COLDER = "colder_gui_atlas"
+
+ @pytest.fixture
+ def traced(self, posed_gui, monkeypatch):
+ """Record every atlas construction and download, with its thread.
+
+ Atlases in ``cold`` count as not downloaded until ``ensure_downloaded``
+ has fetched them; constructing one before then is exactly the inline
+ network fetch that froze the server.
+ """
+ events: list[tuple[str, str, threading.Thread]] = []
+ cold = {self.COLD, self.COLDER}
+ fake_atlas = atlas_module.BrainGlobeAtlas
+
+ class _TracingAtlas(fake_atlas):
+ def __init__(self, name, **kwargs):
+ events.append(("construct", name, threading.current_thread()))
+ super().__init__(name, **kwargs)
+
+ def _fake_download(name):
+ events.append(("download", name, threading.current_thread()))
+ cold.discard(name)
+
+ monkeypatch.setattr(atlas_module, "BrainGlobeAtlas", _TracingAtlas)
+ monkeypatch.setattr(atlas_module, "is_downloaded", lambda name=FAKE_ATLAS: name not in cold)
+ monkeypatch.setattr(atlas_module, "ensure_downloaded", _fake_download)
+ return posed_gui, events, cold
+
+ def _assert_downloaded_off_loop_before_use(self, events, name):
+ mine = [(kind, thread) for kind, n, thread in events if n == name]
+ assert mine, f"{name} was never downloaded or opened"
+ kind, thread = mine[0]
+ assert kind == "download", (
+ f"{name} was opened before being downloaded — on a cold cache that "
+ "is an inline network fetch"
+ )
+ assert thread is not threading.main_thread(), (
+ f"{name} was downloaded on the event loop thread"
+ )
+
+ def test_switching_to_a_cold_atlas_downloads_off_the_event_loop(self, traced):
+ gui, events, _cold = traced
+ gui.compute_anatomy_overlay()
+ assert gui._anatomy_overlay_active is True
+
+ gui.atlas_name_input.value = self.COLD
+
+ self._assert_downloaded_off_loop_before_use(events, self.COLD)
+ # And the overlay is redrawn for the new atlas once it has arrived.
+ assert gui._anatomy_overlay_active is True
+ assert len(gui.region_band_source.data["acronym"]) > 0
+ assert gui.compute_anatomy_button.disabled is False
+ assert gui.compute_anatomy_button.name == "Compute anatomical overlay 🧠"
+
+ def test_switching_again_mid_download_fetches_the_latest_off_the_loop(self, traced, monkeypatch):
+ """The atlas can change while the first download is still running.
+
+ The draw that follows a download reads the *current* dropdown value, so
+ it must not assume that is the atlas it just fetched.
+ """
+ gui, events, cold = traced
+ gui.compute_anatomy_overlay()
+
+ def _download_then_switch(name):
+ events.append(("download", name, threading.current_thread()))
+ cold.discard(name)
+ if name == self.COLD:
+ gui.atlas_name_input.value = self.COLDER # user picks again
+
+ monkeypatch.setattr(atlas_module, "ensure_downloaded", _download_then_switch)
+
+ gui.atlas_name_input.value = self.COLD
+
+ downloads = [n for kind, n, _t in events if kind == "download"]
+ assert downloads == [self.COLD, self.COLDER], (
+ "each atlas should be fetched exactly once, the second by the "
+ "in-flight download rather than a parallel or inline one"
+ )
+ self._assert_downloaded_off_loop_before_use(events, self.COLDER)
+ assert len(gui.region_band_source.data["acronym"]) > 0
+ assert gui.compute_anatomy_button.disabled is False
+
+ def test_a_failed_download_on_switch_leaves_the_button_usable(self, traced, monkeypatch):
+ gui, events, _cold = traced
+ gui.compute_anatomy_overlay()
+
+ def _boom(name):
+ raise ConnectionError("atlas host unreachable")
+
+ monkeypatch.setattr(atlas_module, "ensure_downloaded", _boom)
+
+ gui.atlas_name_input.value = self.COLD
+
+ assert not [e for e in events if e[1] == self.COLD and e[2] is threading.main_thread()]
+ assert gui.compute_anatomy_button.disabled is False
+ assert gui.compute_anatomy_button.name == "Download & compute atlas 🧠 ⏳"
+
+ def test_switching_to_a_cold_atlas_without_an_overlay_downloads_nothing(self, traced):
+ gui, events, _cold = traced
+ assert gui._anatomy_overlay_active is False
+
+ gui.atlas_name_input.value = self.COLD
+
+ assert not [e for e in events if e[1] == self.COLD]
+ assert gui.compute_anatomy_button.name == "Download & compute atlas 🧠 ⏳"
+
+ def test_switching_to_a_warm_atlas_still_recomputes_immediately(self, traced):
+ gui, events, cold = traced
+ gui.compute_anatomy_overlay()
+ cold.discard(self.COLD) # already on disk
+ gui.region_band_source.data = {k: [] for k in gui.region_band_source.data}
+
+ gui.atlas_name_input.value = self.COLD
+
+ assert not [e for e in events if e[0] == "download"]
+ assert len(gui.region_band_source.data["acronym"]) > 0
+
+
def test_no_unlocked_async_gui_callbacks():
"""Every async GUI callback needs the same treatment.
From d685694bb66b15a4c2ba132cd51338ac9d347440 Mon Sep 17 00:00:00 2001
From: Christian Tabedzki <35670232+tabedzki@users.noreply.github.com>
Date: Thu, 29 Oct 2026 23:13:09 -0400
Subject: [PATCH 2/4] fix: run every anatomy overlay compute off the event loop
The cold-atlas download was not the only thing blocking the Bokeh event
loop. Measured on cached atlases:
- Every live pose edit recomputed the overlay inline: 0.7 s on
allen_mouse_25um, 3.3 s on allen_mouse_10um, per keystroke.
- Switching to a human or fish atlas derived its anterior-commissure
origin inline, a whole-volume scan taking 0.8-7.7 s.
- Any on-loop annotation read could wait on _resident_lock, which
another session's download holds for its whole duration.
The overlay is now three steps: snapshot the widget inputs on the loop
(_anatomy_request), do every atlas read in a worker thread
(_compute_anatomy: bands, AC origin, locator render, tip depth), and
write Bokeh models back on the loop under the document lock
(_apply_anatomy, ~3 ms). _drain_anatomy_requests runs one compute per
session at a time and coalesces edits made during it. Clear bumps a
generation counter so a result that outlives its overlay is dropped,
and a failed download clears the stale overlay instead of retrying on
every later edit.
derive_origin_from_ac gets a hand-rolled memo plus
peek_origin_from_ac, so _origin_spec on the loop only reads the memo.
When no overlay is showing, switching to a cached AC atlas derives the
origin in a worker and fills the fields afterwards.
_region_fill_rgba builds one palette entry per distinct region and
gathers through np.unique's inverse index, instead of a full-slice mask
per region. That was 2.4 s of the 3.5 s render on a 10 um atlas; total
compute work is now 0.41 s / 1.16 s on allen_mouse_25um / 10um.
Assisted-by: ClaudeCode:claude-opus-5-5
---
pixelmap/anatomy/atlas.py | 41 ++-
pixelmap/anatomy/schematic.py | 21 +-
pixelmap/gui/gui.py | 468 ++++++++++++++++++++++----------
tests/test_anatomy_atlas.py | 43 +++
tests/test_anatomy_schematic.py | 50 ++++
tests/test_gui_overlays.py | 162 +++++++++++
6 files changed, 632 insertions(+), 153 deletions(-)
diff --git a/pixelmap/anatomy/atlas.py b/pixelmap/anatomy/atlas.py
index 7414015..aa9342e 100644
--- a/pixelmap/anatomy/atlas.py
+++ b/pixelmap/anatomy/atlas.py
@@ -574,14 +574,53 @@ def landmark_policy(name: str) -> str | None:
return None
-@functools.lru_cache(maxsize=8)
+#: Memo for :func:`derive_origin_from_ac`, insertion-ordered so the oldest
+#: entry is evicted first. Hand-rolled rather than ``lru_cache`` because
+#: :func:`peek_origin_from_ac` needs to ask "is this one known?" without
+#: computing it. Values are three floats, so the bound is about entries, not RAM.
+_ac_origin_memo: dict[str, tuple[float, float, float] | None] = {}
+_AC_ORIGIN_MEMO_SIZE = 8
+_MISSING = object()
+
+
def derive_origin_from_ac(name: str) -> tuple[float, float, float] | None:
"""Origin at the anterior-commissure decussation, from the annotation.
Returns canonical ``(AP, ML, DV)`` µm, or ``None`` if the atlas delineates
no anterior commissure. Same recipe used (and validated) for the WHS rat:
the AC's midline-crossing centroid. Requires the atlas (downloads if absent).
+
+ Slow the first time: it scans every voxel of the annotation (0.8 s for a
+ 25 µm atlas, ~8 s at 10 µm), so the GUI only ever calls it from a worker
+ thread and uses :func:`peek_origin_from_ac` on the event loop. Memoised
+ per atlas; exceptions are not cached, so a failed lookup is retried.
"""
+ cached = _ac_origin_memo.get(name, _MISSING)
+ if cached is not _MISSING:
+ return cached
+ origin = _derive_origin_from_ac(name)
+ _ac_origin_memo[name] = origin
+ while len(_ac_origin_memo) > _AC_ORIGIN_MEMO_SIZE:
+ _ac_origin_memo.pop(next(iter(_ac_origin_memo)))
+ return origin
+
+
+derive_origin_from_ac.cache_clear = _ac_origin_memo.clear
+
+
+def peek_origin_from_ac(name: str) -> tuple[bool, tuple[float, float, float] | None]:
+ """``(known, origin)`` for :func:`derive_origin_from_ac`, without computing it.
+
+ ``known`` is False until something has derived this atlas's origin.
+ Instant and touches no atlas data, so it is safe on the event loop.
+ """
+ cached = _ac_origin_memo.get(name, _MISSING)
+ if cached is _MISSING:
+ return False, None
+ return True, cached
+
+
+def _derive_origin_from_ac(name: str) -> tuple[float, float, float] | None:
atlas = get_atlas(name)
ac_ids = [int(s["id"]) for s in atlas.structures.values()
if "anterior" in s["name"].lower() and "commis" in s["name"].lower()]
diff --git a/pixelmap/anatomy/schematic.py b/pixelmap/anatomy/schematic.py
index b5c0f4c..6938d8f 100644
--- a/pixelmap/anatomy/schematic.py
+++ b/pixelmap/anatomy/schematic.py
@@ -58,16 +58,21 @@ def _region_rgb(atlas, region_id: int) -> tuple[int, int, int]:
def _region_fill_rgba(label_img: np.ndarray, atlas) -> np.ndarray:
- """Map a 2D label slice to an RGBA image colored by atlas region."""
- rgba = np.zeros((*label_img.shape, 4), dtype=float)
- for region_id in np.unique(label_img):
- if region_id == 0: # outside-brain / undefined
+ """Map a 2D label slice to an RGBA image colored by atlas region.
+
+ One color per *distinct* region, then a single gather through the inverse
+ index. Masking the slice once per region instead (the obvious loop) costs
+ a full pass per region — 2.4 s of a 3.5 s render on a 10 µm atlas, whose
+ slices hold hundreds of regions.
+ """
+ region_ids, inverse = np.unique(label_img, return_inverse=True)
+ palette = np.zeros((len(region_ids), 4), dtype=float)
+ for i, region_id in enumerate(region_ids):
+ if region_id == 0: # outside-brain / undefined: stays transparent
continue
r, g, b = _region_rgb(atlas, int(region_id))
- mask = label_img == region_id
- rgba[mask, :3] = (r / 255.0, g / 255.0, b / 255.0)
- rgba[mask, 3] = _REGION_ALPHA
- return rgba
+ palette[i] = (r / 255.0, g / 255.0, b / 255.0, _REGION_ALPHA)
+ return palette[inverse.reshape(label_img.shape)]
def _outline_rgba(label_img: np.ndarray) -> np.ndarray:
diff --git a/pixelmap/gui/gui.py b/pixelmap/gui/gui.py
index 49c84e0..8818394 100644
--- a/pixelmap/gui/gui.py
+++ b/pixelmap/gui/gui.py
@@ -124,6 +124,49 @@ def _darken_hex(hex_color: str, factor: float = 0.6) -> str:
return f"#{r:02x}{g:02x}{b:02x}"
+#: "Not supplied" marker for optional args where ``None`` is a real value.
+_UNSET = object()
+
+
+@dataclass(frozen=True)
+class _AnatomyRequest:
+ """Every input an overlay compute reads, snapshotted on the event loop.
+
+ The compute itself runs in a worker thread, which must not touch widgets:
+ Panel/Bokeh models are only safe to read and write under the document lock.
+ Capturing everything up front also pins the atlas, so a dropdown change
+ mid-compute can't make one render mix two atlases.
+ """
+
+ atlas_name: str
+ probe_xs: dict
+ plot_centers: dict
+ y_max: float
+ tip: tuple
+ pitch_deg: float
+ yaw_deg: float
+ shank_orientation_deg: float
+ width: float
+ label_offset: float
+ bregma_um: tuple | None
+ ap_squish: float
+ ml_squish: float
+ dv_squish: float
+ tilt_deg: float
+ origin_was_pending: bool
+ generation: int
+
+
+@dataclass
+class _AnatomyResult:
+ """What a worker-thread compute hands back for the loop to draw."""
+
+ bands: list | None = None
+ error: Exception | None = None
+ locator_html: str | None = None
+ tip_depth: float | None = None
+
+
###################################
#### Electrode selection logic ####
###################################
@@ -1234,17 +1277,19 @@ def _reposition_region_labels(self):
@pn.io.with_lock
async def _on_compute_anatomy_click(self, event):
- """Compute button: download off-thread if needed, then draw.
+ """Compute button: (re)draw the overlay without blocking the event loop.
- The download is the only part of the overlay that can block for
- seconds, and on the deployed server this callback runs on the Bokeh
- event loop — the same one serving every other session and the
- container healthcheck. So a cold atlas is fetched in a worker thread
- and only the (fast, in-memory) drawing happens back on the loop.
+ On the deployed server this callback runs on the Bokeh event loop —
+ the same one serving every other session and the container
+ healthcheck. Both halves of an overlay are slow there: a cold atlas
+ takes seconds to download, and even a cached one takes 0.7–3.3 s to
+ slice and render (measured, allen_mouse_25um → 10um). So all of it
+ happens in a worker thread (see :meth:`_drain_anatomy_requests`), and
+ only the drawing comes back to the loop.
``with_lock`` is not optional. Panel schedules async callbacks with
``nolock`` set unless the function carries ``lock = True``
- (``panel.io.server.async_execute``), and this method writes to Bokeh
+ (``panel.io.server.async_execute``), and the drawing writes to Bokeh
``ColumnDataSource`` models directly. Without the document lock every
such write raises "_pending_writes should be non-None ...", which
Bokeh turns into a *silently* dead overlay: the exception surfaces in
@@ -1255,85 +1300,215 @@ async def _on_compute_anatomy_click(self, event):
Bokeh holds the lock across the ``await`` rather than around each
statement (``ServerSession._needs_document_lock``), so this stays a
per-session lock: the event loop is free to serve other users while
- the download runs, and the session cannot be reaped mid-download.
+ the work runs, and the session cannot be reaped mid-compute.
"""
- name = str(self.atlas_name_input.value).strip()
- if anatomy_atlas.is_downloaded(name):
- self.compute_anatomy_overlay()
- return
- if self._anatomy_download_in_flight:
- # The running download re-reads the dropdown when it finishes and
- # fetches whatever is selected by then, so a second one is redundant.
+ self._anatomy_overlay_wanted = True
+ self._anatomy_dirty = True
+ await self._drain_anatomy_requests()
+
+ def _request_anatomy_recompute(self):
+ """Schedule an off-loop overlay recompute from a synchronous callback.
+
+ Coalesces: while a compute is in flight this only marks the overlay
+ dirty, and the running drain picks up the latest inputs when it
+ finishes, so a burst of edits costs one extra compute, not one each.
+ """
+ self._anatomy_dirty = True
+ if self._anatomy_compute_running:
return
+ pn.state.execute(self._drain_anatomy_requests)
- self._anatomy_download_in_flight = True
- self.compute_anatomy_button.name = "Downloading atlas… (first use only)"
- self.compute_anatomy_button.disabled = True
- try:
- # The atlas can change mid-download, and the draw below reads the
- # dropdown, not ``name``: keep fetching until what is selected is
- # what is local, or the draw would download it on the loop.
- while True:
- await asyncio.to_thread(anatomy_atlas.ensure_downloaded, name)
- latest = str(self.atlas_name_input.value).strip()
- if latest == name or anatomy_atlas.is_downloaded(latest):
- break
- name = latest
- except Exception as exc: # noqa: BLE001 - any download failure is reported to the user
- print(f"Atlas download failed: {exc}")
- self.compute_anatomy_button.name = "Download & compute atlas 🧠 ⏳"
- _notify(
- "error",
- f"Could not download '{name}'. Check your connection and retry.",
- )
+ @pn.io.with_lock
+ async def _drain_anatomy_requests(self):
+ """Run overlay computes in a worker thread until the inputs stop changing.
+
+ One drain per session at a time (``_anatomy_compute_running``); a
+ request arriving mid-compute sets ``_anatomy_dirty`` and is served by
+ the next lap. Each lap re-snapshots the widgets, so it always draws
+ the *current* pose and atlas — including an atlas picked while the
+ previous one was still downloading.
+ """
+ if self._anatomy_compute_running:
return
+ self._anatomy_compute_running = True
+ try:
+ while self._anatomy_dirty and self._anatomy_overlay_wanted:
+ self._anatomy_dirty = False
+ request = self._anatomy_request()
+ name = request.atlas_name
+ if not anatomy_atlas.is_downloaded(name):
+ self.compute_anatomy_button.name = "Downloading atlas… (first use only)"
+ self.compute_anatomy_button.disabled = True
+ try:
+ await asyncio.to_thread(anatomy_atlas.ensure_downloaded, name)
+ except Exception as exc: # noqa: BLE001 - any download failure is reported to the user
+ print(f"Atlas download failed: {exc}")
+ # Whatever is on screen is for another atlas now, and
+ # leaving the overlay live would retry the download on
+ # every later edit. Clicking Compute retries.
+ self.clear_anatomy_overlay()
+ self.compute_anatomy_button.name = "Download & compute atlas 🧠 ⏳"
+ _notify(
+ "error",
+ f"Could not download '{name}'. Check your connection and retry.",
+ )
+ return
+ if self._anatomy_dirty:
+ continue # inputs moved during the download: re-snapshot
+ result = await asyncio.to_thread(self._compute_anatomy, request)
+ self._apply_anatomy(request, result)
finally:
- self._anatomy_download_in_flight = False
+ self._anatomy_compute_running = False
self.compute_anatomy_button.disabled = False
- self.compute_anatomy_overlay()
def compute_anatomy_overlay(self):
- """Compute region bands for the current pose and render them."""
- atlas_name = str(self.atlas_name_input.value).strip()
- if not anatomy_atlas.is_downloaded(atlas_name):
+ """Compute region bands for the current pose and render them, inline.
+
+ Synchronous, so it blocks the calling thread for the whole compute (and
+ any download). Fine for scripts, notebooks and tests; GUI callbacks go
+ through :meth:`_request_anatomy_recompute` instead, which keeps the work
+ off the event loop.
+ """
+ self._anatomy_overlay_wanted = True
+ if not anatomy_atlas.is_downloaded(str(self.atlas_name_input.value).strip()):
self.compute_anatomy_button.name = "Downloading atlas… (first use only)"
self.compute_anatomy_button.disabled = True
+ request = self._anatomy_request()
+ self._apply_anatomy(request, self._compute_anatomy(request))
- probe_xs = self._shank_probe_xs()
- plot_centers = self._shank_plot_centers()
- y_max = float(self.positions_df["y"].max())
-
- # If the origin landmark was "pending" (AC of a not-yet-downloaded
- # atlas), computing below downloads it — remember to fill it in after.
- origin_was_pending = (
- self._origin_spec(self.atlas_name_input.value)["status"] == "ac_pending"
- )
-
- tip = self._tip_atlas_um()
-
+ def _anatomy_request(self) -> _AnatomyRequest:
+ """Snapshot the overlay's inputs. Event loop only; cheap, no atlas reads."""
+ atlas_name = str(self.atlas_name_input.value).strip()
+ width = self._shank_plot_width()
+ # Bregma dot whenever an estimate exists or we're in bregma mode (using
+ # the current, possibly-edited, values). DV-squish + tilt warp the brain
+ # image only in bregma mode (where the squish/tilt inputs are live).
+ bregma_mode = bool(self.bregma_relative_toggle.value)
+ status = self._origin_spec(atlas_name)["status"]
+ bregma_um = None
+ ap_squish = ml_squish = dv_squish = 1.0
+ tilt_deg = 0.0
+ if bregma_mode or status in ("defined", "estimate"):
+ bregma_um = (
+ float(self.bregma_ap_input.value),
+ float(self.bregma_ml_input.value),
+ float(self.bregma_dv_input.value),
+ )
+ if bregma_mode:
+ ap_squish = float(self.ap_squish_input.value) or 1.0
+ ml_squish = float(self.ml_squish_input.value) or 1.0
+ dv_squish = float(self.dv_squish_input.value) or 1.0
+ tilt_deg = float(self.tilt_input.value)
+ return _AnatomyRequest(
+ atlas_name=atlas_name,
+ probe_xs=self._shank_probe_xs(),
+ plot_centers=self._shank_plot_centers(),
+ y_max=float(self.positions_df["y"].max()),
+ tip=self._tip_atlas_um(),
+ pitch_deg=float(self.pitch_input.value),
+ yaw_deg=float(self.yaw_input.value),
+ shank_orientation_deg=float(self.shank_orientation_input.value),
+ width=width,
+ # Pull label text outside the shank outline so it doesn't overlap
+ # the electrode rects; the offset widens when a survey overlay is
+ # loaded so labels clear the survey sidebar bars.
+ label_offset=self._region_label_offset(width / 2),
+ bregma_um=bregma_um,
+ ap_squish=ap_squish,
+ ml_squish=ml_squish,
+ dv_squish=dv_squish,
+ tilt_deg=tilt_deg,
+ # An AC origin not yet located from the annotation (atlas not
+ # downloaded, or not derived yet): the compute locates it, and
+ # the apply step then fills it into the fields.
+ origin_was_pending=status == "ac_pending",
+ generation=self._anatomy_generation,
+ )
+
+ def _compute_anatomy(self, req: _AnatomyRequest) -> _AnatomyResult:
+ """Every atlas read an overlay needs. Runs in a worker thread.
+
+ Must not touch widgets or Bokeh models — only ``req`` and the atlas.
+ The one piece of session state it uses, ``_locator_fig``, is only ever
+ touched by the single in-flight compute.
+ """
try:
bands = compute_region_bands(
- shank_positions=probe_xs,
- y_range=(0.0, y_max),
- tip_atlas=tip,
- pitch_deg=float(self.pitch_input.value),
- yaw_deg=float(self.yaw_input.value),
- shank_orientation_deg=float(self.shank_orientation_input.value),
- atlas_name=atlas_name,
+ shank_positions=req.probe_xs,
+ y_range=(0.0, req.y_max),
+ tip_atlas=req.tip,
+ pitch_deg=req.pitch_deg,
+ yaw_deg=req.yaw_deg,
+ shank_orientation_deg=req.shank_orientation_deg,
+ atlas_name=req.atlas_name,
step_um=25.0,
)
except Exception as exc: # noqa: BLE001 - any lookup failure is reported to the user
- print(f"Anatomy lookup failed: {exc}")
+ return _AnatomyResult(error=exc)
+
+ result = _AnatomyResult(bands=bands)
+ if req.origin_was_pending:
+ # Scans the whole annotation (up to ~8 s on a 10 µm atlas), which
+ # is why _origin_spec never does it itself; memoised, so the apply
+ # step's _origin_spec then answers from the cache.
+ try:
+ anatomy_atlas.derive_origin_from_ac(req.atlas_name)
+ except Exception as exc: # noqa: BLE001 - AC not derivable: _origin_spec reports it
+ print(f"Anterior-commissure lookup failed: {exc}")
+ try:
+ # Reuse this session's figure: building one per render cost 3.1 MB
+ # of RSS per overlay compute, and the overlay recomputes on every
+ # pose edit.
+ fig = render_locator(
+ req.atlas_name,
+ tip_atlas=req.tip,
+ pitch_deg=req.pitch_deg,
+ yaw_deg=req.yaw_deg,
+ shank_orientation_deg=req.shank_orientation_deg,
+ shank_positions=req.probe_xs,
+ y_range=(0.0, req.y_max),
+ bregma_um=req.bregma_um,
+ ap_squish=req.ap_squish,
+ ml_squish=req.ml_squish,
+ dv_squish=req.dv_squish,
+ tilt_deg=req.tilt_deg,
+ fig=self._locator_fig,
+ )
+ self._locator_fig = fig
+ result.locator_html = self._fig_to_locator_html(fig)
+ except Exception as exc: # noqa: BLE001 - a failed locator shouldn't sink the overlay
+ print(f"Locator render failed: {exc}")
+ try:
+ result.tip_depth = tip_depth_below_surface_um(
+ req.tip,
+ pitch_deg=req.pitch_deg,
+ yaw_deg=req.yaw_deg,
+ atlas_name=req.atlas_name,
+ )
+ except Exception as exc: # noqa: BLE001 - a readout must never sink the GUI
+ print(f"Tip depth lookup failed: {exc}")
+
+ # Hand back the chunk buffers this render churned through. They are
+ # already freed; this is what unmaps them, so repeated overlay computes
+ # don't ratchet RSS upward for the life of the process.
+ anatomy_atlas.reclaim_free_memory()
+ return result
+
+ def _apply_anatomy(self, req: _AnatomyRequest, result: _AnatomyResult):
+ """Draw a finished compute. Event loop only (writes Bokeh models)."""
+ if req.generation != self._anatomy_generation or not self._anatomy_overlay_wanted:
+ return # cleared while computing: drop the stale result
+ if result.error is not None:
+ print(f"Anatomy lookup failed: {result.error}")
self.compute_anatomy_button.name = "Compute anatomical overlay 🧠"
self.compute_anatomy_button.disabled = False
return
- width = self._shank_plot_width()
+ bands = result.bands
+ width = req.width
half_width = width / 2
- # Pull label text outside the shank outline so it doesn't overlap the
- # electrode rects; the offset widens when a survey overlay is loaded so
- # labels clear the survey sidebar bars (see _region_label_offset).
- label_offset = self._region_label_offset(half_width)
+ label_offset = req.label_offset
+ plot_centers = req.plot_centers
band_data = {"x": [], "y": [], "width": [], "height": [], "color": [], "acronym": []}
label_data = {"x": [], "y": [], "text": [], "color": [], "center": []}
@@ -1380,60 +1555,8 @@ def compute_anatomy_overlay(self):
self._update_anatomy_legend(bands)
# The atlas is now downloaded, so the origin corner can be shown.
self._update_anatomy_origin_note()
-
- # Bregma dot whenever an estimate exists or we're in bregma mode (using
- # the current, possibly-edited, values). DV-squish + tilt warp the brain
- # image only in bregma mode (where the squish/tilt inputs are live).
- bregma_mode = bool(self.bregma_relative_toggle.value)
- # The atlas is downloaded now (bands were computed), so a previously
- # "pending" AC landmark can be filled in (without clobbering user edits).
- if origin_was_pending:
- self._update_reference_params()
- self.bregma_estimate_header.object = self._bregma_header_html()
- has_origin = self._origin_spec(atlas_name)["status"] in ("defined", "estimate")
- bregma_um = None
- ap_squish = ml_squish = dv_squish = 1.0
- tilt_deg = 0.0
- if bregma_mode or has_origin:
- bregma_um = (
- float(self.bregma_ap_input.value),
- float(self.bregma_ml_input.value),
- float(self.bregma_dv_input.value),
- )
- if bregma_mode:
- ap_squish = float(self.ap_squish_input.value) or 1.0
- ml_squish = float(self.ml_squish_input.value) or 1.0
- dv_squish = float(self.dv_squish_input.value) or 1.0
- tilt_deg = float(self.tilt_input.value)
-
- try:
- # Reuse this session's figure: building one per render cost 3.1 MB
- # of RSS per overlay compute, and the overlay recomputes on every
- # pose edit.
- _fig = render_locator(
- atlas_name,
- tip_atlas=tip,
- pitch_deg=float(self.pitch_input.value),
- yaw_deg=float(self.yaw_input.value),
- shank_orientation_deg=float(self.shank_orientation_input.value),
- shank_positions=probe_xs,
- y_range=(0.0, y_max),
- bregma_um=bregma_um,
- ap_squish=ap_squish,
- ml_squish=ml_squish,
- dv_squish=dv_squish,
- tilt_deg=tilt_deg,
- fig=self._locator_fig,
- )
- self._locator_fig = _fig
- self.anatomy_locator.object = self._fig_to_locator_html(_fig)
- except Exception as exc: # noqa: BLE001 - a failed locator shouldn't sink the overlay
- print(f"Locator render failed: {exc}")
-
- # Hand back the chunk buffers this render churned through. They are
- # already freed; this is what unmaps them, so repeated overlay computes
- # don't ratchet RSS upward for the life of the process.
- anatomy_atlas.reclaim_free_memory()
+ if result.locator_html is not None:
+ self.anatomy_locator.object = result.locator_html
# Overlay now exists → later input edits live-update it.
self._anatomy_overlay_active = True
@@ -1441,13 +1564,29 @@ def compute_anatomy_overlay(self):
# Only now can the depth readout show a value: the overlay is up, and
# computing it downloaded the atlas if it wasn't already cached (the
# readout refuses to trigger a download itself).
- self._update_tip_depth_readout()
+ self._set_tip_depth_readout(result.tip_depth)
self.compute_anatomy_button.name = "Compute anatomical overlay 🧠"
self.compute_anatomy_button.disabled = False
+ # The compute located a previously "pending" AC landmark: fill it in
+ # (without clobbering user edits), then redraw once more so the locator
+ # shows the origin dot this render was computed without.
+ if req.origin_was_pending and self._origin_spec(req.atlas_name)["status"] != "ac_pending":
+ self._suppress_anatomy_recompute = True
+ try:
+ self._update_reference_params()
+ finally:
+ self._suppress_anatomy_recompute = False
+ self.bregma_estimate_header.object = self._bregma_header_html()
+ self._request_anatomy_recompute()
+
def clear_anatomy_overlay(self):
"""Wipe the region bands, labels, boundaries and reset the legend."""
self._anatomy_overlay_active = False # stop live-updating
+ # Any compute still in flight finishes in its worker thread, but its
+ # result is for an overlay the user just dismissed: drop it.
+ self._anatomy_overlay_wanted = False
+ self._anatomy_generation += 1
self.region_band_source.data = {
"x": [], "y": [], "width": [], "height": [], "color": [], "acronym": [],
}
@@ -1568,10 +1707,40 @@ def _on_atlas_change(self, *events):
self._suppress_anatomy_recompute = False
# Reflect download state in the button label so users know before clicking.
name = str(self.atlas_name_input.value).strip()
- if anatomy_atlas.is_downloaded(name):
+ downloaded = anatomy_atlas.is_downloaded(name)
+ if downloaded:
self.compute_anatomy_button.name = "Compute anatomical overlay 🧠"
else:
self.compute_anatomy_button.name = "Download & compute atlas 🧠 ⏳"
+ if getattr(self, "_anatomy_overlay_wanted", False):
+ # The recompute locates a pending AC origin on its way through.
+ self._recompute_anatomy_if_active()
+ elif downloaded and self._origin_spec(name)["status"] == "ac_pending":
+ # No overlay to do it, but the atlas is local, so the origin can be
+ # shown now — once a worker thread has scanned for it.
+ pn.state.execute(functools.partial(self._locate_ac_origin_off_loop, name))
+
+ @pn.io.with_lock
+ async def _locate_ac_origin_off_loop(self, name: str):
+ """Derive an atlas's AC origin in a worker thread, then fill the fields.
+
+ The derivation reads every voxel of the annotation (~8 s on a 10 µm
+ atlas), so it must not run on the event loop the way it used to on
+ every switch to a human or fish atlas.
+ """
+ try:
+ await asyncio.to_thread(anatomy_atlas.derive_origin_from_ac, name)
+ except Exception as exc: # noqa: BLE001 - AC not derivable: banner stays "pending"
+ print(f"Anterior-commissure lookup failed: {exc}")
+ return
+ if str(self.atlas_name_input.value).strip() != name:
+ return # the user has moved on to another atlas
+ self._suppress_anatomy_recompute = True
+ try:
+ self._update_reference_params()
+ finally:
+ self._suppress_anatomy_recompute = False
+ self.bregma_estimate_header.object = self._bregma_header_html()
self._recompute_anatomy_if_active()
def _update_landmark_labels(self):
@@ -1664,13 +1833,16 @@ def _tip_depth_below_surface(self) -> float | None:
print(f"Tip depth lookup failed: {exc}")
return None
- def _tip_depth_readout_html(self) -> str:
+ def _tip_depth_readout_html(self, depth=_UNSET) -> str:
"""Banner text for the depth-below-surface readout above the tip fields.
Blank until an overlay exists: before Compute (or after Clear) there is
no anatomy on screen for a depth to refer to, and a number sitting there
would look like a live measurement of a pose nothing has been checked
against.
+
+ ``depth`` is the value an off-loop overlay compute already measured;
+ omitted, it is looked up here, which reads the atlas on this thread.
"""
if not getattr(self, "_anatomy_overlay_active", False):
value_html = (
@@ -1685,7 +1857,8 @@ def _tip_depth_readout_html(self) -> str:
"(available once the atlas is downloaded)"
)
else:
- depth = self._tip_depth_below_surface()
+ if depth is _UNSET:
+ depth = self._tip_depth_below_surface()
if depth is None:
value_html = (
'—'
@@ -1717,6 +1890,12 @@ def _update_tip_depth_readout(self, *events):
return
self.tip_depth_readout.object = self._tip_depth_readout_html()
+ def _set_tip_depth_readout(self, depth: float | None):
+ """Show a depth measured elsewhere (by the off-loop overlay compute)."""
+ if not hasattr(self, "tip_depth_readout"):
+ return
+ self.tip_depth_readout.object = self._tip_depth_readout_html(depth)
+
def _atlas_tip_center(self, name: str):
"""Atlas center as ``(AP, ML, DV)`` µm, or ``None`` if not readable cheaply.
@@ -1787,14 +1966,14 @@ def _origin_spec(self, name) -> dict:
return spec # no skull landmark for this species → user defines origin
spec["landmark"] = landmark
if landmark == "anterior commissure":
- # Human (AC-PC): derive it from the annotation when downloaded.
- if not anatomy_atlas.is_downloaded(name):
+ # Human (AC-PC): derived from the annotation, but only ever off the
+ # event loop — it scans the whole volume (up to ~8 s). Until that
+ # has happened (see _locate_ac_origin_off_loop and the overlay
+ # compute) report it as pending.
+ known, ac = anatomy_atlas.peek_origin_from_ac(name)
+ if not known:
spec["status"] = "ac_pending"
return spec
- try:
- ac = anatomy_atlas.derive_origin_from_ac(name)
- except Exception: # noqa: BLE001 - AC not derivable: handled as ac is None below
- ac = None
if ac is None:
# AC is the convention but this atlas doesn't delineate it
# (e.g. the coarse human atlas) → keep the name, user sets it.
@@ -1845,18 +2024,14 @@ def _recompute_anatomy_if_active(self, *events):
"""Re-run the overlay on input changes, but only once one exists."""
if getattr(self, "_suppress_anatomy_recompute", False):
return
- if not getattr(self, "_anatomy_overlay_active", False):
- return
- if self._atlas_is_downloaded():
- # compute_anatomy_overlay refreshes the depth readout on its way out.
- self.compute_anatomy_overlay()
- else:
- # A cold atlas (typically just picked from the dropdown) would be
- # downloaded inline by compute_anatomy_overlay — on the server that
- # is the event loop, freezing every session for the whole fetch.
- # Take the Compute button's route instead: download in a worker
- # thread, then draw under the document lock.
- pn.state.execute(functools.partial(self._on_compute_anatomy_click, None))
+ # "Wanted", not "active": edits made while the first compute is still
+ # running must reach it too, or it draws an outdated pose or atlas.
+ if getattr(self, "_anatomy_overlay_wanted", False):
+ # Never inline: on the server this watcher runs on the event loop,
+ # and a recompute is a download for a cold atlas (just picked from
+ # the dropdown) and 0.7–3.3 s of slicing and rendering even for a
+ # cached one. Either froze every session; this runs it off-loop.
+ self._request_anatomy_recompute()
def _update_anatomy_legend(self, bands: list):
"""Render a deduplicated region legend on the right-side panel."""
@@ -2731,9 +2906,14 @@ def create_widgets(self):
# pose / bregma / squish / tilt input changes, so edits are visible
# immediately instead of only on the next Compute click.
self._anatomy_overlay_active = False
- # Set while _on_compute_anatomy_click is fetching an atlas, so live
- # updates arriving mid-download don't start a second one.
- self._anatomy_download_in_flight = False
+ # Off-loop compute bookkeeping (see _drain_anatomy_requests): whether
+ # the user asked for an overlay, whether its inputs changed since the
+ # last compute started, whether a compute is running, and a counter
+ # bumped by Clear so a compute that outlives its overlay is dropped.
+ self._anatomy_overlay_wanted = False
+ self._anatomy_dirty = False
+ self._anatomy_compute_running = False
+ self._anatomy_generation = 0
# atlas_name + bregma toggle do their own batched recompute (via
# _on_atlas_change / _on_bregma_toggle), so they're not in this list.
for _w in (self.tip_ap_input, self.tip_ml_input, self.tip_dv_input,
diff --git a/tests/test_anatomy_atlas.py b/tests/test_anatomy_atlas.py
index f6b0826..a37ace4 100644
--- a/tests/test_anatomy_atlas.py
+++ b/tests/test_anatomy_atlas.py
@@ -187,6 +187,49 @@ def test_derive_origin_from_ac_none_without_ac(self, monkeypatch):
atlas_module.derive_origin_from_ac.cache_clear()
assert atlas_module.derive_origin_from_ac("y") is None
+ def test_peek_reports_unknown_until_derived(self, monkeypatch):
+ """The event loop asks ``peek``; only a worker thread pays for the scan."""
+ calls = []
+ monkeypatch.setattr(atlas_module, "_derive_origin_from_ac",
+ lambda name: calls.append(name) or (1.0, 2.0, 3.0))
+
+ assert atlas_module.peek_origin_from_ac("a") == (False, None)
+ assert calls == [], "peeking must never compute"
+ assert atlas_module.derive_origin_from_ac("a") == (1.0, 2.0, 3.0)
+ assert atlas_module.peek_origin_from_ac("a") == (True, (1.0, 2.0, 3.0))
+ assert atlas_module.derive_origin_from_ac("a") == (1.0, 2.0, 3.0)
+ assert calls == ["a"], "a derived origin is memoised"
+
+ def test_peek_distinguishes_no_ac_from_not_yet_derived(self, monkeypatch):
+ monkeypatch.setattr(atlas_module, "_derive_origin_from_ac", lambda name: None)
+ assert atlas_module.peek_origin_from_ac("b") == (False, None)
+ assert atlas_module.derive_origin_from_ac("b") is None
+ assert atlas_module.peek_origin_from_ac("b") == (True, None)
+
+ def test_a_failed_derivation_is_not_memoised(self, monkeypatch):
+ def _boom(name):
+ raise OSError("annotation unreadable")
+
+ monkeypatch.setattr(atlas_module, "_derive_origin_from_ac", _boom)
+ with pytest.raises(OSError):
+ atlas_module.derive_origin_from_ac("c")
+ assert atlas_module.peek_origin_from_ac("c") == (False, None)
+
+ def test_origin_memo_is_bounded_and_evicts_oldest_first(self, monkeypatch):
+ monkeypatch.setattr(atlas_module, "_derive_origin_from_ac", lambda name: (0.0, 0.0, 0.0))
+ size = atlas_module._AC_ORIGIN_MEMO_SIZE
+ for i in range(size + 1):
+ atlas_module.derive_origin_from_ac(f"atlas{i}")
+ assert atlas_module.peek_origin_from_ac("atlas0") == (False, None)
+ assert atlas_module.peek_origin_from_ac(f"atlas{size}")[0] is True
+ assert len(atlas_module._ac_origin_memo) == size
+
+ def test_cache_clear_forgets_derived_origins(self, monkeypatch):
+ monkeypatch.setattr(atlas_module, "_derive_origin_from_ac", lambda name: (0.0, 0.0, 0.0))
+ atlas_module.derive_origin_from_ac("d")
+ atlas_module.derive_origin_from_ac.cache_clear()
+ assert atlas_module.peek_origin_from_ac("d") == (False, None)
+
def test_lookup_resolves_through_ap_flip(self, monkeypatch):
# "psr" reverses AP: a marker at the native posterior pole (index 0) must
# be read at large canonical AP, not at AP=0 (the anterior pole).
diff --git a/tests/test_anatomy_schematic.py b/tests/test_anatomy_schematic.py
index c965770..4710dfa 100644
--- a/tests/test_anatomy_schematic.py
+++ b/tests/test_anatomy_schematic.py
@@ -93,6 +93,56 @@ def test_region_fill_uses_atlas_colors(fake_brainglobe):
assert rgba[0, 1, 3] > 0 and rgba[0, 2, 3] > 0
+def _region_fill_rgba_reference(label_img, atlas):
+ """The original one-mask-per-region implementation, kept as an oracle."""
+ rgba = np.zeros((*label_img.shape, 4), dtype=float)
+ for region_id in np.unique(label_img):
+ if region_id == 0:
+ continue
+ r, g, b = schematic_module._region_rgb(atlas, int(region_id))
+ mask = label_img == region_id
+ rgba[mask, :3] = (r / 255.0, g / 255.0, b / 255.0)
+ rgba[mask, 3] = schematic_module._REGION_ALPHA
+ return rgba
+
+
+class TestRegionFillMatchesThePerRegionLoop:
+ """The fill is vectorised: it used to build one full-slice mask per region,
+ which was 2.4 s of every 3.5 s live update on allen_mouse_10um."""
+
+ def test_unknown_region_ids_fall_back_to_gray(self, fake_brainglobe):
+ atlas = _FakeAtlas("fake")
+ rgba = schematic_module._region_fill_rgba(np.array([[0, 99]], dtype=np.int32), atlas)
+ np.testing.assert_allclose(rgba[0, 1, :3], (200 / 255,) * 3)
+ assert rgba[0, 1, 3] == schematic_module._REGION_ALPHA
+
+ def test_an_all_outside_slice_is_fully_transparent(self, fake_brainglobe):
+ rgba = schematic_module._region_fill_rgba(np.zeros((3, 4), dtype=np.int32),
+ _FakeAtlas("fake"))
+ assert rgba.shape == (3, 4, 4)
+ assert not rgba.any()
+
+ def test_an_empty_slice_gives_an_empty_image(self, fake_brainglobe):
+ rgba = schematic_module._region_fill_rgba(np.zeros((0, 5), dtype=np.int32),
+ _FakeAtlas("fake"))
+ assert rgba.shape == (0, 5, 4)
+
+ @pytest.mark.parametrize("dtype", [np.int32, np.uint32, np.int64, np.uint16])
+ def test_many_regions_match_the_reference(self, fake_brainglobe, dtype):
+ atlas = _FakeAtlas("fake")
+ rng = np.random.default_rng(0)
+ ids = np.array([0, 1, 2, 7, 500, 60_000], dtype=dtype) # 7, 500, 60k: unknown
+ label_img = rng.choice(ids, size=(40, 30)).astype(dtype)
+ atlas.structures = {
+ **atlas.structures,
+ 500: {"acronym": "X", "name": "X", "rgb_triplet": [10, 20, 30]},
+ }
+ np.testing.assert_array_equal(
+ schematic_module._region_fill_rgba(label_img, atlas),
+ _region_fill_rgba_reference(label_img, atlas),
+ )
+
+
def test_outline_marks_region_boundaries(fake_brainglobe):
label_img = np.array([[1, 1, 2, 2]], dtype=np.int32)
outline = schematic_module._outline_rgba(label_img)
diff --git a/tests/test_gui_overlays.py b/tests/test_gui_overlays.py
index 238f068..462fcf5 100644
--- a/tests/test_gui_overlays.py
+++ b/tests/test_gui_overlays.py
@@ -22,6 +22,7 @@
from pixelmap.anatomy import atlas as atlas_module
from pixelmap.anatomy import regions as regions_module
+from pixelmap.gui import gui as gui_module
from pixelmap.gui.gui import ChannelmapGUI
from pixelmap.types import Electrode
@@ -814,6 +815,167 @@ def test_switching_to_a_warm_atlas_still_recomputes_immediately(self, traced):
assert len(gui.region_band_source.data["acronym"]) > 0
+class TestOverlayComputeRunsOffTheEventLoop:
+ """Regression tests: even a *cached* atlas froze the server on every edit.
+
+ Slicing the annotation and rendering the locator takes 0.7 s per overlay
+ compute on allen_mouse_25um and 3.3 s on allen_mouse_10um (measured), and
+ the overlay recomputes on every pose keystroke — all of it on the Bokeh
+ event loop that serves every session. Locating an anterior-commissure
+ origin scans the whole volume (0.8–8 s), and ran on the loop on every
+ switch to a human or fish atlas. All of these must happen in a worker.
+ """
+
+ @pytest.fixture
+ def threads(self, monkeypatch):
+ """Record which thread each atlas-reading step of the overlay runs on."""
+ seen: dict[str, list[threading.Thread]] = {}
+
+ def _tracing(label, fn):
+ def wrapper(*args, **kwargs):
+ seen.setdefault(label, []).append(threading.current_thread())
+ return fn(*args, **kwargs)
+ return wrapper
+
+ for label in ("compute_region_bands", "render_locator", "tip_depth_below_surface_um"):
+ monkeypatch.setattr(gui_module, label, _tracing(label, getattr(gui_module, label)))
+ return seen
+
+ @staticmethod
+ def _assert_off_loop(seen, *labels):
+ for label in labels:
+ assert seen.get(label), f"{label} never ran"
+ assert all(t is not threading.main_thread() for t in seen[label]), (
+ f"{label} ran on the event loop thread"
+ )
+
+ def test_a_live_pose_edit_computes_off_the_event_loop(self, posed_gui, threads):
+ posed_gui.compute_anatomy_overlay()
+ before = list(posed_gui.region_band_source.data["y"])
+ threads.clear()
+
+ posed_gui.tip_dv_input.value = 2200.0
+
+ self._assert_off_loop(threads, "compute_region_bands", "render_locator",
+ "tip_depth_below_surface_um")
+ assert list(posed_gui.region_band_source.data["y"]) != before
+ # 2200 µm tip, surface at ≈ 987.5 µm → ≈ 1212 µm below it.
+ assert "1,2" in posed_gui.tip_depth_readout.object
+
+ def test_clicking_compute_on_a_cached_atlas_computes_off_the_loop(self, served, threads):
+ gui, session = served
+
+ asyncio.run(session.with_document_locked(gui._on_compute_anatomy_click, None))
+
+ self._assert_off_loop(threads, "compute_region_bands", "render_locator")
+ assert len(gui.region_band_source.data["acronym"]) > 0
+ assert gui.compute_anatomy_button.disabled is False
+
+ def test_edits_during_a_compute_are_coalesced_into_one_more(self, posed_gui, monkeypatch):
+ """A burst of keystrokes must not queue one multi-second compute each."""
+ posed_gui.compute_anatomy_overlay()
+ real = gui_module.compute_region_bands
+ tips = []
+
+ def _slow_bands(**kwargs):
+ tips.append(kwargs["tip_atlas"][2])
+ if len(tips) == 1: # the user keeps typing while this one runs
+ for dv in (2100.0, 2200.0, 2300.0):
+ posed_gui.tip_dv_input.value = dv
+ return real(**kwargs)
+
+ monkeypatch.setattr(gui_module, "compute_region_bands", _slow_bands)
+
+ posed_gui.tip_dv_input.value = 2000.0
+
+ assert tips == [2000.0, 2300.0], "expected the first edit, then only the latest"
+ assert posed_gui._anatomy_compute_running is False
+
+ def test_clearing_mid_compute_discards_the_result(self, posed_gui, monkeypatch):
+ posed_gui.compute_anatomy_overlay()
+ real = gui_module.compute_region_bands
+
+ def _cleared_meanwhile(**kwargs):
+ bands = real(**kwargs)
+ posed_gui.clear_anatomy_overlay() # the user clicks Clear
+ return bands
+
+ monkeypatch.setattr(gui_module, "compute_region_bands", _cleared_meanwhile)
+
+ posed_gui.tip_dv_input.value = 2200.0
+
+ assert posed_gui._anatomy_overlay_active is False
+ assert posed_gui.region_band_source.data["x"] == []
+ assert posed_gui.anatomy_locator.object == ""
+
+ def test_a_lookup_failure_leaves_the_button_usable(self, posed_gui, monkeypatch):
+ posed_gui.compute_anatomy_overlay()
+
+ def _boom(**kwargs):
+ raise ValueError("bad pose")
+
+ monkeypatch.setattr(gui_module, "compute_region_bands", _boom)
+
+ posed_gui.tip_dv_input.value = 2200.0
+
+ assert posed_gui._anatomy_compute_running is False
+ assert posed_gui.compute_anatomy_button.disabled is False
+ assert posed_gui.compute_anatomy_button.name == "Compute anatomical overlay 🧠"
+
+
+class TestAnteriorCommissureOriginIsLocatedOffTheEventLoop:
+ """Human and fish atlases use the AC as origin; finding it scans every voxel."""
+
+ AC_ATLAS = "fake_zfish_atlas" # "zfish" → anterior-commissure landmark
+ AC_ORIGIN = (100.0, 200.0, 300.0) # (AP, ML, DV) µm
+
+ @pytest.fixture
+ def ac_threads(self, posed_gui, monkeypatch):
+ seen: list[threading.Thread] = []
+
+ def _derive(name):
+ seen.append(threading.current_thread())
+ return self.AC_ORIGIN
+
+ atlas_module.derive_origin_from_ac.cache_clear()
+ monkeypatch.setattr(atlas_module, "_derive_origin_from_ac", _derive)
+ yield posed_gui, seen
+ atlas_module.derive_origin_from_ac.cache_clear()
+
+ def _assert_origin_filled(self, gui):
+ assert (gui.bregma_ap_input.value, gui.bregma_ml_input.value,
+ gui.bregma_dv_input.value) == self.AC_ORIGIN
+ assert "anterior commissure (defined)" in gui.bregma_estimate_header.object
+
+ def test_switching_to_a_cached_ac_atlas_derives_it_off_the_loop(self, ac_threads):
+ gui, seen = ac_threads
+ assert gui._anatomy_overlay_active is False
+
+ gui.atlas_name_input.value = self.AC_ATLAS
+
+ assert seen, "the AC origin was never located"
+ assert all(t is not threading.main_thread() for t in seen), (
+ "the whole-volume AC scan ran on the event loop thread"
+ )
+ self._assert_origin_filled(gui)
+
+ def test_with_an_overlay_the_recompute_derives_it_off_the_loop(self, ac_threads):
+ gui, seen = ac_threads
+ gui.compute_anatomy_overlay()
+
+ gui.atlas_name_input.value = self.AC_ATLAS
+
+ assert seen and all(t is not threading.main_thread() for t in seen)
+ self._assert_origin_filled(gui)
+ assert len(gui.region_band_source.data["acronym"]) > 0
+
+ def test_origin_spec_never_scans_on_its_own(self, ac_threads):
+ """It runs on the loop several times per switch, so it may only peek."""
+ gui, seen = ac_threads
+ assert gui._origin_spec(self.AC_ATLAS)["status"] == "ac_pending"
+ assert seen == []
+
+
def test_no_unlocked_async_gui_callbacks():
"""Every async GUI callback needs the same treatment.
From 7504f2b78469c9e3ce180660a40ebf4ad47d8275 Mon Sep 17 00:00:00 2001
From: Christian Tabedzki <35670232+tabedzki@users.noreply.github.com>
Date: Thu, 29 Oct 2026 23:21:40 -0400
Subject: [PATCH 3/4] refactor: simplify off-loop anatomy pipeline after review
- Locate a pending AC origin in the drain before the snapshot, so a lap
draws with the origin. This drops origin_was_pending, the derive in
_compute_anatomy, and the extra fill-and-recompute lap in
_apply_anatomy, which cost a full 0.7-3.3 s recompute on the first
overlay for a human or fish atlas.
- Merge the two AC paths into one _locate_ac_origin coroutine and a
_fill_reference_params helper.
- Make derive_origin_from_ac single-flight per atlas name, so concurrent
callers wait on the running scan instead of starting another.
- Fold _anatomy_overlay_wanted into _anatomy_overlay_active, now set on
Compute rather than on the first draw.
- Pass the tip depth into one _update_tip_depth_readout(depth) and drop
the _UNSET sentinel, _set_tip_depth_readout, and the readout's on-loop
atlas read. Share the lookup and error handling via
_measure_tip_depth.
- Add button-label constants, _refresh_compute_button, and an
_anatomy_recompute_suppressed() context manager. Drop dead button
writes from the sync compute_anatomy_overlay.
- Tests: reset the AC memo in the layered_atlas fixture, share one
_assert_off_loop helper, and add a single-flight test.
Assisted-by: ClaudeCode:claude-opus-5-5
---
pixelmap/anatomy/atlas.py | 21 +++-
pixelmap/gui/gui.py | 238 ++++++++++++++++--------------------
tests/test_anatomy_atlas.py | 23 ++++
tests/test_gui_overlays.py | 36 +++---
4 files changed, 160 insertions(+), 158 deletions(-)
diff --git a/pixelmap/anatomy/atlas.py b/pixelmap/anatomy/atlas.py
index aa9342e..cca4c93 100644
--- a/pixelmap/anatomy/atlas.py
+++ b/pixelmap/anatomy/atlas.py
@@ -581,6 +581,10 @@ def landmark_policy(name: str) -> str | None:
_ac_origin_memo: dict[str, tuple[float, float, float] | None] = {}
_AC_ORIGIN_MEMO_SIZE = 8
_MISSING = object()
+#: One lock per atlas name, so concurrent callers (several sessions, or a quick
+#: A→B→A switch) wait for the scan already running instead of starting another.
+_ac_origin_locks: dict[str, threading.Lock] = {}
+_ac_origin_locks_guard = threading.Lock()
def derive_origin_from_ac(name: str) -> tuple[float, float, float] | None:
@@ -593,15 +597,22 @@ def derive_origin_from_ac(name: str) -> tuple[float, float, float] | None:
Slow the first time: it scans every voxel of the annotation (0.8 s for a
25 µm atlas, ~8 s at 10 µm), so the GUI only ever calls it from a worker
thread and uses :func:`peek_origin_from_ac` on the event loop. Memoised
- per atlas; exceptions are not cached, so a failed lookup is retried.
+ per atlas and single-flight per name; exceptions are not cached, so a
+ failed lookup is retried.
"""
cached = _ac_origin_memo.get(name, _MISSING)
if cached is not _MISSING:
return cached
- origin = _derive_origin_from_ac(name)
- _ac_origin_memo[name] = origin
- while len(_ac_origin_memo) > _AC_ORIGIN_MEMO_SIZE:
- _ac_origin_memo.pop(next(iter(_ac_origin_memo)))
+ with _ac_origin_locks_guard:
+ lock = _ac_origin_locks.setdefault(name, threading.Lock())
+ with lock:
+ cached = _ac_origin_memo.get(name, _MISSING) # a concurrent caller's scan
+ if cached is not _MISSING:
+ return cached
+ origin = _derive_origin_from_ac(name)
+ _ac_origin_memo[name] = origin
+ while len(_ac_origin_memo) > _AC_ORIGIN_MEMO_SIZE:
+ _ac_origin_memo.pop(next(iter(_ac_origin_memo)))
return origin
diff --git a/pixelmap/gui/gui.py b/pixelmap/gui/gui.py
index 8818394..65078f6 100644
--- a/pixelmap/gui/gui.py
+++ b/pixelmap/gui/gui.py
@@ -5,6 +5,7 @@
import asyncio
import base64
+import contextlib
import functools
import json
import logging
@@ -124,8 +125,20 @@ def _darken_hex(hex_color: str, factor: float = 0.6) -> str:
return f"#{r:02x}{g:02x}{b:02x}"
-#: "Not supplied" marker for optional args where ``None`` is a real value.
-_UNSET = object()
+def _measure_tip_depth(tip, pitch_deg, yaw_deg, atlas_name) -> float | None:
+ """Tip-to-surface depth in µm, or ``None`` if outside or the lookup fails."""
+ try:
+ return tip_depth_below_surface_um(
+ tip, pitch_deg=pitch_deg, yaw_deg=yaw_deg, atlas_name=atlas_name
+ )
+ except Exception as exc: # noqa: BLE001 - a readout must never sink the GUI
+ print(f"Tip depth lookup failed: {exc}")
+ return None
+
+
+_BUTTON_COMPUTE = "Compute anatomical overlay 🧠"
+_BUTTON_DOWNLOAD = "Download & compute atlas 🧠 ⏳"
+_BUTTON_DOWNLOADING = "Downloading atlas… (first use only)"
@dataclass(frozen=True)
@@ -153,7 +166,6 @@ class _AnatomyRequest:
ml_squish: float
dv_squish: float
tilt_deg: float
- origin_was_pending: bool
generation: int
@@ -1277,15 +1289,9 @@ def _reposition_region_labels(self):
@pn.io.with_lock
async def _on_compute_anatomy_click(self, event):
- """Compute button: (re)draw the overlay without blocking the event loop.
+ """Compute button: (re)draw the overlay off the event loop.
- On the deployed server this callback runs on the Bokeh event loop —
- the same one serving every other session and the container
- healthcheck. Both halves of an overlay are slow there: a cold atlas
- takes seconds to download, and even a cached one takes 0.7–3.3 s to
- slice and render (measured, allen_mouse_25um → 10um). So all of it
- happens in a worker thread (see :meth:`_drain_anatomy_requests`), and
- only the drawing comes back to the loop.
+ See :meth:`_drain_anatomy_requests` for why the work runs in a thread.
``with_lock`` is not optional. Panel schedules async callbacks with
``nolock`` set unless the function carries ``lock = True``
@@ -1302,7 +1308,7 @@ async def _on_compute_anatomy_click(self, event):
per-session lock: the event loop is free to serve other users while
the work runs, and the session cannot be reaped mid-compute.
"""
- self._anatomy_overlay_wanted = True
+ self._anatomy_overlay_active = True
self._anatomy_dirty = True
await self._drain_anatomy_requests()
@@ -1322,22 +1328,28 @@ def _request_anatomy_recompute(self):
async def _drain_anatomy_requests(self):
"""Run overlay computes in a worker thread until the inputs stop changing.
+ On the server, GUI callbacks run on the Bokeh event loop that serves
+ every session and the healthcheck, and every part of an overlay is slow
+ there: a cold atlas takes seconds to download, a cached one 0.7–3.3 s
+ to slice and render (allen_mouse_25um → 10um), and an AC origin up to
+ ~8 s to locate. So all of that happens in worker threads, and only the
+ snapshot and the drawing touch the loop.
+
One drain per session at a time (``_anatomy_compute_running``); a
request arriving mid-compute sets ``_anatomy_dirty`` and is served by
- the next lap. Each lap re-snapshots the widgets, so it always draws
- the *current* pose and atlas — including an atlas picked while the
- previous one was still downloading.
+ the next lap. Each lap snapshots the widgets only after its downloads
+ and origin lookup, so it always draws the *current* pose and atlas —
+ including an atlas picked while the previous one was still downloading.
"""
if self._anatomy_compute_running:
return
self._anatomy_compute_running = True
try:
- while self._anatomy_dirty and self._anatomy_overlay_wanted:
+ while self._anatomy_dirty and self._anatomy_overlay_active:
self._anatomy_dirty = False
- request = self._anatomy_request()
- name = request.atlas_name
+ name = str(self.atlas_name_input.value).strip()
if not anatomy_atlas.is_downloaded(name):
- self.compute_anatomy_button.name = "Downloading atlas… (first use only)"
+ self.compute_anatomy_button.name = _BUTTON_DOWNLOADING
self.compute_anatomy_button.disabled = True
try:
await asyncio.to_thread(anatomy_atlas.ensure_downloaded, name)
@@ -1347,14 +1359,18 @@ async def _drain_anatomy_requests(self):
# leaving the overlay live would retry the download on
# every later edit. Clicking Compute retries.
self.clear_anatomy_overlay()
- self.compute_anatomy_button.name = "Download & compute atlas 🧠 ⏳"
+ self._refresh_compute_button()
_notify(
"error",
f"Could not download '{name}'. Check your connection and retry.",
)
return
- if self._anatomy_dirty:
- continue # inputs moved during the download: re-snapshot
+ if self._origin_spec(name)["status"] == "ac_pending":
+ # Before the snapshot, so this lap draws with the origin.
+ await self._locate_ac_origin(name)
+ if self._anatomy_dirty:
+ continue # inputs moved while we waited: re-snapshot
+ request = self._anatomy_request()
result = await asyncio.to_thread(self._compute_anatomy, request)
self._apply_anatomy(request, result)
finally:
@@ -1369,10 +1385,15 @@ def compute_anatomy_overlay(self):
through :meth:`_request_anatomy_recompute` instead, which keeps the work
off the event loop.
"""
- self._anatomy_overlay_wanted = True
- if not anatomy_atlas.is_downloaded(str(self.atlas_name_input.value).strip()):
- self.compute_anatomy_button.name = "Downloading atlas… (first use only)"
- self.compute_anatomy_button.disabled = True
+ self._anatomy_overlay_active = True
+ name = str(self.atlas_name_input.value).strip()
+ if self._origin_spec(name)["status"] == "ac_pending":
+ try:
+ anatomy_atlas.derive_origin_from_ac(name)
+ except Exception as exc: # noqa: BLE001 - AC not derivable: banner stays "pending"
+ print(f"Anterior-commissure lookup failed: {exc}")
+ else:
+ self._fill_reference_params()
request = self._anatomy_request()
self._apply_anatomy(request, self._compute_anatomy(request))
@@ -1418,10 +1439,6 @@ def _anatomy_request(self) -> _AnatomyRequest:
ml_squish=ml_squish,
dv_squish=dv_squish,
tilt_deg=tilt_deg,
- # An AC origin not yet located from the annotation (atlas not
- # downloaded, or not derived yet): the compute locates it, and
- # the apply step then fills it into the fields.
- origin_was_pending=status == "ac_pending",
generation=self._anatomy_generation,
)
@@ -1447,14 +1464,6 @@ def _compute_anatomy(self, req: _AnatomyRequest) -> _AnatomyResult:
return _AnatomyResult(error=exc)
result = _AnatomyResult(bands=bands)
- if req.origin_was_pending:
- # Scans the whole annotation (up to ~8 s on a 10 µm atlas), which
- # is why _origin_spec never does it itself; memoised, so the apply
- # step's _origin_spec then answers from the cache.
- try:
- anatomy_atlas.derive_origin_from_ac(req.atlas_name)
- except Exception as exc: # noqa: BLE001 - AC not derivable: _origin_spec reports it
- print(f"Anterior-commissure lookup failed: {exc}")
try:
# Reuse this session's figure: building one per render cost 3.1 MB
# of RSS per overlay compute, and the overlay recomputes on every
@@ -1478,15 +1487,9 @@ def _compute_anatomy(self, req: _AnatomyRequest) -> _AnatomyResult:
result.locator_html = self._fig_to_locator_html(fig)
except Exception as exc: # noqa: BLE001 - a failed locator shouldn't sink the overlay
print(f"Locator render failed: {exc}")
- try:
- result.tip_depth = tip_depth_below_surface_um(
- req.tip,
- pitch_deg=req.pitch_deg,
- yaw_deg=req.yaw_deg,
- atlas_name=req.atlas_name,
- )
- except Exception as exc: # noqa: BLE001 - a readout must never sink the GUI
- print(f"Tip depth lookup failed: {exc}")
+ result.tip_depth = _measure_tip_depth(
+ req.tip, req.pitch_deg, req.yaw_deg, req.atlas_name
+ )
# Hand back the chunk buffers this render churned through. They are
# already freed; this is what unmaps them, so repeated overlay computes
@@ -1496,12 +1499,11 @@ def _compute_anatomy(self, req: _AnatomyRequest) -> _AnatomyResult:
def _apply_anatomy(self, req: _AnatomyRequest, result: _AnatomyResult):
"""Draw a finished compute. Event loop only (writes Bokeh models)."""
- if req.generation != self._anatomy_generation or not self._anatomy_overlay_wanted:
+ if req.generation != self._anatomy_generation or not self._anatomy_overlay_active:
return # cleared while computing: drop the stale result
+ self._refresh_compute_button()
if result.error is not None:
print(f"Anatomy lookup failed: {result.error}")
- self.compute_anatomy_button.name = "Compute anatomical overlay 🧠"
- self.compute_anatomy_button.disabled = False
return
bands = result.bands
@@ -1558,34 +1560,16 @@ def _apply_anatomy(self, req: _AnatomyRequest, result: _AnatomyResult):
if result.locator_html is not None:
self.anatomy_locator.object = result.locator_html
- # Overlay now exists → later input edits live-update it.
- self._anatomy_overlay_active = True
self.anatomy_locator_section.visible = True
# Only now can the depth readout show a value: the overlay is up, and
- # computing it downloaded the atlas if it wasn't already cached (the
- # readout refuses to trigger a download itself).
- self._set_tip_depth_readout(result.tip_depth)
- self.compute_anatomy_button.name = "Compute anatomical overlay 🧠"
- self.compute_anatomy_button.disabled = False
-
- # The compute located a previously "pending" AC landmark: fill it in
- # (without clobbering user edits), then redraw once more so the locator
- # shows the origin dot this render was computed without.
- if req.origin_was_pending and self._origin_spec(req.atlas_name)["status"] != "ac_pending":
- self._suppress_anatomy_recompute = True
- try:
- self._update_reference_params()
- finally:
- self._suppress_anatomy_recompute = False
- self.bregma_estimate_header.object = self._bregma_header_html()
- self._request_anatomy_recompute()
+ # computing it downloaded the atlas if it wasn't already cached.
+ self._update_tip_depth_readout(result.tip_depth)
def clear_anatomy_overlay(self):
"""Wipe the region bands, labels, boundaries and reset the legend."""
self._anatomy_overlay_active = False # stop live-updating
# Any compute still in flight finishes in its worker thread, but its
# result is for an overlay the user just dismissed: drop it.
- self._anatomy_overlay_wanted = False
self._anatomy_generation += 1
self.region_band_source.data = {
"x": [], "y": [], "width": [], "height": [], "color": [], "acronym": [],
@@ -1696,32 +1680,26 @@ def _on_atlas_change(self, *events):
The field updates are batched under a recompute guard so a single atlas
switch triggers one overlay refresh, not one per field changed.
"""
- self._suppress_anatomy_recompute = True
- try:
+ with self._anatomy_recompute_suppressed():
self._update_reference_params(*events)
self._update_tip_to_atlas_center(*events)
self._update_anatomy_origin_note(*events)
self._update_landmark_labels()
self.bregma_estimate_header.object = self._bregma_header_html()
- finally:
- self._suppress_anatomy_recompute = False
# Reflect download state in the button label so users know before clicking.
+ self._refresh_compute_button()
name = str(self.atlas_name_input.value).strip()
- downloaded = anatomy_atlas.is_downloaded(name)
- if downloaded:
- self.compute_anatomy_button.name = "Compute anatomical overlay 🧠"
- else:
- self.compute_anatomy_button.name = "Download & compute atlas 🧠 ⏳"
- if getattr(self, "_anatomy_overlay_wanted", False):
+ if getattr(self, "_anatomy_overlay_active", False):
# The recompute locates a pending AC origin on its way through.
self._recompute_anatomy_if_active()
- elif downloaded and self._origin_spec(name)["status"] == "ac_pending":
+ elif (self._origin_spec(name)["status"] == "ac_pending"
+ and anatomy_atlas.is_downloaded(name)):
# No overlay to do it, but the atlas is local, so the origin can be
# shown now — once a worker thread has scanned for it.
- pn.state.execute(functools.partial(self._locate_ac_origin_off_loop, name))
+ pn.state.execute(functools.partial(self._locate_ac_origin, name))
@pn.io.with_lock
- async def _locate_ac_origin_off_loop(self, name: str):
+ async def _locate_ac_origin(self, name: str):
"""Derive an atlas's AC origin in a worker thread, then fill the fields.
The derivation reads every voxel of the annotation (~8 s on a 10 µm
@@ -1733,15 +1711,28 @@ async def _locate_ac_origin_off_loop(self, name: str):
except Exception as exc: # noqa: BLE001 - AC not derivable: banner stays "pending"
print(f"Anterior-commissure lookup failed: {exc}")
return
- if str(self.atlas_name_input.value).strip() != name:
- return # the user has moved on to another atlas
+ if str(self.atlas_name_input.value).strip() == name: # still selected
+ self._fill_reference_params()
+
+ def _fill_reference_params(self):
+ """Refill the origin fields and banner without triggering a recompute."""
+ with self._anatomy_recompute_suppressed():
+ self._update_reference_params()
+ self.bregma_estimate_header.object = self._bregma_header_html()
+
+ def _refresh_compute_button(self):
+ """Label the Compute button by whether the selected atlas is local."""
+ downloaded = anatomy_atlas.is_downloaded(str(self.atlas_name_input.value).strip())
+ self.compute_anatomy_button.name = _BUTTON_COMPUTE if downloaded else _BUTTON_DOWNLOAD
+
+ @contextlib.contextmanager
+ def _anatomy_recompute_suppressed(self):
+ """Batch field writes so they don't each request an overlay recompute."""
self._suppress_anatomy_recompute = True
try:
- self._update_reference_params()
+ yield
finally:
self._suppress_anatomy_recompute = False
- self.bregma_estimate_header.object = self._bregma_header_html()
- self._recompute_anatomy_if_active()
def _update_landmark_labels(self):
"""Rename the toggle + coordinate fields to the atlas's landmark.
@@ -1822,18 +1813,14 @@ def _tip_depth_below_surface(self) -> float | None:
"""
if not self._atlas_is_downloaded():
return None
- try:
- return tip_depth_below_surface_um(
- self._tip_atlas_um(),
- pitch_deg=float(self.pitch_input.value),
- yaw_deg=float(self.yaw_input.value),
- atlas_name=str(self.atlas_name_input.value).strip(),
- )
- except Exception as exc: # noqa: BLE001 - a readout must never sink the GUI
- print(f"Tip depth lookup failed: {exc}")
- return None
+ return _measure_tip_depth(
+ self._tip_atlas_um(),
+ float(self.pitch_input.value),
+ float(self.yaw_input.value),
+ str(self.atlas_name_input.value).strip(),
+ )
- def _tip_depth_readout_html(self, depth=_UNSET) -> str:
+ def _tip_depth_readout_html(self, depth: float | None) -> str:
"""Banner text for the depth-below-surface readout above the tip fields.
Blank until an overlay exists: before Compute (or after Clear) there is
@@ -1841,8 +1828,8 @@ def _tip_depth_readout_html(self, depth=_UNSET) -> str:
would look like a live measurement of a pose nothing has been checked
against.
- ``depth`` is the value an off-loop overlay compute already measured;
- omitted, it is looked up here, which reads the atlas on this thread.
+ ``depth`` is measured by the off-loop overlay compute; this never reads
+ the atlas itself, so it is safe on the event loop.
"""
if not getattr(self, "_anatomy_overlay_active", False):
value_html = (
@@ -1857,8 +1844,6 @@ def _tip_depth_readout_html(self, depth=_UNSET) -> str:
"(available once the atlas is downloaded)"
)
else:
- if depth is _UNSET:
- depth = self._tip_depth_below_surface()
if depth is None:
value_html = (
'—'
@@ -1884,14 +1869,8 @@ def _tip_depth_readout_html(self, depth=_UNSET) -> str:
""
)
- def _update_tip_depth_readout(self, *events):
+ def _update_tip_depth_readout(self, depth: float | None = None):
"""Refresh the depth readout (cheap; skipped if the widget isn't built)."""
- if not hasattr(self, "tip_depth_readout"):
- return
- self.tip_depth_readout.object = self._tip_depth_readout_html()
-
- def _set_tip_depth_readout(self, depth: float | None):
- """Show a depth measured elsewhere (by the off-loop overlay compute)."""
if not hasattr(self, "tip_depth_readout"):
return
self.tip_depth_readout.object = self._tip_depth_readout_html(depth)
@@ -1968,7 +1947,7 @@ def _origin_spec(self, name) -> dict:
if landmark == "anterior commissure":
# Human (AC-PC): derived from the annotation, but only ever off the
# event loop — it scans the whole volume (up to ~8 s). Until that
- # has happened (see _locate_ac_origin_off_loop and the overlay
+ # has happened (see _locate_ac_origin and the overlay
# compute) report it as pending.
known, ac = anatomy_atlas.peek_origin_from_ac(name)
if not known:
@@ -2007,8 +1986,7 @@ def _on_bregma_toggle(self, *events):
for w in (self.dv_squish_input, self.ap_squish_input,
self.ml_squish_input, self.tilt_input):
w.disabled = not on
- self._suppress_anatomy_recompute = True
- try:
+ with self._anatomy_recompute_suppressed():
if on:
# Sensible bregma-relative default: at bregma, 4 mm deep.
self.tip_ap_input.value = 0.0
@@ -2016,22 +1994,14 @@ def _on_bregma_toggle(self, *events):
self.tip_dv_input.value = 4000.0
else:
self._update_tip_to_atlas_center()
- finally:
- self._suppress_anatomy_recompute = False
self._recompute_anatomy_if_active()
def _recompute_anatomy_if_active(self, *events):
"""Re-run the overlay on input changes, but only once one exists."""
if getattr(self, "_suppress_anatomy_recompute", False):
return
- # "Wanted", not "active": edits made while the first compute is still
- # running must reach it too, or it draws an outdated pose or atlas.
- if getattr(self, "_anatomy_overlay_wanted", False):
- # Never inline: on the server this watcher runs on the event loop,
- # and a recompute is a download for a cold atlas (just picked from
- # the dropdown) and 0.7–3.3 s of slicing and rendering even for a
- # cached one. Either froze every session; this runs it off-loop.
- self._request_anatomy_recompute()
+ if getattr(self, "_anatomy_overlay_active", False):
+ self._request_anatomy_recompute() # never inline: see _drain_anatomy_requests
def _update_anatomy_legend(self, bands: list):
"""Render a deduplicated region legend on the right-side panel."""
@@ -2902,15 +2872,16 @@ def create_widgets(self):
self.atlas_name_input.param.watch(self._on_atlas_change, "value")
self.bregma_relative_toggle.param.watch(self._on_bregma_toggle, "value")
- # Once an overlay exists, live-update it (bands + slices) whenever any
- # pose / bregma / squish / tilt input changes, so edits are visible
- # immediately instead of only on the next Compute click.
+ # Once an overlay is requested, live-update it (bands + slices) whenever
+ # any pose / bregma / squish / tilt input changes, so edits are visible
+ # immediately instead of only on the next Compute click. Set on
+ # Compute, not on the first draw, so edits made while that first
+ # compute runs reach it too.
self._anatomy_overlay_active = False
# Off-loop compute bookkeeping (see _drain_anatomy_requests): whether
- # the user asked for an overlay, whether its inputs changed since the
- # last compute started, whether a compute is running, and a counter
- # bumped by Clear so a compute that outlives its overlay is dropped.
- self._anatomy_overlay_wanted = False
+ # inputs changed since the last compute started, whether a compute is
+ # running, and a counter bumped by Clear so a compute that outlives its
+ # overlay is dropped.
self._anatomy_dirty = False
self._anatomy_compute_running = False
self._anatomy_generation = 0
@@ -2937,7 +2908,7 @@ def create_widgets(self):
margin=(0, 0),
)
self.compute_anatomy_button = pn.widgets.Button(
- name="Compute anatomical overlay 🧠", button_type="primary",
+ name=_BUTTON_COMPUTE, button_type="primary",
sizing_mode="stretch_width", margin=(0, 0, 0, 0),
)
self.clear_anatomy_button = pn.widgets.Button(
@@ -2947,7 +2918,7 @@ def create_widgets(self):
self.clear_anatomy_button.on_click(lambda event: self.clear_anatomy_overlay())
self.anatomy_legend = pn.pane.HTML(self._empty_legend_html(), sizing_mode="stretch_width")
self.anatomy_locator = pn.pane.HTML("", sizing_mode="stretch_width")
- # Reused across renders (see compute_anatomy_overlay); dropped when the
+ # Reused across renders (see _compute_anatomy); dropped when the
# overlay is cleared so an idle session doesn't sit on a canvas.
self._locator_fig = None
# Hidden until the first overlay is computed; cleared by "Clear overlay".
@@ -2957,8 +2928,7 @@ def create_widgets(self):
)
# Set initial button label based on whether the default atlas is already cached.
- if not anatomy_atlas.is_downloaded(atlas_default):
- self.compute_anatomy_button.name = "Download & compute atlas 🧠 ⏳"
+ self._refresh_compute_button()
# IMRO file dropper
self.imro_file_loader = pn.widgets.FileInput(width=300)
diff --git a/tests/test_anatomy_atlas.py b/tests/test_anatomy_atlas.py
index a37ace4..21b2b68 100644
--- a/tests/test_anatomy_atlas.py
+++ b/tests/test_anatomy_atlas.py
@@ -224,6 +224,29 @@ def test_origin_memo_is_bounded_and_evicts_oldest_first(self, monkeypatch):
assert atlas_module.peek_origin_from_ac(f"atlas{size}")[0] is True
assert len(atlas_module._ac_origin_memo) == size
+ def test_concurrent_callers_share_one_scan(self, monkeypatch):
+ """Several sessions picking the same human atlas pay for one scan."""
+ import threading
+ import time
+
+ calls = []
+
+ def _slow(name):
+ calls.append(name)
+ time.sleep(0.05)
+ return (1.0, 2.0, 3.0)
+
+ monkeypatch.setattr(atlas_module, "_derive_origin_from_ac", _slow)
+ results = []
+ workers = [threading.Thread(target=lambda: results.append(
+ atlas_module.derive_origin_from_ac("e"))) for _ in range(4)]
+ for w in workers:
+ w.start()
+ for w in workers:
+ w.join()
+ assert calls == ["e"]
+ assert results == [(1.0, 2.0, 3.0)] * 4
+
def test_cache_clear_forgets_derived_origins(self, monkeypatch):
monkeypatch.setattr(atlas_module, "_derive_origin_from_ac", lambda name: (0.0, 0.0, 0.0))
atlas_module.derive_origin_from_ac("d")
diff --git a/tests/test_gui_overlays.py b/tests/test_gui_overlays.py
index 462fcf5..1fd8054 100644
--- a/tests/test_gui_overlays.py
+++ b/tests/test_gui_overlays.py
@@ -90,6 +90,7 @@ def __init__(self, name, **_kwargs):
atlas_module.release_atlas_memory()
atlas_module.get_atlas.cache_clear()
atlas_module.canonical_annotation.cache_clear()
+ atlas_module.derive_origin_from_ac.cache_clear()
atlas_module._region_info_from_id.cache_clear()
monkeypatch.setattr(atlas_module, "BrainGlobeAtlas", _FakeAtlas)
# Pretend it's cached so the GUI treats it as a local atlas throughout.
@@ -98,6 +99,7 @@ def __init__(self, name, **_kwargs):
atlas_module.release_atlas_memory()
atlas_module.get_atlas.cache_clear()
atlas_module.canonical_annotation.cache_clear()
+ atlas_module.derive_origin_from_ac.cache_clear()
atlas_module._region_info_from_id.cache_clear()
@@ -815,6 +817,14 @@ def test_switching_to_a_warm_atlas_still_recomputes_immediately(self, traced):
assert len(gui.region_band_source.data["acronym"]) > 0
+def _assert_off_loop(threads, what: str):
+ """``what`` ran, and never on the main (event loop) thread."""
+ assert threads, f"{what} never ran"
+ assert all(t is not threading.main_thread() for t in threads), (
+ f"{what} ran on the event loop thread"
+ )
+
+
class TestOverlayComputeRunsOffTheEventLoop:
"""Regression tests: even a *cached* atlas froze the server on every edit.
@@ -841,14 +851,6 @@ def wrapper(*args, **kwargs):
monkeypatch.setattr(gui_module, label, _tracing(label, getattr(gui_module, label)))
return seen
- @staticmethod
- def _assert_off_loop(seen, *labels):
- for label in labels:
- assert seen.get(label), f"{label} never ran"
- assert all(t is not threading.main_thread() for t in seen[label]), (
- f"{label} ran on the event loop thread"
- )
-
def test_a_live_pose_edit_computes_off_the_event_loop(self, posed_gui, threads):
posed_gui.compute_anatomy_overlay()
before = list(posed_gui.region_band_source.data["y"])
@@ -856,8 +858,8 @@ def test_a_live_pose_edit_computes_off_the_event_loop(self, posed_gui, threads):
posed_gui.tip_dv_input.value = 2200.0
- self._assert_off_loop(threads, "compute_region_bands", "render_locator",
- "tip_depth_below_surface_um")
+ for label in ("compute_region_bands", "render_locator", "tip_depth_below_surface_um"):
+ _assert_off_loop(threads.get(label), label)
assert list(posed_gui.region_band_source.data["y"]) != before
# 2200 µm tip, surface at ≈ 987.5 µm → ≈ 1212 µm below it.
assert "1,2" in posed_gui.tip_depth_readout.object
@@ -867,7 +869,8 @@ def test_clicking_compute_on_a_cached_atlas_computes_off_the_loop(self, served,
asyncio.run(session.with_document_locked(gui._on_compute_anatomy_click, None))
- self._assert_off_loop(threads, "compute_region_bands", "render_locator")
+ for label in ("compute_region_bands", "render_locator"):
+ _assert_off_loop(threads.get(label), label)
assert len(gui.region_band_source.data["acronym"]) > 0
assert gui.compute_anatomy_button.disabled is False
@@ -937,10 +940,8 @@ def _derive(name):
seen.append(threading.current_thread())
return self.AC_ORIGIN
- atlas_module.derive_origin_from_ac.cache_clear()
monkeypatch.setattr(atlas_module, "_derive_origin_from_ac", _derive)
- yield posed_gui, seen
- atlas_module.derive_origin_from_ac.cache_clear()
+ return posed_gui, seen
def _assert_origin_filled(self, gui):
assert (gui.bregma_ap_input.value, gui.bregma_ml_input.value,
@@ -953,10 +954,7 @@ def test_switching_to_a_cached_ac_atlas_derives_it_off_the_loop(self, ac_threads
gui.atlas_name_input.value = self.AC_ATLAS
- assert seen, "the AC origin was never located"
- assert all(t is not threading.main_thread() for t in seen), (
- "the whole-volume AC scan ran on the event loop thread"
- )
+ _assert_off_loop(seen, "the whole-volume AC scan")
self._assert_origin_filled(gui)
def test_with_an_overlay_the_recompute_derives_it_off_the_loop(self, ac_threads):
@@ -965,7 +963,7 @@ def test_with_an_overlay_the_recompute_derives_it_off_the_loop(self, ac_threads)
gui.atlas_name_input.value = self.AC_ATLAS
- assert seen and all(t is not threading.main_thread() for t in seen)
+ _assert_off_loop(seen, "the whole-volume AC scan")
self._assert_origin_filled(gui)
assert len(gui.region_band_source.data["acronym"]) > 0
From bd3b26cc7391e56d4b3069051c4ebee242d390ec Mon Sep 17 00:00:00 2001
From: Christian Tabedzki <35670232+tabedzki@users.noreply.github.com>
Date: Fri, 30 Oct 2026 09:07:53 -0400
Subject: [PATCH 4/4] refactor: simplify code changed since v1.4.1
Second /simplify pass, widened from this PR's diff to everything since
v1.4.1.
- compute_anatomy_overlay() now runs the same off-loop drain as the
Compute button (synchronous when no event loop is running), so the
separate inline pipeline and its duplicate AC-origin handling are gone.
_request_anatomy_recompute drops its redundant "already running" check;
the drain's own guard is the one that matters.
- The overlay worker no longer writes session state: the locator figure
travels in the request/result and is adopted (or closed if stale) on
the loop. Label width/offset are computed at draw time instead of
being snapshotted.
- Anatomy flags are initialised in __init__, so the getattr fallbacks go;
_selected_atlas_name() replaces eight copies of the name lookup; the
unreachable "available once downloaded" readout branch and the
test-only _tip_depth_below_surface are removed.
- AC-origin memo is a plain dict (no hand-rolled eviction).
- Wiring maps: a cold rebuild indexed the wiring table once per
electrode (~55 s in the first session's constructor); it now indexes
each table once (~1.1 s), with identical output.
- PDF electrodes are drawn as one PolyCollection built from a vertex
array with precomputed colours, sharing one path between single- and
multi-shank probes: pixel-identical renders, 2-3x faster.
- `import pixelmap` no longer loads Panel/Bokeh (1.28 s -> 0.55 s): the
IMRO parser imports the notification helper lazily.
- One notify() helper in error_reporting replaces gui._notify and
error_reporting._toast; traceback helpers use the stdlib directly;
survey parsing converts all columns in one pass.
Assisted-by: ClaudeCode:claude-opus-5-5
---
pixelmap/anatomy/atlas.py | 32 +++----
pixelmap/backend.py | 176 +++++++++++++++---------------------
pixelmap/error_reporting.py | 27 +++---
pixelmap/gui/gui.py | 162 ++++++++++++---------------------
pixelmap/utils/imro.py | 20 ++--
pixelmap/utils/survey.py | 12 +--
tests/test_anatomy_atlas.py | 9 --
tests/test_gui_overlays.py | 38 +++++---
tests/test_pdf_export.py | 10 +-
tests/test_public_api.py | 11 +++
tests/test_wiring_lookup.py | 34 +++++++
11 files changed, 251 insertions(+), 280 deletions(-)
diff --git a/pixelmap/anatomy/atlas.py b/pixelmap/anatomy/atlas.py
index cca4c93..6b2fff4 100644
--- a/pixelmap/anatomy/atlas.py
+++ b/pixelmap/anatomy/atlas.py
@@ -574,13 +574,10 @@ def landmark_policy(name: str) -> str | None:
return None
-#: Memo for :func:`derive_origin_from_ac`, insertion-ordered so the oldest
-#: entry is evicted first. Hand-rolled rather than ``lru_cache`` because
-#: :func:`peek_origin_from_ac` needs to ask "is this one known?" without
-#: computing it. Values are three floats, so the bound is about entries, not RAM.
+#: Memo for :func:`derive_origin_from_ac`. A plain dict rather than
+#: ``lru_cache`` because :func:`peek_origin_from_ac` needs to ask "is this one
+#: known?" without computing it. Unbounded: one three-float entry per atlas.
_ac_origin_memo: dict[str, tuple[float, float, float] | None] = {}
-_AC_ORIGIN_MEMO_SIZE = 8
-_MISSING = object()
#: One lock per atlas name, so concurrent callers (several sessions, or a quick
#: A→B→A switch) wait for the scan already running instead of starting another.
_ac_origin_locks: dict[str, threading.Lock] = {}
@@ -600,20 +597,14 @@ def derive_origin_from_ac(name: str) -> tuple[float, float, float] | None:
per atlas and single-flight per name; exceptions are not cached, so a
failed lookup is retried.
"""
- cached = _ac_origin_memo.get(name, _MISSING)
- if cached is not _MISSING:
- return cached
+ if name in _ac_origin_memo:
+ return _ac_origin_memo[name]
with _ac_origin_locks_guard:
lock = _ac_origin_locks.setdefault(name, threading.Lock())
with lock:
- cached = _ac_origin_memo.get(name, _MISSING) # a concurrent caller's scan
- if cached is not _MISSING:
- return cached
- origin = _derive_origin_from_ac(name)
- _ac_origin_memo[name] = origin
- while len(_ac_origin_memo) > _AC_ORIGIN_MEMO_SIZE:
- _ac_origin_memo.pop(next(iter(_ac_origin_memo)))
- return origin
+ if name not in _ac_origin_memo: # else a concurrent caller's scan won
+ _ac_origin_memo[name] = _derive_origin_from_ac(name)
+ return _ac_origin_memo[name]
derive_origin_from_ac.cache_clear = _ac_origin_memo.clear
@@ -625,10 +616,9 @@ def peek_origin_from_ac(name: str) -> tuple[bool, tuple[float, float, float] | N
``known`` is False until something has derived this atlas's origin.
Instant and touches no atlas data, so it is safe on the event loop.
"""
- cached = _ac_origin_memo.get(name, _MISSING)
- if cached is _MISSING:
- return False, None
- return True, cached
+ if name in _ac_origin_memo:
+ return True, _ac_origin_memo[name]
+ return False, None
def _derive_origin_from_ac(name: str) -> tuple[float, float, float] | None:
diff --git a/pixelmap/backend.py b/pixelmap/backend.py
index 5d5322e..38e0701 100644
--- a/pixelmap/backend.py
+++ b/pixelmap/backend.py
@@ -12,7 +12,7 @@
import numpy as np
import pandas as pd
from matplotlib import cm, patches
-from matplotlib.collections import PatchCollection
+from matplotlib.collections import PolyCollection
from .constants import (
LEGACY_INT_TO_IMRO_FORMAT,
@@ -103,25 +103,24 @@ def _wiring_index(wiring_df):
def find_forbidden_electrodes(selected_electrodes, wiring_df):
"Return list of forbidden electrodes [[shank_id, electrode_id], ...] given selected electrodes and wiring diagram."
+ return _forbidden_electrodes(selected_electrodes, *_wiring_index(wiring_df))
- table, shanks, index = _wiring_index(wiring_df)
- rows, sel_shanks, sel_electrodes = [], [], []
+def _forbidden_electrodes(selected_electrodes, table, shanks, index):
+ """``find_forbidden_electrodes`` against a prebuilt :func:`_wiring_index`."""
+ rows = []
for shank_id, electrode_id in selected_electrodes:
loc = index.get((float(shank_id), float(electrode_id)))
assert loc is not None, f"electrode {electrode_id} on shank {shank_id} not found in wiring map!"
rows.append(loc[0])
- sel_shanks.append(float(shank_id))
- sel_electrodes.append(float(electrode_id))
+ selected = np.asarray(selected_electrodes, dtype=float).reshape(-1, 2)
# Every selected electrode's wiring-table row: the electrodes sharing its
# channel. Keep the wired (non-NaN), non-self cells; boolean indexing is
# row-major, so the order matches the old per-electrode loop.
row_electrodes = table[rows] # (n_selected, n_columns)
row_shanks = np.broadcast_to(shanks, row_electrodes.shape)
- is_self = (row_shanks == np.array(sel_shanks)[:, None]) & (
- row_electrodes == np.array(sel_electrodes)[:, None]
- )
+ is_self = (row_shanks == selected[:, :1]) & (row_electrodes == selected[:, 1:])
keep = ~np.isnan(row_electrodes) & ~is_self
if not keep.any():
return np.empty((0, 2), dtype=int)
@@ -165,9 +164,10 @@ def _load_wiring_maps(wiring_maps_dir):
wiring_df = pd.read_csv(wiring_file)
wiring_maps[probe_type] = {}
+ wiring = _wiring_index(wiring_df) # once per table, not per electrode
for (shank_id, electrode_id, _, _) in positions_df.values:
electrode = Electrode(shank_id=shank_id, electrode_id=electrode_id)
- conflicting_electrodes = find_forbidden_electrodes([(shank_id, electrode_id)], wiring_df)
+ conflicting_electrodes = _forbidden_electrodes([(shank_id, electrode_id)], *wiring)
conflicting_electrodes = {Electrode(e[0], e[1]) for e in conflicting_electrodes}
wiring_maps[probe_type][electrode] = conflicting_electrodes
@@ -685,18 +685,38 @@ def _darken_hex(hex_color: str, factor: float = 0.6) -> str:
return f"#{r:02x}{g:02x}{b:02x}"
-def _add_rects(ax, rects, facecolors, zorder=1):
- """Add borderless rectangles to ``ax`` as a single PatchCollection.
+_SELECTED_COLOR, _UNSELECTED_COLOR, _FORBIDDEN_COLOR = "red", "lightgrey", "black"
+_SELECTED_RGBA = mcolors.to_rgba(_SELECTED_COLOR, 1.0)
+_FORBIDDEN_RGBA = mcolors.to_rgba(_FORBIDDEN_COLOR, 1.0)
+_UNSELECTED_RGBA = mcolors.to_rgba(_UNSELECTED_COLOR, 0.7)
+
+
+def _electrode_rgba(is_selected, is_forbidden):
+ """Per-electrode facecolour: selected wins over forbidden over unselected."""
+ return np.select(
+ [np.asarray(is_selected)[:, None], np.asarray(is_forbidden)[:, None]],
+ [_SELECTED_RGBA, _FORBIDDEN_RGBA],
+ default=_UNSELECTED_RGBA,
+ )
+
+
+def _add_rects(ax, x0, y0, width, height, facecolors, zorder=1):
+ """Add borderless rectangles (lower-left corners ``x0, y0``) as one collection.
A probe has thousands of electrodes; adding each as its own patch made the
PDF export spend seconds in per-artist bookkeeping (data-limit updates,
transform setup, separate draw calls) on the server's event loop. One
- collection renders identically for a fraction of the cost.
+ collection built straight from a vertex array renders identically for a
+ fraction of the cost.
"""
- if not rects:
+ x0 = np.asarray(x0, dtype=float)
+ if not x0.size:
return
+ y0 = np.asarray(y0, dtype=float)
+ x1, y1 = x0 + width, y0 + height
+ verts = np.stack([np.column_stack(c) for c in ((x0, y0), (x1, y0), (x1, y1), (x0, y1))], axis=1)
ax.add_collection(
- PatchCollection(rects, facecolors=facecolors, edgecolors="none", linewidths=0, zorder=zorder),
+ PolyCollection(verts, facecolors=facecolors, edgecolors="none", linewidths=0, zorder=zorder),
autolim=False,
)
@@ -712,11 +732,6 @@ def plot_probe_layout(
"""
- # Format parameters
- selected_color = "red"
- unselected_color = "lightgrey"
- forbidden_color = "black"
-
if probe_type in ["1.0", "2.0-1shank"]:
n_shanks = 1
else: # "2.0-4shanks" and future multi-shank types
@@ -827,48 +842,27 @@ def plot_probe_layout(
# Draw electrodes (and optional survey sidebar bars)
is_selected = np.isin(positions[:, 1], selected_electrodes[:, 1])
is_forbidden = np.isin(positions[:, 1], forbidden_electrodes[:, 1])
- electrode_rects, electrode_colors = [], []
- bar_rects, bar_colors = [], []
- for (electrode, orig_x, y), sel, forb in zip(positions[:, 1:], is_selected, is_forbidden):
- if sel:
- color = selected_color
- alpha = 1.0
- elif forb:
- color = forbidden_color
- alpha = 1
- else:
- color = unselected_color
- alpha = 0.7
-
- # Map original x positions to shank width (normalized then scaled)
- if probe_type in ["1.0"]:
- # Original positions: 11,27,43,59 μm (range: 48 μm, center at 35)
- # Normalize to [-1, 1] range: (x - 35) / 24
- x_norm = (orig_x - 35) / 24
- x = x_norm * (shank_width * 0.8) / 2 # Use 80% of shank width
- else: # linear
- # Original positions: 0,32 μm (range: 32 μm, center at 16)
- # Normalize to [-1, 1] range: (x - 16) / 16
- x_norm = (orig_x - 16) / 16
- x = x_norm * (shank_width * 0.6) / 2 # Use 60% of shank width
-
- electrode_rects.append(patches.Rectangle(
- (x - electrode_width // 2, y - electrode_height // 2),
- electrode_width,
- electrode_height,
- ))
- electrode_colors.append(mcolors.to_rgba(color, alpha))
-
- # Survey sidebar bar (always on right side in PDF)
- if survey_colors is not None:
- bar_rects.append(patches.Rectangle(
- (survey_bar_center_x - survey_bar_width / 2, y - electrode_height / 2),
- survey_bar_width, electrode_height,
- ))
- bar_colors.append(survey_colors.get((0, int(electrode)), "#dddddd"))
-
- _add_rects(ax, electrode_rects, electrode_colors)
- _add_rects(ax, bar_rects, bar_colors, zorder=50)
+ electrodes, orig_x, ys = positions[:, 1], positions[:, 2], positions[:, 3]
+ # Map original x positions to shank width (normalized then scaled)
+ if probe_type in ["1.0"]:
+ # Original positions: 11,27,43,59 μm (range: 48 μm, center at 35)
+ # Normalize to [-1, 1] range: (x - 35) / 24; use 80% of shank width
+ xs = (orig_x - 35) / 24 * (shank_width * 0.8) / 2
+ else: # linear
+ # Original positions: 0,32 μm (range: 32 μm, center at 16)
+ # Normalize to [-1, 1] range: (x - 16) / 16; use 60% of shank width
+ xs = (orig_x - 16) / 16 * (shank_width * 0.6) / 2
+ _add_rects(
+ ax, xs - electrode_width // 2, ys - electrode_height // 2,
+ electrode_width, electrode_height, _electrode_rgba(is_selected, is_forbidden),
+ )
+ # Survey sidebar bars (always on right side in PDF)
+ if survey_colors is not None:
+ _add_rects(
+ ax, np.full(len(ys), survey_bar_center_x - survey_bar_width / 2), ys - electrode_height / 2,
+ survey_bar_width, electrode_height,
+ [survey_colors.get((0, int(e)), "#dddddd") for e in electrodes], zorder=50,
+ )
ax.set_xlim(-shank_width // 2 - 20, shank_width // 2 + 20)
ax.set_ylim(min_y - tip_height - 50, max_y + 100)
@@ -1009,43 +1003,23 @@ def plot_probe_layout(
shank_forbidden = forbidden_electrodes[forbidden_electrodes[:, 0] == shank_id, 1]
is_selected = np.isin(shank_positions[:, 1], shank_selected)
is_forbidden = np.isin(shank_positions[:, 1], shank_forbidden)
- electrode_rects, electrode_colors = [], []
- bar_rects, bar_colors = [], []
- for (shank_id_pos, electrode, orig_x, y), sel, forb in zip(shank_positions, is_selected, is_forbidden):
- # Check if this electrode is selected
- if sel:
- electrode_color = selected_color
- alpha = 1.0
- elif forb:
- electrode_color = forbidden_color
- alpha = 1
- else:
- electrode_color = unselected_color
- alpha = 0.7
-
- # Map electrode positions to shank width (normalized then scaled)
- # Original positions: 0,32 μm (center at 16) - always 2.0
- x_norm = (orig_x - true_shank_spacing * shank_id - 16) / 16
- x = x_center + x_norm * (shank_width * 0.5) / 2
-
- electrode_rects.append(patches.Rectangle(
- (x - electrode_width // 2, y - electrode_height // 2),
- electrode_width,
- electrode_height,
- ))
- electrode_colors.append(mcolors.to_rgba(electrode_color, alpha))
-
- # Survey sidebar bar (always on right side of each shank in PDF)
- if survey_colors is not None:
- bar_x = x_center + ms_survey_bar_center_offset
- bar_rects.append(patches.Rectangle(
- (bar_x - ms_survey_bar_width / 2, y - electrode_height / 2),
- ms_survey_bar_width, electrode_height,
- ))
- bar_colors.append(survey_colors.get((int(shank_id_pos), int(electrode)), "#dddddd"))
-
- _add_rects(ax, electrode_rects, electrode_colors)
- _add_rects(ax, bar_rects, bar_colors, zorder=50)
+ shank_ids, electrodes, orig_x, ys = shank_positions.T
+ # Map electrode positions to shank width (normalized then scaled)
+ # Original positions: 0,32 μm (center at 16) - always 2.0
+ xs = x_center + (orig_x - true_shank_spacing * shank_id - 16) / 16 * (shank_width * 0.5) / 2
+ _add_rects(
+ ax, xs - electrode_width // 2, ys - electrode_height // 2,
+ electrode_width, electrode_height, _electrode_rgba(is_selected, is_forbidden),
+ )
+ # Survey sidebar bars (always on right side of each shank in PDF)
+ if survey_colors is not None:
+ bar_x = x_center + ms_survey_bar_center_offset
+ _add_rects(
+ ax, np.full(len(ys), bar_x - ms_survey_bar_width / 2), ys - electrode_height / 2,
+ ms_survey_bar_width, electrode_height,
+ [survey_colors.get((int(sh), int(e)), "#dddddd") for sh, e in zip(shank_ids, electrodes)],
+ zorder=50,
+ )
# Add shank label
ax.text(
@@ -1114,19 +1088,19 @@ def plot_probe_layout(
from matplotlib.lines import Line2D
legend_elements = [
- Line2D([0], [0], marker="s", color="w", markerfacecolor=selected_color, markersize=10, label="Selected"),
+ Line2D([0], [0], marker="s", color="w", markerfacecolor=_SELECTED_COLOR, markersize=10, label="Selected"),
Line2D(
[0],
[0],
marker="s",
color="w",
- markerfacecolor=unselected_color,
+ markerfacecolor=_UNSELECTED_COLOR,
markersize=10,
alpha=0.7,
label="Unselected",
),
Line2D(
- [0], [0], marker="s", color="w", markerfacecolor=forbidden_color, markersize=10, alpha=1, label="Forbidden"
+ [0], [0], marker="s", color="w", markerfacecolor=_FORBIDDEN_COLOR, markersize=10, alpha=1, label="Forbidden"
),
]
# Pin ``loc`` explicitly. Without it matplotlib uses loc="best", which on
diff --git a/pixelmap/error_reporting.py b/pixelmap/error_reporting.py
index 4e324c1..9e9e33c 100644
--- a/pixelmap/error_reporting.py
+++ b/pixelmap/error_reporting.py
@@ -150,7 +150,7 @@ def load_webhook_config(environ: Mapping[str, str] | None = None) -> WebhookConf
def _format_traceback(exc: BaseException) -> str:
try:
- return "".join(traceback.format_exception(type(exc), exc, exc.__traceback__))
+ return "".join(traceback.format_exception(exc))
except Exception: # noqa: BLE001 - formatting must never fail the report
return f""
@@ -214,23 +214,26 @@ def post_webhook(payload: dict[str, Any], config: WebhookConfig) -> bool:
def _dedupe_key(exc: BaseException) -> tuple:
- location = None
- tb = exc.__traceback__
- while tb is not None and tb.tb_next is not None:
- tb = tb.tb_next
- if tb is not None:
- location = (tb.tb_frame.f_code.co_filename, tb.tb_lineno)
+ frames = traceback.extract_tb(exc.__traceback__)
+ location = (frames[-1].filename, frames[-1].lineno) if frames else None
return (type(exc).__qualname__, _safe_str(exc)[:200], location)
-def _toast(message: str) -> None:
- """Show an error toast in the current session, if it has a notification area."""
+def notify(level: str, message: str, **kwargs) -> None:
+ """Emit a Panel notification, or do nothing if the session has no area.
+
+ `pn.state.notifications` is None outside a served session (tests, scripts).
+ Reaching through it unguarded raises inside a Bokeh callback, and Bokeh
+ discards every pending document write when a locked callback raises -- so
+ one missing notification silently loses all the plot updates the callback
+ had already made. Swallowing the notification is always the lesser evil.
+ """
try:
notifications = pn.state.notifications
if notifications is not None:
- notifications.error(message, duration=10_000)
+ getattr(notifications, level)(message, **kwargs)
except Exception:
- logger.debug("Could not show error toast", exc_info=True)
+ logger.debug("Could not show %s notification", level, exc_info=True)
class ErrorReporter:
@@ -286,7 +289,7 @@ def _report(self, exc: BaseException, context: str | None, notify_user: bool) ->
message = _truncate(message, MAX_TOAST_CHARS)
if config.enabled:
message += " (the error has been reported)"
- _toast(message)
+ notify("error", message, duration=10_000)
if config.enabled and self._should_send(exc, config):
self._dispatch(build_payload(exc, context, _current_session_id()), config)
diff --git a/pixelmap/gui/gui.py b/pixelmap/gui/gui.py
index 65078f6..61a73dd 100644
--- a/pixelmap/gui/gui.py
+++ b/pixelmap/gui/gui.py
@@ -16,6 +16,7 @@
from dataclasses import dataclass, field
from io import BytesIO, StringIO
from pathlib import Path
+from typing import Any
import matplotlib.pyplot as plt
import numpy as np
@@ -59,6 +60,7 @@
SUPPORTED_QuadBase_PRESETS,
)
from pixelmap.error_reporting import guarded
+from pixelmap.error_reporting import notify as _notify
from pixelmap.types import Electrode
from pixelmap.utils import imro, survey, url_share
from pixelmap.utils.survey import default_survey_range
@@ -85,19 +87,6 @@
pn.extension(*PANEL_EXTENSIONS, notifications=True)
-def _notify(level: str, message: str, **kwargs) -> None:
- """Emit a Panel notification, or do nothing if the session has no area.
-
- `pn.state.notifications` is None outside a served session (tests, scripts).
- Reaching through it unguarded raises inside a Bokeh callback, and Bokeh
- discards every pending document write when a locked callback raises -- so
- one missing notification silently loses all the plot updates the callback
- had already made. Swallowing the notification is always the lesser evil.
- """
- notifications = pn.state.notifications
- if notifications is None:
- return
- getattr(notifications, level)(message, **kwargs)
@functools.lru_cache(maxsize=16)
@@ -159,14 +148,13 @@ class _AnatomyRequest:
pitch_deg: float
yaw_deg: float
shank_orientation_deg: float
- width: float
- label_offset: float
bregma_um: tuple | None
ap_squish: float
ml_squish: float
dv_squish: float
tilt_deg: float
generation: int
+ locator_fig: Any = None # reused across renders; see _compute_anatomy
@dataclass
@@ -177,6 +165,7 @@ class _AnatomyResult:
error: Exception | None = None
locator_html: str | None = None
tip_depth: float | None = None
+ locator_fig: Any = None
###################################
@@ -357,6 +346,21 @@ def __init__(self, **params):
self.survey_color_bar_title = None
self._survey_range_suspend = False
+ # Anatomy overlay state. Once an overlay is requested, live-update it
+ # whenever any pose / bregma / squish / tilt input changes; set on
+ # Compute, not on the first draw, so edits made while that first
+ # compute runs reach it too.
+ self._anatomy_overlay_active = False
+ # Off-loop compute bookkeeping (see _drain_anatomy_requests): whether
+ # inputs changed since the last compute started, whether a compute is
+ # running, a counter bumped by Clear so a compute that outlives its
+ # overlay is dropped, and a flag batched field writes set to hold off
+ # recomputes until they're done.
+ self._anatomy_dirty = False
+ self._anatomy_compute_running = False
+ self._anatomy_generation = 0
+ self._suppress_anatomy_recompute = False
+
# Load initial data
self.load_probe_data()
@@ -1050,7 +1054,7 @@ def generate_pdf_content(self):
# Collect anatomy overlay data (if active)
anatomy_bands = None
- if getattr(self, "_anatomy_overlay_active", False):
+ if self._anatomy_overlay_active:
band_src = self.region_band_source.data
if band_src["x"]:
plot_centers = self._shank_plot_centers()
@@ -1315,13 +1319,11 @@ async def _on_compute_anatomy_click(self, event):
def _request_anatomy_recompute(self):
"""Schedule an off-loop overlay recompute from a synchronous callback.
- Coalesces: while a compute is in flight this only marks the overlay
- dirty, and the running drain picks up the latest inputs when it
- finishes, so a burst of edits costs one extra compute, not one each.
+ Coalesces: while a compute is in flight the new drain returns at once,
+ and the running one picks up the latest inputs when it finishes, so a
+ burst of edits costs one extra compute, not one each.
"""
self._anatomy_dirty = True
- if self._anatomy_compute_running:
- return
pn.state.execute(self._drain_anatomy_requests)
@pn.io.with_lock
@@ -1347,7 +1349,7 @@ async def _drain_anatomy_requests(self):
try:
while self._anatomy_dirty and self._anatomy_overlay_active:
self._anatomy_dirty = False
- name = str(self.atlas_name_input.value).strip()
+ name = self._selected_atlas_name()
if not anatomy_atlas.is_downloaded(name):
self.compute_anatomy_button.name = _BUTTON_DOWNLOADING
self.compute_anatomy_button.disabled = True
@@ -1378,29 +1380,18 @@ async def _drain_anatomy_requests(self):
self.compute_anatomy_button.disabled = False
def compute_anatomy_overlay(self):
- """Compute region bands for the current pose and render them, inline.
+ """Compute and draw the overlay for the current pose (the Compute button).
- Synchronous, so it blocks the calling thread for the whole compute (and
- any download). Fine for scripts, notebooks and tests; GUI callbacks go
- through :meth:`_request_anatomy_recompute` instead, which keeps the work
- off the event loop.
+ Runs the same off-loop drain as the GUI. With no event loop running
+ (scripts, tests) Panel runs it to completion before returning; inside a
+ running loop (the served app, Jupyter) it is scheduled instead.
"""
self._anatomy_overlay_active = True
- name = str(self.atlas_name_input.value).strip()
- if self._origin_spec(name)["status"] == "ac_pending":
- try:
- anatomy_atlas.derive_origin_from_ac(name)
- except Exception as exc: # noqa: BLE001 - AC not derivable: banner stays "pending"
- print(f"Anterior-commissure lookup failed: {exc}")
- else:
- self._fill_reference_params()
- request = self._anatomy_request()
- self._apply_anatomy(request, self._compute_anatomy(request))
+ self._request_anatomy_recompute()
def _anatomy_request(self) -> _AnatomyRequest:
"""Snapshot the overlay's inputs. Event loop only; cheap, no atlas reads."""
- atlas_name = str(self.atlas_name_input.value).strip()
- width = self._shank_plot_width()
+ atlas_name = self._selected_atlas_name()
# Bregma dot whenever an estimate exists or we're in bregma mode (using
# the current, possibly-edited, values). DV-squish + tilt warp the brain
# image only in bregma mode (where the squish/tilt inputs are live).
@@ -1429,25 +1420,20 @@ def _anatomy_request(self) -> _AnatomyRequest:
pitch_deg=float(self.pitch_input.value),
yaw_deg=float(self.yaw_input.value),
shank_orientation_deg=float(self.shank_orientation_input.value),
- width=width,
- # Pull label text outside the shank outline so it doesn't overlap
- # the electrode rects; the offset widens when a survey overlay is
- # loaded so labels clear the survey sidebar bars.
- label_offset=self._region_label_offset(width / 2),
bregma_um=bregma_um,
ap_squish=ap_squish,
ml_squish=ml_squish,
dv_squish=dv_squish,
tilt_deg=tilt_deg,
generation=self._anatomy_generation,
+ locator_fig=self._locator_fig,
)
def _compute_anatomy(self, req: _AnatomyRequest) -> _AnatomyResult:
"""Every atlas read an overlay needs. Runs in a worker thread.
- Must not touch widgets or Bokeh models — only ``req`` and the atlas.
- The one piece of session state it uses, ``_locator_fig``, is only ever
- touched by the single in-flight compute.
+ Must not touch widgets, Bokeh models or session state — only ``req``
+ and the atlas.
"""
try:
bands = compute_region_bands(
@@ -1463,7 +1449,7 @@ def _compute_anatomy(self, req: _AnatomyRequest) -> _AnatomyResult:
except Exception as exc: # noqa: BLE001 - any lookup failure is reported to the user
return _AnatomyResult(error=exc)
- result = _AnatomyResult(bands=bands)
+ result = _AnatomyResult(bands=bands, locator_fig=req.locator_fig)
try:
# Reuse this session's figure: building one per render cost 3.1 MB
# of RSS per overlay compute, and the overlay recomputes on every
@@ -1481,9 +1467,9 @@ def _compute_anatomy(self, req: _AnatomyRequest) -> _AnatomyResult:
ml_squish=req.ml_squish,
dv_squish=req.dv_squish,
tilt_deg=req.tilt_deg,
- fig=self._locator_fig,
+ fig=req.locator_fig,
)
- self._locator_fig = fig
+ result.locator_fig = fig
result.locator_html = self._fig_to_locator_html(fig)
except Exception as exc: # noqa: BLE001 - a failed locator shouldn't sink the overlay
print(f"Locator render failed: {exc}")
@@ -1499,17 +1485,24 @@ def _compute_anatomy(self, req: _AnatomyRequest) -> _AnatomyResult:
def _apply_anatomy(self, req: _AnatomyRequest, result: _AnatomyResult):
"""Draw a finished compute. Event loop only (writes Bokeh models)."""
- if req.generation != self._anatomy_generation or not self._anatomy_overlay_active:
- return # cleared while computing: drop the stale result
+ if req.generation != self._anatomy_generation:
+ # Cleared while computing: drop the stale result.
+ if result.locator_fig is not self._locator_fig:
+ plt.close(result.locator_fig)
+ return
+ self._locator_fig = result.locator_fig
self._refresh_compute_button()
if result.error is not None:
print(f"Anatomy lookup failed: {result.error}")
return
bands = result.bands
- width = req.width
+ width = self._shank_plot_width()
half_width = width / 2
- label_offset = req.label_offset
+ # Pull label text outside the shank outline so it doesn't overlap the
+ # electrode rects; the offset widens when a survey overlay is loaded so
+ # labels clear the survey sidebar bars.
+ label_offset = self._region_label_offset(half_width)
plot_centers = req.plot_centers
band_data = {"x": [], "y": [], "width": [], "height": [], "color": [], "acronym": []}
@@ -1642,7 +1635,7 @@ def _anatomy_coord_note_html(self) -> str:
native code as an FYI, but only when the atlas is already downloaded so
switching atlases in the dropdown stays cheap.
"""
- name = str(self.atlas_name_input.value).strip()
+ name = self._selected_atlas_name()
native = None
try:
if anatomy_atlas.is_downloaded(name):
@@ -1688,10 +1681,10 @@ def _on_atlas_change(self, *events):
self.bregma_estimate_header.object = self._bregma_header_html()
# Reflect download state in the button label so users know before clicking.
self._refresh_compute_button()
- name = str(self.atlas_name_input.value).strip()
- if getattr(self, "_anatomy_overlay_active", False):
+ name = self._selected_atlas_name()
+ if self._anatomy_overlay_active:
# The recompute locates a pending AC origin on its way through.
- self._recompute_anatomy_if_active()
+ self._request_anatomy_recompute()
elif (self._origin_spec(name)["status"] == "ac_pending"
and anatomy_atlas.is_downloaded(name)):
# No overlay to do it, but the atlas is local, so the origin can be
@@ -1711,7 +1704,7 @@ async def _locate_ac_origin(self, name: str):
except Exception as exc: # noqa: BLE001 - AC not derivable: banner stays "pending"
print(f"Anterior-commissure lookup failed: {exc}")
return
- if str(self.atlas_name_input.value).strip() == name: # still selected
+ if self._selected_atlas_name() == name: # still selected
self._fill_reference_params()
def _fill_reference_params(self):
@@ -1722,7 +1715,7 @@ def _fill_reference_params(self):
def _refresh_compute_button(self):
"""Label the Compute button by whether the selected atlas is local."""
- downloaded = anatomy_atlas.is_downloaded(str(self.atlas_name_input.value).strip())
+ downloaded = anatomy_atlas.is_downloaded(self._selected_atlas_name())
self.compute_anatomy_button.name = _BUTTON_COMPUTE if downloaded else _BUTTON_DOWNLOAD
@contextlib.contextmanager
@@ -1797,28 +1790,8 @@ def _update_anatomy_origin_note(self, *events):
"""Refresh the coordinate note when the atlas selection changes."""
self.anatomy_coord_note.object = self._anatomy_coord_note_html()
- def _atlas_is_downloaded(self) -> bool:
- """True if the selected atlas is on disk, so reading it won't download."""
- try:
- return anatomy_atlas.is_downloaded(str(self.atlas_name_input.value).strip())
- except Exception: # noqa: BLE001 - unreadable atlas means not downloaded
- return False
-
- def _tip_depth_below_surface(self) -> float | None:
- """Tip-to-brain-surface distance along the probe axis, in µm.
-
- ``None`` when it can't be computed: the atlas isn't downloaded (we
- never trigger a download just to refresh a readout), the tip is outside
- the brain, or the atlas lookup failed.
- """
- if not self._atlas_is_downloaded():
- return None
- return _measure_tip_depth(
- self._tip_atlas_um(),
- float(self.pitch_input.value),
- float(self.yaw_input.value),
- str(self.atlas_name_input.value).strip(),
- )
+ def _selected_atlas_name(self) -> str:
+ return str(self.atlas_name_input.value).strip()
def _tip_depth_readout_html(self, depth: float | None) -> str:
"""Banner text for the depth-below-surface readout above the tip fields.
@@ -1831,18 +1804,12 @@ def _tip_depth_readout_html(self, depth: float | None) -> str:
``depth`` is measured by the off-loop overlay compute; this never reads
the atlas itself, so it is safe on the event loop.
"""
- if not getattr(self, "_anatomy_overlay_active", False):
+ if not self._anatomy_overlay_active:
value_html = (
'—'
' '
"(compute the overlay below)"
)
- elif not self._atlas_is_downloaded():
- value_html = (
- '—'
- ' '
- "(available once the atlas is downloaded)"
- )
else:
if depth is None:
value_html = (
@@ -1998,9 +1965,9 @@ def _on_bregma_toggle(self, *events):
def _recompute_anatomy_if_active(self, *events):
"""Re-run the overlay on input changes, but only once one exists."""
- if getattr(self, "_suppress_anatomy_recompute", False):
+ if self._suppress_anatomy_recompute:
return
- if getattr(self, "_anatomy_overlay_active", False):
+ if self._anatomy_overlay_active:
self._request_anatomy_recompute() # never inline: see _drain_anatomy_requests
def _update_anatomy_legend(self, bands: list):
@@ -2872,19 +2839,6 @@ def create_widgets(self):
self.atlas_name_input.param.watch(self._on_atlas_change, "value")
self.bregma_relative_toggle.param.watch(self._on_bregma_toggle, "value")
- # Once an overlay is requested, live-update it (bands + slices) whenever
- # any pose / bregma / squish / tilt input changes, so edits are visible
- # immediately instead of only on the next Compute click. Set on
- # Compute, not on the first draw, so edits made while that first
- # compute runs reach it too.
- self._anatomy_overlay_active = False
- # Off-loop compute bookkeeping (see _drain_anatomy_requests): whether
- # inputs changed since the last compute started, whether a compute is
- # running, and a counter bumped by Clear so a compute that outlives its
- # overlay is dropped.
- self._anatomy_dirty = False
- self._anatomy_compute_running = False
- self._anatomy_generation = 0
# atlas_name + bregma toggle do their own batched recompute (via
# _on_atlas_change / _on_bregma_toggle), so they're not in this list.
for _w in (self.tip_ap_input, self.tip_ml_input, self.tip_dv_input,
diff --git a/pixelmap/utils/imro.py b/pixelmap/utils/imro.py
index 5d9d3af..faedb8f 100644
--- a/pixelmap/utils/imro.py
+++ b/pixelmap/utils/imro.py
@@ -5,7 +5,6 @@
import numpy as np
import pandas as pd
-import panel as pn
from pixelmap.backend import format_imro_string, get_electrodes
from pixelmap.constants import (
@@ -192,23 +191,26 @@ def parse_imro_list(imro_list):
hp_filter)
+def _fail(message):
+ """Toast ``message`` in the GUI session, if any, then raise it."""
+ # Imported here so `import pixelmap` doesn't pull in Panel and Bokeh.
+ from pixelmap.error_reporting import notify
+
+ notify("error", message, duration=10_000)
+ raise AssertionError(message)
+
+
def ref_id_to_string(reference_id, imro_fmt):
ref_map = {v: k for k, v in REF_ELECTRODES[imro_fmt].items() if k != "Join Tips"}
if reference_id not in ref_map:
- error_message = f"Unexpected reference id {reference_id} for IMRO format {imro_fmt}!"
- pn.state.notifications.error(error_message,
- duration=10_000)
- raise AssertionError(error_message)
+ _fail(f"Unexpected reference id {reference_id} for IMRO format {imro_fmt}!")
return ref_map[reference_id]
def check_entry_elements(n_expected_elements, entry, probe_type):
n_entry_elements = len(entry)
if n_entry_elements != n_expected_elements:
- error_message = f"Corrupt .imro file - IMRO table entries for {probe_type} probes should have {n_expected_elements} elements, not {n_entry_elements}."
- pn.state.notifications.error(error_message,
- duration=10_000)
- raise AssertionError(error_message)
+ _fail(f"Corrupt .imro file - IMRO table entries for {probe_type} probes should have {n_expected_elements} elements, not {n_entry_elements}.")
def generate_imro_channelmap(
diff --git a/pixelmap/utils/survey.py b/pixelmap/utils/survey.py
index a5550d6..3b45f23 100644
--- a/pixelmap/utils/survey.py
+++ b/pixelmap/utils/survey.py
@@ -81,13 +81,11 @@ def parse_survey_file(content: str) -> pd.DataFrame:
f"Expected header: Shank\\tXum\\tZum\\tVal."
)
- df = df[list(SURVEY_COLUMNS)]
- df = df.assign(
- shank=pd.to_numeric(df["shank"], errors="raise"),
- xum=pd.to_numeric(df["xum"], errors="raise"),
- zum=pd.to_numeric(df["zum"], errors="raise"),
- val=pd.to_numeric(df["val"], errors="raise"),
- ).astype({"shank": int, "xum": int, "zum": int, "val": float})
+ df = (
+ df[list(SURVEY_COLUMNS)]
+ .apply(pd.to_numeric, errors="raise")
+ .astype({"shank": int, "xum": int, "zum": int, "val": float})
+ )
return df
diff --git a/tests/test_anatomy_atlas.py b/tests/test_anatomy_atlas.py
index 21b2b68..0ce71ce 100644
--- a/tests/test_anatomy_atlas.py
+++ b/tests/test_anatomy_atlas.py
@@ -215,15 +215,6 @@ def _boom(name):
atlas_module.derive_origin_from_ac("c")
assert atlas_module.peek_origin_from_ac("c") == (False, None)
- def test_origin_memo_is_bounded_and_evicts_oldest_first(self, monkeypatch):
- monkeypatch.setattr(atlas_module, "_derive_origin_from_ac", lambda name: (0.0, 0.0, 0.0))
- size = atlas_module._AC_ORIGIN_MEMO_SIZE
- for i in range(size + 1):
- atlas_module.derive_origin_from_ac(f"atlas{i}")
- assert atlas_module.peek_origin_from_ac("atlas0") == (False, None)
- assert atlas_module.peek_origin_from_ac(f"atlas{size}")[0] is True
- assert len(atlas_module._ac_origin_memo) == size
-
def test_concurrent_callers_share_one_scan(self, monkeypatch):
"""Several sessions picking the same human atlas pay for one scan."""
import threading
diff --git a/tests/test_gui_overlays.py b/tests/test_gui_overlays.py
index 1fd8054..4d6c458 100644
--- a/tests/test_gui_overlays.py
+++ b/tests/test_gui_overlays.py
@@ -364,6 +364,16 @@ def test_clearing_wipes_every_anatomy_layer(self, posed_gui):
assert "No anatomical overlay computed yet" in posed_gui.anatomy_legend.object
+def _measured_depth(gui):
+ """The depth the overlay compute would measure for ``gui``'s current pose."""
+ return gui_module._measure_tip_depth(
+ gui._tip_atlas_um(),
+ float(gui.pitch_input.value),
+ float(gui.yaw_input.value),
+ gui._selected_atlas_name(),
+ )
+
+
class TestTipDepthReadout:
"""The readout is tied to the overlay: blank until Compute, blank after Clear."""
@@ -396,38 +406,42 @@ def test_readout_follows_the_tip_once_an_overlay_exists(self, posed_gui):
posed_gui.compute_anatomy_overlay()
posed_gui.tip_dv_input.value = 2000.0 # 1 mm below the fake surface
assert "1,0" in posed_gui.tip_depth_readout.object
- assert posed_gui._tip_depth_below_surface() == pytest.approx(1012.5, abs=25.0)
+ assert _measured_depth(posed_gui) == pytest.approx(1012.5, abs=25.0)
def test_tilting_the_probe_lengthens_the_measured_path(self, posed_gui):
posed_gui.compute_anatomy_overlay()
- vertical = posed_gui._tip_depth_below_surface()
+ vertical = _measured_depth(posed_gui)
posed_gui.pitch_input.value = 30.0
- tilted = posed_gui._tip_depth_below_surface()
+ tilted = _measured_depth(posed_gui)
assert tilted > vertical
assert tilted == pytest.approx(vertical / np.cos(np.deg2rad(30.0)), abs=30.0)
def test_tip_above_the_brain_is_reported_as_outside(self, posed_gui):
posed_gui.compute_anatomy_overlay()
posed_gui.tip_dv_input.value = 100.0
- assert posed_gui._tip_depth_below_surface() is None
+ assert _measured_depth(posed_gui) is None
assert "outside the brain" in posed_gui.tip_depth_readout.object
- def test_undownloaded_atlas_is_reported_without_triggering_a_download(
- self, posed_gui, monkeypatch
+ @pytest.mark.parametrize("depth", [None, 0.0, 1012.5])
+ def test_refreshing_the_readout_never_reads_the_atlas(
+ self, posed_gui, monkeypatch, depth
):
- """Refreshing a readout must never kick off a tens-of-MB download."""
+ """The readout runs on the event loop, so it must only format a depth
+ the off-loop compute already measured — never touch the atlas, which
+ could mean a tens-of-MB download."""
posed_gui.compute_anatomy_overlay()
- def _boom(name):
- raise AssertionError("must not read an atlas that isn't downloaded")
+ def _boom(*args, **kwargs):
+ raise AssertionError("the readout read the atlas")
- monkeypatch.setattr(atlas_module, "is_downloaded", lambda name: False)
+ monkeypatch.setattr(atlas_module, "is_downloaded", _boom)
# regions.py imports the symbol directly, so patch it where it's used.
monkeypatch.setattr(regions_module, "canonical_annotation", _boom)
- posed_gui._update_tip_depth_readout()
+ posed_gui._update_tip_depth_readout(depth)
- assert "once the atlas is downloaded" in posed_gui.tip_depth_readout.object
+ expected = "outside the brain" if depth is None else f"{depth:,.0f} µm"
+ assert expected in posed_gui.tip_depth_readout.object
class TestBothOverlaysTogether:
diff --git a/tests/test_pdf_export.py b/tests/test_pdf_export.py
index f9d0c3d..8d15a96 100644
--- a/tests/test_pdf_export.py
+++ b/tests/test_pdf_export.py
@@ -18,7 +18,7 @@
import matplotlib.pyplot as plt
import numpy as np
import pytest
-from matplotlib.collections import PatchCollection
+from matplotlib.collections import PolyCollection
from pixelmap import backend
from pixelmap.gui.gui import ChannelmapGUI
@@ -104,11 +104,11 @@ def _rgba(c):
def _electrode_collections(ax):
- """Per-shank electrode PatchCollections, in shank order (survey bars excluded)."""
+ """Per-shank electrode PolyCollections, in shank order (survey bars excluded)."""
return [
c
for c in ax.collections
- if isinstance(c, PatchCollection) and c.get_zorder() != SURVEY_BAR_ZORDER
+ if isinstance(c, PolyCollection) and c.get_zorder() != SURVEY_BAR_ZORDER
]
@@ -124,7 +124,7 @@ def test_electrodes_drawn_as_collections(gui, probe_type, with_survey):
kwargs = {"survey_colors": {(0, 0): "#ff0000"}, "survey_range": (0.0, 1.0)}
ax = _plot(gui, **kwargs)
- collections = [c for c in ax.collections if isinstance(c, PatchCollection)]
+ collections = [c for c in ax.collections if isinstance(c, PolyCollection)]
per_shank = 2 if with_survey else 1
assert len(collections) == n_shanks * per_shank
# Only shank outlines / anatomy bands remain as standalone patches.
@@ -191,5 +191,5 @@ def test_no_forbidden_electrodes(gui, probe_type, monkeypatch):
def test_add_rects_empty_is_noop():
_fig, ax = plt.subplots()
- backend._add_rects(ax, [], [])
+ backend._add_rects(ax, [], [], 1.0, 1.0, [])
assert len(ax.collections) == 0
diff --git a/tests/test_public_api.py b/tests/test_public_api.py
index f8770b0..e94804c 100644
--- a/tests/test_public_api.py
+++ b/tests/test_public_api.py
@@ -67,6 +67,7 @@
"pickle",
"Path",
"PatchCollection",
+ "PolyCollection",
"pn",
]
@@ -202,3 +203,13 @@ def test_documented_workflow_round_trips(tmp_path, probe_type, preset):
assert parsed_probe_type == probe_type
assert len(selected) == 384
assert len(np.unique(selected, axis=0)) == 384
+
+
+def test_importing_the_package_does_not_load_the_gui_stack():
+ """Script/API users shouldn't pay ~0.7 s to import Panel and Bokeh."""
+ import subprocess
+ import sys
+
+ code = "import sys, pixelmap; print(sorted({'panel', 'bokeh'} & set(sys.modules)))"
+ out = subprocess.run([sys.executable, "-c", code], capture_output=True, text=True, check=True)
+ assert out.stdout.strip() == "[]"
diff --git a/tests/test_wiring_lookup.py b/tests/test_wiring_lookup.py
index 8e83d4a..6315763 100644
--- a/tests/test_wiring_lookup.py
+++ b/tests/test_wiring_lookup.py
@@ -231,3 +231,37 @@ def test_lookups_much_faster_than_per_electrode_scan():
backend.find_electrode_coordinates(sel, wiring_df),
))
assert new * 5 < old, f"new {new * 1000:.0f} ms vs reference {old * 1000:.0f} ms"
+
+
+# --------------------------------------------------------------------------
+# Wiring-map rebuild
+# --------------------------------------------------------------------------
+
+def _copy_wiring_csvs(tmp_path):
+ for csv in WIRING_DIR.glob("*.csv"):
+ (tmp_path / csv.name).write_bytes(csv.read_bytes())
+ return tmp_path
+
+
+def test_rebuilt_wiring_maps_match_the_shipped_cache(tmp_path):
+ """No pickle: the maps are rebuilt from the CSVs, identical to the shipped ones."""
+ import pickle
+
+ rebuilt = backend._load_wiring_maps(str(_copy_wiring_csvs(tmp_path)))
+ with open(WIRING_DIR / "wiring_maps.pkl", "rb") as f:
+ shipped = pickle.load(f)
+ assert {k: dict(v) for k, v in rebuilt.items()} == {
+ k: {e: frozenset(c) for e, c in v.items()} for k, v in shipped.items()
+ }
+
+
+def test_rebuild_indexes_each_wiring_table_once(tmp_path, monkeypatch):
+ """Re-indexing per electrode made a cold rebuild take ~55 s, inside the
+ first session's GUI constructor on the event loop."""
+ calls = []
+ real = backend._wiring_index
+ monkeypatch.setattr(backend, "_wiring_index", lambda df: calls.append(1) or real(df))
+
+ backend._load_wiring_maps(str(_copy_wiring_csvs(tmp_path)))
+
+ assert len(calls) == len(WIRING_FILE_MAP)