Pure-python surf2surf matrix (direct nnfr construction)

.github/workflows/build_docs.yml

@@ -11,11 +11,15 @@ on:
       - main
   workflow_dispatch:  # Manual trigger for publishing docs
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
 jobs:
   build-docs:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v6
+    - uses: actions/checkout@v7
       with:
         fetch-depth: 0  # Required for setuptools-scm to get version from tags
 
@@ -48,6 +52,8 @@ jobs:
       with:
         path: ~/.cache/ms-playwright
         key: ${{ runner.os }}-playwright-${{ hashFiles('**/pyproject.toml') }}
+        restore-keys: |
+          ${{ runner.os }}-playwright-
 
     - name: Install Playwright Chromium
       run: playwright install --with-deps --only-shell chromium

.github/workflows/codespell.yml

@@ -7,6 +7,10 @@ on:
   pull_request:
     branches: [main]
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
 permissions:
   contents: read
 
@@ -17,6 +21,6 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v6
+        uses: actions/checkout@v7
       - name: Codespell
         uses: codespell-project/actions-codespell@v2

.github/workflows/install_from_wheel.yml

@@ -8,6 +8,10 @@ on:
     branches:
       - main
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
 jobs:
   install-from-wheel:
     runs-on: ubuntu-latest
@@ -17,7 +21,7 @@ jobs:
       max-parallel: 5
 
     steps:
-    - uses: actions/checkout@v6
+    - uses: actions/checkout@v7
     - name: Set up Python
       uses: actions/setup-python@v6
       with:

.github/workflows/publish.yml

@@ -12,7 +12,7 @@ jobs:
       contents: read  # Required to checkout the repository
 
     steps:
-    - uses: actions/checkout@v6
+    - uses: actions/checkout@v7
       with:
         fetch-depth: 0  # Required for setuptools-scm to get version from tags
 

.github/workflows/run_tests.yml

@@ -8,6 +8,10 @@ on:
     branches:
       - main
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
 jobs:
   run-tests:
     runs-on: ubuntu-latest
@@ -17,7 +21,7 @@ jobs:
       max-parallel: 5
 
     steps:
-    - uses: actions/checkout@v6
+    - uses: actions/checkout@v7
     - name: Set up Python
       uses: actions/setup-python@v6
       with:
@@ -47,16 +51,18 @@ jobs:
       with:
         path: ~/.cache/ms-playwright
         key: ${{ runner.os }}-playwright-${{ hashFiles('**/pyproject.toml') }}
+        restore-keys: |
+          ${{ runner.os }}-playwright-
 
     - name: Install Playwright Chromium
       run: playwright install --with-deps --only-shell chromium
 
     - name: Test with pytest
-      timeout-minutes: 20  # in case webviewer tests hang
+      timeout-minutes: 25  # in case webviewer tests hang
       run: pytest --cov=./
 
     - name: Upload coverage to Codecov
-      uses: codecov/codecov-action@v6
+      uses: codecov/codecov-action@v7
       with:
         env_vars: OS,PYTHON
         fail_ci_if_error: true

.gitignore

@@ -69,3 +69,7 @@ docs/colormaps.rst
 
 # Git worktrees
 .worktrees
+
+# Claude Code working directory (per-worktree scratch: launchers, verify
+# scripts, plans). Not part of the project.
+.claude

cortex/dataset/braindata.py

@@ -1,4 +1,5 @@
 import hashlib
+import warnings
 from copy import deepcopy
 import sys
 from typing import Generic, Optional, TypeVar, Union, cast
@@ -552,7 +553,33 @@ def right(self):
     def blend_curvature(self, alpha, threshold=0, brightness=0.5,
                         contrast=0.25, smooth=20):
         """Blend the data with a curvature map depending on a transparency map.
-
+
+        .. deprecated::
+            Per-vertex/voxel alpha is now honored directly by both the WebGL
+            viewer and ``cortex.quickshow``, so this curvature-blending hack
+            is no longer needed. The recommended replacement for scalar data
+            with a transparency map is :class:`Vertex2D` (or
+            :class:`Volume2D`) with a 2D colormap whose second axis encodes
+            alpha (e.g. ``"fire_alpha"``, ``"PU_RdBu_covar_alpha"``)::
+
+                # Was:
+                #   blended = vtx.blend_curvature(alpha)
+                #   cortex.quickshow(blended)
+                # Now:
+                v2d = cortex.Vertex2D(vtx.data, alpha, subject,
+                                      cmap="fire_alpha",
+                                      vmin=vtx.vmin, vmax=vtx.vmax,
+                                      vmin2=0, vmax2=1)
+                cortex.quickshow(v2d)         # or cortex.webgl.show(v2d)
+
+            The 2D colormap path keeps colormap parameters (``cmap``,
+            ``vmin``, ``vmax``) editable on the resulting object, and the
+            curvature underlay is composited through automatically by both
+            the matplotlib and WebGL renderers.
+
+            For data that is already RGB, pass ``alpha=`` to
+            :class:`VertexRGB` / :class:`VolumeRGB` directly instead.
+
         Vertex objects cannot use transparency as Volume objects. This method
         is a hack to mimic the transparency of Volume objects, blending the
         Vertex data with a curvature map. This method returns a VertexRGB
@@ -577,6 +604,19 @@ def blend_curvature(self, alpha, threshold=0, brightness=0.5,
         blended : VertexRGB object
             The original map blended with a curvature map.
         """
+        warnings.warn(
+            "blend_curvature is deprecated and will be removed in a future "
+            "release. Per-vertex/voxel alpha is now honored directly by both "
+            "the WebGL viewer and quickshow, so this curvature-blending hack "
+            "is no longer needed. For scalar data with a transparency map, "
+            "use Vertex2D / Volume2D with a 2D colormap whose second axis "
+            "encodes alpha (e.g. 'fire_alpha', 'PU_RdBu_covar_alpha'), e.g. "
+            "`Vertex2D(data, alpha, subject, cmap='fire_alpha', vmin=..., "
+            "vmax=..., vmin2=0, vmax2=1)`. For data that is already RGB, "
+            "pass `alpha=` to VertexRGB / VolumeRGB directly.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         from .views import Vertex
         from .viewRGB import VertexRGB
         # prepare curvature map

cortex/export/headless.py

@@ -42,6 +42,7 @@
 import contextlib
 import logging
 import threading
+import time
 from typing import Any, Mapping, Optional
 
 import cortex
@@ -50,6 +51,49 @@
 logger = logging.getLogger(__name__)
 
 
+def _wait_for_viewer_loaded(handle, timeout: float = 60.0) -> None:
+    """Block until ``window.viewer.loaded`` resolves in the browser.
+
+    The WebSocket "connect" message fires as soon as the page DOM is ready,
+    but the WebGL viewer's CTM mesh download, parse, and initial render
+    typically take a few more seconds. ``viewer.loaded`` is a jQuery
+    Deferred that resolves at the end of ``setData`` (mriview.js), so polling
+    its ``.state()`` is a faithful "the viewer is ready to be driven"
+    signal that replaces brittle fixed sleeps in callers and tests.
+
+    We bypass the JSProxy attribute machinery and call ``send`` directly so
+    each poll is exactly one WebSocket roundtrip (the JSProxy ``__getattr__``
+    path would issue an extra ``query`` call per poll).
+    """
+    deadline = time.monotonic() + timeout
+    poll_interval = 0.1
+    last_err: Optional[str] = None
+    while time.monotonic() < deadline:
+        try:
+            result = handle.send(
+                method="run", params=["window.viewer.loaded.state", []]
+            )
+        except Exception as exc:
+            last_err = repr(exc)
+            result = None
+        # WebApp.send always wraps its single per-client response in a list;
+        # unpack the leaf so the "resolved"/"pending"/error-dict check below
+        # is straightforward and last_err carries the actual value seen.
+        val = result[0] if isinstance(result, list) and result else result
+        if val == "resolved":
+            return
+        if val is not None:
+            last_err = (
+                str(val.get("error", val)) if isinstance(val, dict) else str(val)
+            )
+        time.sleep(poll_interval)
+    raise RuntimeError(
+        f"Viewer's .loaded deferred did not resolve within {timeout:.0f}s "
+        f"(last response: {last_err!r}). The CTM mesh may have failed to "
+        "download or parse, or mriview.js failed to initialise."
+    )
+
+
 # --------------------------------------------------------------------------- #
 # Helper: run Playwright in a dedicated thread to avoid asyncio conflicts     #
 # --------------------------------------------------------------------------- #
@@ -337,6 +381,12 @@ def headless_viewer(
         # any point during the session (each call returns a fresh snapshot).
         handle._pw_thread = pw_thread
 
+        # Block until the WebGL viewer has finished initialising (CTM mesh
+        # download + parse + first setData). Replaces ad-hoc time.sleep(10)
+        # calls in tests and callers, and shortens the wait when the
+        # browser is faster than the worst-case timeout.
+        _wait_for_viewer_loaded(handle, timeout=timeout)
+
         yield handle
 
     finally:

cortex/export/save_views.py

@@ -114,8 +114,12 @@ def save_3d_views(
         cm = contextlib.nullcontext(cortex.webshow(volume, **viewer_params))
 
     with cm as handle:
-        # Wait for the viewer to be loaded
-        time.sleep(sleep)
+        # Wait for the viewer to be loaded. The headless context manager
+        # already blocks on ``viewer.loaded`` before yielding, so we only
+        # need this fixed sleep for the interactive (real-browser) path
+        # where the user is opening the page manually.
+        if not headless:
+            time.sleep(sleep)
 
         # Add interpolation and layers params only if we have a volume
         if isinstance(volume, (cortex.Volume, cortex.Volume2D, cortex.VolumeRGB)):