arrayview 0.31.0__tar.gz → 0.31.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: arrayview
-Version: 0.31.0
+Version: 0.31.2
 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.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "arrayview"
-version = "0.31.0"
+version = "0.31.2"
 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.2}/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.2}/src/arrayview/_instance_registry.py

@@ -115,11 +115,17 @@ def _windows_process_start(pid: int) -> str | None:
     handle = kernel32.OpenProcess(0x1000, False, pid)
     if not handle:
         return None
+    still_active = 259
+    exit_code = ctypes.c_ulong()
     creation = ctypes.c_ulonglong()
     exit_time = ctypes.c_ulonglong()
     kernel = ctypes.c_ulonglong()
     user = ctypes.c_ulonglong()
     try:
+        if not kernel32.GetExitCodeProcess(handle, ctypes.byref(exit_code)):
+            return None
+        if exit_code.value != still_active:
+            return None
         ok = kernel32.GetProcessTimes(handle, ctypes.byref(creation),
                                       ctypes.byref(exit_time), ctypes.byref(kernel),
                                       ctypes.byref(user))

arrayview-0.31.2/src/arrayview/_overlays.py

@@ -0,0 +1,150 @@
+"""Shared overlay compositing helpers."""
+
+from __future__ import annotations
+
+import numpy as np
+
+from arrayview._render import (
+    _build_mosaic_grid,
+    _composite_overlay_mask,
+    _extract_overlay_mask,
+    _overlay_is_label_map,
+)
+
+
+def _parse_hex_color(hex_str: str) -> np.ndarray | None:
+    """Parse a 6-char hex RGB color."""
+    h = hex_str.strip().lstrip("#")
+    if len(h) != 6:
+        return None
+    try:
+        return np.array(
+            [int(h[0:2], 16), int(h[2:4], 16), int(h[4:6], 16)],
+            dtype=np.uint8,
+        )
+    except ValueError:
+        return None
+
+
+def _composite_overlays(
+    rgba: np.ndarray,
+    overlay_sid_str: str | None,
+    overlay_colors_str: str | None,
+    overlay_alpha: float,
+    overlay_alphas_str: str | None,
+    overlay_outline: bool,
+    dim_x: int,
+    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:
+        return rgba
+    sids = [s.strip() for s in overlay_sid_str.split(",") if s.strip()]
+    colors_raw = (
+        [c.strip() for c in overlay_colors_str.split(",")] if overlay_colors_str else []
+    )
+    alphas_raw = (
+        [a.strip() for a in overlay_alphas_str.split(",")] if overlay_alphas_str else []
+    )
+    for i, sid in enumerate(sids):
+        color = _parse_hex_color(colors_raw[i]) if i < len(colors_raw) else None
+        alpha = overlay_alpha
+        if i < len(alphas_raw):
+            try:
+                alpha = float(alphas_raw[i])
+            except ValueError:
+                alpha = overlay_alpha
+        alpha = max(0.0, min(1.0, alpha))
+        ov_raw = _extract_overlay_mask(
+            sid,
+            dim_x,
+            dim_y,
+            idx_tuple,
+            expected_shape=shape_hw,
+            base_shape=base_shape,
+        )
+        rgba = _composite_overlay_mask(
+            rgba,
+            ov_raw,
+            alpha=alpha,
+            is_label=_overlay_is_label_map(sid, ov_raw),
+            override_color=color,
+            outline_only=overlay_outline,
+        )
+    return rgba
+
+
+def _composite_mosaic_overlays(
+    rgba: np.ndarray,
+    overlay_sid_str: str | None,
+    overlay_colors_str: str | None,
+    overlay_alpha: float,
+    overlay_alphas_str: str | None,
+    overlay_outline: bool,
+    dim_x: int,
+    dim_y: int,
+    dim_z: int,
+    idx_tuple: tuple[int, ...],
+    base_shape: tuple[int, ...],
+    mosaic_cols: int | None = None,
+) -> np.ndarray:
+    """Composite each overlay as a mosaic using the base mosaic's frame indices.
+
+    Missing overlay axes are resolved per frame by ``_extract_overlay_mask``.
+    That lets a mask omit, for example, an echo axis without materialising a
+    repeated full-volume copy.
+    """
+    if not overlay_sid_str:
+        return rgba
+    sids = [sid.strip() for sid in overlay_sid_str.split(",") if sid.strip()]
+    colors_raw = (
+        [color.strip() for color in overlay_colors_str.split(",")]
+        if overlay_colors_str
+        else []
+    )
+    alphas_raw = (
+        [alpha.strip() for alpha in overlay_alphas_str.split(",")]
+        if overlay_alphas_str
+        else []
+    )
+    tile_shape = (int(base_shape[dim_y]), int(base_shape[dim_x]))
+    n_frames = int(base_shape[dim_z])
+
+    for i, sid in enumerate(sids):
+        color = _parse_hex_color(colors_raw[i]) if i < len(colors_raw) else None
+        try:
+            alpha = float(alphas_raw[i]) if i < len(alphas_raw) else overlay_alpha
+        except ValueError:
+            alpha = overlay_alpha
+        alpha = max(0.0, min(1.0, alpha))
+
+        frames = []
+        for frame in range(n_frames):
+            frame_idx = list(idx_tuple)
+            frame_idx[dim_z] = frame
+            ov_raw = _extract_overlay_mask(
+                sid,
+                dim_x,
+                dim_y,
+                tuple(frame_idx),
+                expected_shape=tile_shape,
+                base_shape=base_shape,
+            )
+            frames.append(
+                ov_raw if ov_raw is not None else np.zeros(tile_shape, dtype=np.float32)
+            )
+        grid, _, _ = _build_mosaic_grid(frames, n_frames, cols=mosaic_cols)
+        # Gaps are transparent, not NaN label values or heatmap samples.
+        grid = np.nan_to_num(grid, nan=0.0)
+        rgba = _composite_overlay_mask(
+            rgba,
+            grid,
+            alpha=alpha,
+            is_label=_overlay_is_label_map(sid, grid),
+            override_color=color,
+            outline_only=overlay_outline,
+        )
+    return rgba

{arrayview-0.31.0 → arrayview-0.31.2}/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.2}/src/arrayview/_routes_rendering.py

@@ -6,7 +6,7 @@ from fastapi import Depends, Response
 from fastapi.responses import JSONResponse
 
 from arrayview._diff import _compute_diff, _diff_histogram, _render_diff_rgba
-from arrayview._overlays import _composite_overlays
+from arrayview._overlays import _composite_mosaic_overlays, _composite_overlays
 from arrayview._render import (
     LUTS,
     _build_mosaic_grid,
@@ -178,6 +178,11 @@ def register_rendering_routes(app, *, get_session_or_404) -> None:
                     vmin_override=vmin_override,
                     vmax_override=vmax_override,
                 )
+                rgba = _composite_mosaic_overlays(
+                    rgba, overlay_sid, overlay_colors, overlay_alpha, overlay_alphas,
+                    overlay_outline, dim_x, dim_y, dim_z, idx_tuple, session.shape,
+                    mosaic_cols,
+                )
                 if vmin_override is not None and vmax_override is not None:
                     vmin, vmax = float(vmin_override), float(vmax_override)
                 else:
@@ -251,6 +256,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,
@@ -263,6 +269,12 @@ def register_rendering_routes(app, *, get_session_or_404) -> None:
                 )
                 if qmri_role:
                     vmin, vmax = _qmri_adjust_vmin_vmax(vmin, vmax, qmri_role)
+            if dim_z >= 0 and qmri_role:
+                rgba = _composite_mosaic_overlays(
+                    rgba, overlay_sid, overlay_colors, overlay_alpha, overlay_alphas,
+                    overlay_outline, dim_x, dim_y, dim_z, idx_tuple, session.shape,
+                    mosaic_cols,
+                )
         render_ms = (time.perf_counter() - render_t0) * 1000.0
         encode_t0 = time.perf_counter()
         img = _pil_image().fromarray(rgba[:, :, :3], mode="RGB")

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

@@ -8,7 +8,7 @@ from starlette.websockets import WebSocketDisconnect
 import arrayview._session as _session_mod
 from arrayview._analysis import _build_metadata
 from arrayview._lifecycle import release_session
-from arrayview._overlays import _composite_overlays
+from arrayview._overlays import _composite_mosaic_overlays, _composite_overlays
 from arrayview._render import (
     LUTS,
     _prepare_display,
@@ -25,6 +25,7 @@ from arrayview._session import (
     SESSIONS,
     SHELL_SOCKETS,
     _render,
+    _schedule_overlay_prefetch,
     _schedule_prefetch,
     _vprint,
     wait_for_session_ready,
@@ -231,6 +232,12 @@ def register_websocket_routes(app) -> None:
                                 vmax_override=vmax_override,
                             ),
                         )
+                        rgba = _composite_mosaic_overlays(
+                            rgba, msg.get("overlay_sid"), msg.get("overlay_colors"),
+                            float(msg.get("overlay_alpha", 0.45)), msg.get("overlay_alphas"),
+                            bool(msg.get("overlay_outline", False)), dim_x, dim_y, dim_z,
+                            idx_tuple, session.shape, mosaic_cols,
+                        )
                         h, w = rgba.shape[:2]
                         raw = extract_slice(session, dim_x, dim_y, list(idx_tuple))
                         _, vmin, vmax = _prepare_display(
@@ -340,6 +347,15 @@ def register_websocket_routes(app) -> None:
                         dim_y,
                         idx_tuple,
                         (h, w),
+                        session.shape,
+                    )
+
+                if dim_z >= 0 and qmri_role:
+                    rgba = _composite_mosaic_overlays(
+                        rgba, msg.get("overlay_sid"), msg.get("overlay_colors"),
+                        float(msg.get("overlay_alpha", 0.45)), msg.get("overlay_alphas"),
+                        bool(msg.get("overlay_outline", False)), dim_x, dim_y, dim_z,
+                        idx_tuple, session.shape, mosaic_cols,
                     )
 
                 render_ms = (time.perf_counter() - render_t0) * 1000.0
@@ -414,6 +430,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.2}/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.2}/src/arrayview/_vscode_browser.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import os
 import json
+import platform
 import subprocess
 import sys
 import threading
@@ -219,7 +220,7 @@ def _open_browser(
                     port_hint = int(url.split(":")[2].split("/")[0].split("?")[0])
                 except Exception:
                     port_hint = parsed_port
-                hostname = os.uname().nodename or "<this-host>"
+                hostname = platform.node() or "<this-host>"
                 print(
                     f"[ArrayView] Plain SSH session detected.\n"
                     f"\n"

{arrayview-0.31.0 → arrayview-0.31.2}/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,82 @@ class TestCropPersistence:
 
 
 class TestMultipleOverlays:
+    def test_http_mosaic_repeats_overlay_across_missing_dimension(self, client, tmp_path):
+        base_path = tmp_path / "mosaic-base.npy"
+        np.save(base_path, np.zeros((4, 3, 6, 6), dtype=np.float32))
+        base_sid = client.post("/load", json={"filepath": str(base_path)}).json()["sid"]
+        overlay_data = np.zeros((4, 6, 6), dtype=np.uint8)
+        overlay_data[2, 2:4, 2:4] = 1
+        overlay_path = tmp_path / "mosaic-overlay.npy"
+        np.save(overlay_path, overlay_data)
+        overlay_sid = client.post("/load", json={"filepath": str(overlay_path)}).json()["sid"]
+
+        response = client.get(
+            f"/slice/{base_sid}",
+            params={
+                "dim_x": 3,
+                "dim_y": 2,
+                "dim_z": 1,
+                "indices": "2,0,3,3",
+                "overlay_sid": overlay_sid,
+                "overlay_colors": "ff0000",
+                "overlay_alpha": 1.0,
+            },
+        )
+        image = np.asarray(Image.open(io.BytesIO(response.content)))
+        for x0 in (0, 8, 16):
+            tile = image[:, x0 : x0 + 6]
+            assert np.max(tile[:, :, 0].astype(int) - tile[:, :, 1].astype(int)) > 20
+
+    def test_mosaic_overlay_broadcasts_over_missing_mosaic_dimension(self):
+        from arrayview._overlays import _composite_mosaic_overlays
+        from arrayview._render import mosaic_shape
+        from arrayview._session import SESSIONS, Session
+
+        base = Session(np.zeros((4, 3, 6, 6), dtype=np.float32))
+        overlay_data = np.zeros((4, 6, 6), dtype=np.uint8)
+        overlay_data[2, 3, 4] = 1
+        overlay = Session(overlay_data)
+        SESSIONS[overlay.sid] = overlay
+        try:
+            rows, cols = mosaic_shape(3)
+            rgba = np.zeros((rows * 6 + (rows - 1) * 2, cols * 6 + (cols - 1) * 2, 4), dtype=np.uint8)
+            result = _composite_mosaic_overlays(
+                rgba, overlay.sid, "ff0000", 1.0, None, False,
+                dim_x=3, dim_y=2, dim_z=1, idx_tuple=(2, 0, 3, 3),
+                base_shape=base.shape,
+            )
+            for frame in range(3):
+                row, col = divmod(frame, cols)
+                assert result[row * 8 + 3, col * 8 + 4, 0] == 255
+        finally:
+            SESSIONS.pop(overlay.sid, None)
+
+    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