arrayview 0.31.0__tar.gz → 0.31.1__tar.gz

{arrayview-0.31.0 → arrayview-0.31.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: arrayview
-Version: 0.31.0
+Version: 0.31.1
 Summary: Fast multi-dimensional array viewer
 Project-URL: Home, https://github.com/oscarvanderheide/arrayview
 Project-URL: Source, https://github.com/oscarvanderheide/arrayview

{arrayview-0.31.0 → arrayview-0.31.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "arrayview"
-version = "0.31.0"
+version = "0.31.1"
 description = "Fast multi-dimensional array viewer"
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.12"

{arrayview-0.31.0 → arrayview-0.31.1}/src/arrayview/_analysis.py

@@ -34,7 +34,15 @@ def _build_metadata(session) -> dict:
         "is_rgb": session.rgb_axis is not None,
         "has_source_file": bool(getattr(session, "filepath", None)),
     }
-    default_dims = _session_mod._startup_dims_for_data(session.data, target_shape)
+    collection_spatial_ndim = getattr(session, "collection_spatial_ndim", None)
+    default_shape = target_shape
+    if collection_spatial_ndim is not None:
+        spatial_ndim = int(collection_spatial_ndim)
+        if 2 <= spatial_ndim <= len(target_shape):
+            # Collection axes are appended after the image dimensions. They
+            # select a case; they must not influence the startup plane.
+            default_shape = target_shape[:spatial_ndim]
+    default_dims = _session_mod._startup_dims_for_data(session.data, default_shape)
     if default_dims is not None:
         meta["default_dims"] = [int(default_dims[0]), int(default_dims[1])]
     if getattr(session, "spatial_meta", None) is not None:
@@ -49,7 +57,6 @@ def _build_metadata(session) -> dict:
         )
     if getattr(session, "array_keys", None):
         meta["array_keys"] = session.array_keys
-    collection_spatial_ndim = getattr(session, "collection_spatial_ndim", None)
     if collection_spatial_ndim is not None:
         meta["collection_spatial_ndim"] = int(collection_spatial_ndim)
     if getattr(session.data, "_av_ragged", False):

{arrayview-0.31.0 → arrayview-0.31.1}/src/arrayview/_overlays.py

@@ -36,6 +36,7 @@ def _composite_overlays(
     dim_y: int,
     idx_tuple: tuple[int, ...],
     shape_hw: tuple[int, int],
+    base_shape: tuple[int, ...] | None = None,
 ) -> np.ndarray:
     """Composite one or more overlay masks onto RGBA pixels."""
     if not overlay_sid_str:
@@ -62,6 +63,7 @@ def _composite_overlays(
             dim_y,
             idx_tuple,
             expected_shape=shape_hw,
+            base_shape=base_shape,
         )
         rgba = _composite_overlay_mask(
             rgba,

{arrayview-0.31.0 → arrayview-0.31.1}/src/arrayview/_render.py

@@ -1,5 +1,6 @@
 """Rendering pipeline: colormaps, LUTs, slice extraction, RGBA, mosaic, RGB, preload."""
 
+import itertools
 import threading
 import time
 
@@ -527,6 +528,7 @@ def _extract_overlay_mask(
     dim_y: int,
     idx_tuple: tuple[int, ...],
     expected_shape: tuple[int, int],
+    base_shape: tuple[int, ...] | None = None,
 ) -> np.ndarray | None:
     """Return the raw overlay slice (float32 H×W) for compositing, or None.
 
@@ -538,27 +540,43 @@ def _extract_overlay_mask(
     if ov_session is None:
         return None
 
-    ov_ndim = ov_session.data.ndim
-    if dim_x >= ov_ndim or dim_y >= ov_ndim:
+    ov_shape = tuple(int(size) for size in ov_session.shape)
+    main_shape = tuple(int(size) for size in (base_shape or ov_shape))
+    if len(ov_shape) > len(main_shape):
         return None
 
-    idx_candidates: list[tuple[int, ...]] = [
-        tuple(int(idx_tuple[i]) if i < len(idx_tuple) else 0 for i in range(ov_ndim))
-    ]
-    if len(idx_tuple) >= ov_ndim:
-        trailing = tuple(int(v) for v in idx_tuple[-ov_ndim:])
-        if trailing != idx_candidates[0]:
-            idx_candidates.append(trailing)
-
-    for ov_idx in idx_candidates:
-        try:
-            ov_raw = extract_slice(ov_session, dim_x, dim_y, list(ov_idx))
-        except Exception:
-            continue
-        if ov_raw.shape != expected_shape:
-            continue
-        if np.any(np.isfinite(ov_raw) & (ov_raw != 0)):
-            return ov_raw.astype(np.float32)
+    # An overlay may omit one or more non-spatial dimensions from the base.
+    # Match its axes to equal-sized base axes, then index only those axes. This
+    # broadcasts the overlay over every omitted axis without allocating a tiled
+    # copy (important for masks next to multi-echo or multi-channel data).
+    map_key = (main_shape, dim_x, dim_y)
+    axis_maps = getattr(ov_session, "_overlay_axis_maps", None)
+    if axis_maps is None:
+        axis_maps = {}
+        ov_session._overlay_axis_maps = axis_maps
+    if map_key not in axis_maps:
+        axis_maps[map_key] = next(
+            (
+                base_axes
+                for base_axes in itertools.combinations(range(len(main_shape)), len(ov_shape))
+                if dim_x in base_axes
+                and dim_y in base_axes
+                and tuple(main_shape[axis] for axis in base_axes) == ov_shape
+            ),
+            None,
+        )
+    base_axes = axis_maps[map_key]
+    if base_axes is None:
+        return None
+    ov_dim_x = base_axes.index(dim_x)
+    ov_dim_y = base_axes.index(dim_y)
+    ov_idx = [int(idx_tuple[axis]) for axis in base_axes]
+    try:
+        ov_raw = extract_slice(ov_session, ov_dim_x, ov_dim_y, ov_idx)
+    except Exception:
+        return None
+    if ov_raw.shape == expected_shape:
+        return ov_raw.astype(np.float32)
     return None
 
 

{arrayview-0.31.0 → arrayview-0.31.1}/src/arrayview/_routes_rendering.py

@@ -251,6 +251,7 @@ def register_rendering_routes(app, *, get_session_or_404) -> None:
                     dim_y,
                     idx_tuple,
                     rgba.shape[:2],
+                    session.shape,
                 )
                 _, vmin, vmax = _prepare_display(
                     session,

{arrayview-0.31.0 → arrayview-0.31.1}/src/arrayview/_routes_websocket.py

@@ -25,6 +25,7 @@ from arrayview._session import (
     SESSIONS,
     SHELL_SOCKETS,
     _render,
+    _schedule_overlay_prefetch,
     _schedule_prefetch,
     _vprint,
     wait_for_session_ready,
@@ -340,6 +341,7 @@ def register_websocket_routes(app) -> None:
                         dim_y,
                         idx_tuple,
                         (h, w),
+                        session.shape,
                     )
 
                 render_ms = (time.perf_counter() - render_t0) * 1000.0
@@ -414,6 +416,16 @@ def register_websocket_routes(app) -> None:
                             collection_axis,
                             collection_direction,
                         )
+                    _schedule_overlay_prefetch(
+                        session,
+                        msg.get("overlay_sid"),
+                        msg.get("overlay_alphas"),
+                        dim_x,
+                        dim_y,
+                        list(idx_tuple),
+                        collection_axis,
+                        collection_direction,
+                    )
                 previous_indices = idx_tuple
         except Exception as _ws_exc:
             import traceback

{arrayview-0.31.0 → arrayview-0.31.1}/src/arrayview/_session.py

@@ -101,6 +101,7 @@ def _ensure_render_thread() -> None:
 # Neighbor prefetch thread pool (Phase 3)
 # ---------------------------------------------------------------------------
 _PREFETCH_POOL = None
+_OVERLAY_PREFETCH_POOL = None
 _PREFETCH_LOCK = threading.Lock()
 
 
@@ -116,6 +117,19 @@ def _get_prefetch_pool():
         return _PREFETCH_POOL
 
 
+def _get_overlay_prefetch_pool():
+    """Return the small pool reserved for collection overlay lookahead."""
+    global _OVERLAY_PREFETCH_POOL
+    with _PREFETCH_LOCK:
+        if _OVERLAY_PREFETCH_POOL is None or _OVERLAY_PREFETCH_POOL._shutdown:
+            import concurrent.futures
+
+            _OVERLAY_PREFETCH_POOL = concurrent.futures.ThreadPoolExecutor(
+                max_workers=2, thread_name_prefix="arrayview-overlay-prefetch"
+            )
+        return _OVERLAY_PREFETCH_POOL
+
+
 def _schedule_prefetch(session, dim_x, dim_y, idx_list, slice_dim, direction):
     """Warm raw_cache for the next PREFETCH_NEIGHBORS slices in *direction*.
 
@@ -170,6 +184,85 @@ def _schedule_prefetch(session, dim_x, dim_y, idx_list, slice_dim, direction):
         pass  # pool shutting down
 
 
+def _schedule_overlay_prefetch(
+    session,
+    overlay_sid_str,
+    overlay_alphas_str,
+    dim_x,
+    dim_y,
+    idx_list,
+    collection_axis,
+    direction,
+):
+    """Warm the next collection volume for visible overlays.
+
+    Overlay work uses its own bounded pool so a long mask decompression cannot
+    hold up the main image's single-worker prefetch lane. New navigation
+    supersedes overlay jobs that have not started loading a volume yet.
+    """
+    if not overlay_sid_str:
+        return
+
+    sids = [sid.strip() for sid in overlay_sid_str.split(",") if sid.strip()]
+    alphas = [a.strip() for a in (overlay_alphas_str or "").split(",")]
+    visible_sids = []
+    for i, sid in enumerate(sids):
+        try:
+            alpha = float(alphas[i]) if i < len(alphas) and alphas[i] else 1.0
+        except ValueError:
+            alpha = 1.0
+        if alpha > 0.0:
+            visible_sids.append(sid)
+    if not visible_sids:
+        return
+
+    target = idx_list[collection_axis] + direction
+    if not 0 <= target < session.shape[collection_axis]:
+        return
+
+    request_key = (collection_axis, target, tuple(visible_sids))
+    if request_key == getattr(session, "_overlay_prefetch_request", None):
+        return
+    session._overlay_prefetch_request = request_key
+    generation = getattr(session, "_overlay_prefetch_generation", 0) + 1
+    session._overlay_prefetch_generation = generation
+
+    def _warm(overlay_sid):
+        if generation != getattr(session, "_overlay_prefetch_generation", 0):
+            return
+        overlay = SESSIONS.get(overlay_sid)
+        if overlay is None or collection_axis >= len(overlay.shape):
+            return
+        overlay_stack_axes = tuple(getattr(overlay.data, "_stack_axes", ()))
+        if collection_axis not in overlay_stack_axes or target >= overlay.shape[collection_axis]:
+            return
+        overlay_idx = list(idx_list[: len(overlay.shape)])
+        overlay_idx[collection_axis] = target
+        # Sparse --overlay-dir collections represent a missing patient with a
+        # None filepath. Avoid allocating a fresh full-size zero volume merely
+        # to prefetch an overlay that will be shown empty.
+        file_matrix = getattr(overlay.data, "_file_matrix", None)
+        if file_matrix is not None:
+            modality = 0
+            if len(overlay_stack_axes) > 1:
+                modality = overlay_idx[overlay_stack_axes[1]]
+            if not file_matrix[target][modality]:
+                return
+        try:
+            from arrayview._render import extract_slice
+
+            extract_slice(overlay, dim_x, dim_y, overlay_idx)
+        except Exception:
+            pass
+
+    try:
+        pool = _get_overlay_prefetch_pool()
+        for overlay_sid in visible_sids:
+            pool.submit(_warm, overlay_sid)
+    except RuntimeError:
+        pass  # pool shutting down
+
+
 async def _render(loop: asyncio.AbstractEventLoop, func) -> object:
     """Await *func()* in the render thread without using concurrent.futures."""
     _ensure_render_thread()
@@ -476,9 +569,12 @@ __all__ = [
     "_render",
     # Prefetch
     "_PREFETCH_POOL",
+    "_OVERLAY_PREFETCH_POOL",
     "_PREFETCH_LOCK",
     "_get_prefetch_pool",
+    "_get_overlay_prefetch_pool",
     "_schedule_prefetch",
+    "_schedule_overlay_prefetch",
     # Session
     "Session",
     "SESSIONS",

{arrayview-0.31.0 → arrayview-0.31.1}/tests/test_api.py

@@ -100,6 +100,14 @@ class TestHealth:
 
         assert body["default_dims"] == [0, 1]
 
+    def test_metadata_prefers_trailing_plane_when_it_has_the_two_largest_axes(self, client, tmp_path):
+        path = tmp_path / "startup_dims_volume.npy"
+        np.save(path, np.zeros((48, 224, 224), dtype=np.float32))
+
+        sid = client.post("/load", json={"filepath": str(path)}).json()["sid"]
+
+        assert client.get(f"/metadata/{sid}").json()["default_dims"] == [1, 2]
+
     def test_sessions_lists_registered_sid(self, client, sid_2d):
         r = client.get("/sessions")
         assert r.status_code == 200
@@ -4593,6 +4601,31 @@ class TestCropPersistence:
 
 
 class TestMultipleOverlays:
+    def test_overlay_broadcasts_over_missing_base_dimension(self):
+        from arrayview._render import _extract_overlay_mask
+        from arrayview._session import SESSIONS, Session
+
+        base = Session(np.zeros((48, 3, 224, 224), dtype=np.float32))
+        overlay_data = np.zeros((48, 224, 224), dtype=np.uint8)
+        overlay_data[12, 100, 150] = 1
+        overlay = Session(overlay_data)
+        SESSIONS[overlay.sid] = overlay
+        try:
+            for channel in range(3):
+                result = _extract_overlay_mask(
+                    overlay.sid,
+                    dim_x=2,
+                    dim_y=3,
+                    idx_tuple=(12, channel, 112, 112),
+                    expected_shape=(224, 224),
+                    base_shape=base.shape,
+                )
+                assert result is not None
+                assert result[150, 100] == 1
+            assert overlay.data is overlay_data
+        finally:
+            SESSIONS.pop(overlay.sid, None)
+
     def test_single_overlay_with_color(self, client, sid_2d):
         """A single binary mask overlay with explicit hex color renders without error."""
         from arrayview._app import SESSIONS, Session

{arrayview-0.31.0 → arrayview-0.31.1}/tests/test_nifti_series.py

@@ -329,6 +329,108 @@ def test_stale_collection_prefetch_is_coalesced(monkeypatch):
     assert warmed == [21]
 
 
+def test_overlay_prefetch_only_warms_visible_next_patient(monkeypatch):
+    from arrayview import _session as session_mod
+    import arrayview._render as render_mod
+
+    warmed = []
+    main = SimpleNamespace(
+        shape=(32, 32, 20, 100),
+        _overlay_prefetch_generation=0,
+    )
+    overlays = {
+        "visible": SimpleNamespace(
+            shape=main.shape,
+            data=SimpleNamespace(_stack_axes=(3,)),
+            raw_cache={},
+        ),
+        "hidden": SimpleNamespace(
+            shape=main.shape,
+            data=SimpleNamespace(_stack_axes=(3,)),
+            raw_cache={},
+        ),
+        "missing": SimpleNamespace(
+            shape=main.shape,
+            data=SimpleNamespace(
+                _stack_axes=(3,),
+                _file_matrix=[["mask.nii.gz"] for _ in range(100)],
+            ),
+            raw_cache={},
+        ),
+        "not_collection": SimpleNamespace(
+            shape=main.shape,
+            data=SimpleNamespace(_stack_axes=()),
+            raw_cache={},
+        ),
+    }
+    overlays["missing"].data._file_matrix[13][0] = None
+
+    class ImmediatePool:
+        def submit(self, fn, *args):
+            fn(*args)
+
+    monkeypatch.setattr(session_mod, "SESSIONS", overlays)
+    monkeypatch.setattr(session_mod, "_get_overlay_prefetch_pool", lambda: ImmediatePool())
+    monkeypatch.setattr(
+        render_mod,
+        "extract_slice",
+        lambda overlay, _dx, _dy, idx: warmed.append((overlay, idx[3])),
+    )
+
+    session_mod._schedule_overlay_prefetch(
+        main,
+        "visible,hidden,missing,not_collection,unknown",
+        "0.45,0,0.45,0.45,0.45",
+        0,
+        1,
+        [0, 0, 10, 12],
+        3,
+        1,
+    )
+
+    assert warmed == [(overlays["visible"], 13)]
+
+
+def test_stale_overlay_prefetch_is_coalesced(monkeypatch):
+    from arrayview import _session as session_mod
+    import arrayview._render as render_mod
+
+    queued = []
+    warmed = []
+    main = SimpleNamespace(shape=(32, 32, 20, 100))
+    overlay = SimpleNamespace(
+        shape=main.shape,
+        data=SimpleNamespace(_stack_axes=(3,)),
+        raw_cache={},
+    )
+
+    class QueuedPool:
+        def submit(self, fn, *args):
+            queued.append((fn, args))
+
+    monkeypatch.setattr(session_mod, "SESSIONS", {"overlay": overlay})
+    monkeypatch.setattr(session_mod, "_get_overlay_prefetch_pool", lambda: QueuedPool())
+    monkeypatch.setattr(
+        render_mod,
+        "extract_slice",
+        lambda _overlay, _dx, _dy, idx: warmed.append(idx[3]),
+    )
+
+    session_mod._schedule_overlay_prefetch(
+        main, "overlay", "0.45", 0, 1, [0, 0, 10, 12], 3, 1
+    )
+    session_mod._schedule_overlay_prefetch(
+        main, "overlay", "0.45", 0, 1, [0, 0, 11, 12], 3, 1
+    )
+    session_mod._schedule_overlay_prefetch(
+        main, "overlay", "0.45", 0, 1, [0, 0, 10, 20], 3, 1
+    )
+    for fn, args in queued:
+        fn(*args)
+
+    assert warmed == [21]
+
+
 # ---------------------------------------------------------------------------
 # Non-NIfTI file series  (.npy, .npz, etc.)
 # ---------------------------------------------------------------------------
@@ -643,6 +745,15 @@ class TestDirCollection:
         assert meta["collection_spatial_ndim"] == 3
         assert meta["ragged_spatial_shapes"][1][1] == [3, 6, 6]
 
+    def test_metadata_ignores_case_axis_when_selecting_startup_plane(self):
+        from arrayview._analysis import _build_metadata
+        from arrayview._session import Session
+
+        session = Session(np.zeros((48, 3, 224, 224, 5), dtype=np.float32))
+        session.collection_spatial_ndim = 4
+
+        assert _build_metadata(session)["default_dims"] == [2, 3]
+
     def test_ordered_pairing_mismatched_counts_error(self, tmp_path):
         import arrayview._io as _io
 

{arrayview-0.31.0 → arrayview-0.31.1}/uv.lock

@@ -198,7 +198,7 @@ wheels = [
 
 [[package]]
 name = "arrayview"
-version = "0.31.0"
+version = "0.31.1"
 source = { editable = "." }
 dependencies = [
     { name = "fastapi" },