arrayview 0.31.1__tar.gz → 0.31.2__tar.gz

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

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "arrayview"
-version = "0.31.1"
+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.1 → 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.1 → 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:
@@ -264,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.1 → 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,
@@ -232,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(
@@ -344,6 +350,14 @@ def register_websocket_routes(app) -> None:
                         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
                 post_t0 = time.perf_counter()
                 header = np.array([seq, w, h], dtype=np.uint32).tobytes()

{arrayview-0.31.1 → 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.1 → arrayview-0.31.2}/tests/test_api.py

@@ -4601,6 +4601,57 @@ 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

{arrayview-0.31.1 → arrayview-0.31.2}/tests/test_lifecycle_contract.py

@@ -163,6 +163,7 @@ def test_vscode_tunnel_without_window_id_uses_focused_window_fallback(
     signal_dir = home / ".arrayview"
     signal_dir.mkdir(parents=True)
     monkeypatch.setenv("HOME", str(home))
+    monkeypatch.setenv("USERPROFILE", str(home))
     monkeypatch.setattr(signal, "_is_vscode_remote", lambda: True)
     monkeypatch.setattr(signal, "_find_arrayview_window_id", lambda: None)
     monkeypatch.setattr(signal, "_find_current_vscode_window_id", lambda: "100")
@@ -201,6 +202,7 @@ def test_vscode_tunnel_exact_window_id_is_not_redirected_to_newer_sibling(
     signal_dir = home / ".arrayview"
     signal_dir.mkdir(parents=True)
     monkeypatch.setenv("HOME", str(home))
+    monkeypatch.setenv("USERPROFILE", str(home))
     monkeypatch.setattr(signal, "_is_vscode_remote", lambda: True)
     monkeypatch.setattr(signal, "_find_arrayview_window_id", lambda: "100")
 
@@ -231,6 +233,7 @@ def test_vscode_local_exact_window_id_is_not_redirected_to_newer_sibling(
     signal_dir = home / ".arrayview"
     signal_dir.mkdir(parents=True)
     monkeypatch.setenv("HOME", str(home))
+    monkeypatch.setenv("USERPROFILE", str(home))
     monkeypatch.setattr(signal, "_is_vscode_remote", lambda: False)
     monkeypatch.setattr(signal, "_find_arrayview_window_id", lambda: "100")
 
@@ -261,6 +264,7 @@ def test_vscode_local_stale_window_id_with_multiple_windows_fails_closed(
     signal_dir = home / ".arrayview"
     signal_dir.mkdir(parents=True)
     monkeypatch.setenv("HOME", str(home))
+    monkeypatch.setenv("USERPROFILE", str(home))
     monkeypatch.setattr(signal, "_is_vscode_remote", lambda: False)
     monkeypatch.setattr(signal, "_find_arrayview_window_id", lambda: "stale")
     monkeypatch.setattr(signal, "_find_current_vscode_window_id", lambda: None)
@@ -290,6 +294,7 @@ def test_vscode_local_missing_window_match_uses_focused_window_fallback(
     signal_dir = home / ".arrayview"
     signal_dir.mkdir(parents=True)
     monkeypatch.setenv("HOME", str(home))
+    monkeypatch.setenv("USERPROFILE", str(home))
     monkeypatch.setattr(signal, "_is_vscode_remote", lambda: False)
     monkeypatch.setattr(signal, "_find_arrayview_window_id", lambda: None)
     monkeypatch.setattr(signal, "_find_current_vscode_window_id", lambda: None)
@@ -331,6 +336,7 @@ def test_vscode_local_missing_window_match_with_local_windows_fails_closed(
     signal_dir = home / ".arrayview"
     signal_dir.mkdir(parents=True)
     monkeypatch.setenv("HOME", str(home))
+    monkeypatch.setenv("USERPROFILE", str(home))
     monkeypatch.setattr(signal, "_is_vscode_remote", lambda: False)
     monkeypatch.setattr(signal, "_find_arrayview_window_id", lambda: None)
     monkeypatch.setattr(signal, "_find_current_vscode_window_id", lambda: None)

{arrayview-0.31.1 → arrayview-0.31.2}/tests/test_vscode_ack_protocol.py

@@ -19,6 +19,7 @@ def _request(tmp_path, **overrides):
 
 def test_open_request_includes_versioned_ack_metadata(monkeypatch, tmp_path):
     monkeypatch.setenv("HOME", str(tmp_path))
+    monkeypatch.setenv("USERPROFILE", str(tmp_path))
     monkeypatch.setattr(signal, "_find_arrayview_window_id", lambda: "window-1")
     captured = []
     monkeypatch.setattr(
@@ -51,6 +52,7 @@ def test_open_request_includes_versioned_ack_metadata(monkeypatch, tmp_path):
 
 def test_open_request_reports_failed_legacy_write(monkeypatch, tmp_path):
     monkeypatch.setenv("HOME", str(tmp_path))
+    monkeypatch.setenv("USERPROFILE", str(tmp_path))
     monkeypatch.setattr(signal, "_find_arrayview_window_id", lambda: None)
     monkeypatch.setattr(signal, "_write_vscode_signal", lambda *args, **kwargs: False)
 
@@ -62,6 +64,7 @@ def test_open_request_reports_failed_legacy_write(monkeypatch, tmp_path):
 
 def test_open_request_correlates_ack_to_recovered_live_window(monkeypatch, tmp_path):
     monkeypatch.setenv("HOME", str(tmp_path))
+    monkeypatch.setenv("USERPROFILE", str(tmp_path))
     monkeypatch.setattr(signal, "_find_arrayview_window_id", lambda: "stale-window")
     monkeypatch.setattr(signal, "_is_vscode_remote", lambda: False)
     signal_dir = tmp_path / ".arrayview"
@@ -86,6 +89,7 @@ def test_open_request_correlates_ack_to_recovered_live_window(monkeypatch, tmp_p
 
 def test_open_request_leaves_broadcast_window_to_claiming_extension(monkeypatch, tmp_path):
     monkeypatch.setenv("HOME", str(tmp_path))
+    monkeypatch.setenv("USERPROFILE", str(tmp_path))
     monkeypatch.setattr(signal, "_find_arrayview_window_id", lambda: "stale-window")
     monkeypatch.setattr(signal, "_is_vscode_remote", lambda: True)
     signal_dir = tmp_path / ".arrayview"
@@ -112,6 +116,7 @@ def test_open_request_leaves_broadcast_window_to_claiming_extension(monkeypatch,
 
 def test_protocol_requests_get_distinct_queue_files(monkeypatch, tmp_path):
     monkeypatch.setenv("HOME", str(tmp_path))
+    monkeypatch.setenv("USERPROFILE", str(tmp_path))
     monkeypatch.setattr(signal, "_is_vscode_remote", lambda: True)
     monkeypatch.setattr(signal, "_find_arrayview_window_id", lambda: "window-1")
     signal_dir = tmp_path / ".arrayview"
@@ -144,6 +149,7 @@ def test_protocol_requests_get_distinct_queue_files(monkeypatch, tmp_path):
 
 def test_protocol_uses_fixed_filename_for_running_legacy_extension(monkeypatch, tmp_path):
     monkeypatch.setenv("HOME", str(tmp_path))
+    monkeypatch.setenv("USERPROFILE", str(tmp_path))
     monkeypatch.setattr(signal, "_is_vscode_remote", lambda: True)
     monkeypatch.setattr(signal, "_find_arrayview_window_id", lambda: "window-1")
     signal_dir = tmp_path / ".arrayview"
@@ -240,6 +246,7 @@ def test_wait_rejects_malformed_or_unknown_ack(tmp_path):
 
 def test_cleanup_removes_only_stale_ack_files(monkeypatch, tmp_path):
     monkeypatch.setenv("HOME", str(tmp_path))
+    monkeypatch.setenv("USERPROFILE", str(tmp_path))
     signal_dir = tmp_path / ".arrayview"
     signal_dir.mkdir()
     stale = signal_dir / "open-ack-v0100-stale.json"

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

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

{arrayview-0.31.1 → arrayview-0.31.2}/vscode-extension/test_lifecycle_helpers.js

@@ -1,4 +1,5 @@
 const assert = require('assert');
+const path = require('path');
 const {
     collectReleaseSidsFromUrl,
     pingUrlFromViewerUrl,
@@ -54,18 +55,19 @@ assert.strictEqual(shouldDeferBroadcast(false, true, { broadcast: true }), false
 assert.strictEqual(shouldDeferBroadcast(true, false, { broadcast: true }), false);
 assert.strictEqual(shouldDeferBroadcast(false, false, { broadcast: false }), false);
 
-const home = '/home/tester';
+const home = path.join(path.parse(process.cwd()).root, 'home', 'tester');
+const ackPath = path.join(home, '.arrayview', 'open-ack-v0100-req-1.json');
 assert.strictEqual(
-    validatedAckPath('/home/tester/.arrayview/open-ack-v0100-req-1.json', 'req-1', home),
-    '/home/tester/.arrayview/open-ack-v0100-req-1.json'
+    validatedAckPath(ackPath, 'req-1', home),
+    path.resolve(ackPath)
 );
-assert.strictEqual(validatedAckPath('/tmp/open-ack-v0100-req-1.json', 'req-1', home), null);
+assert.strictEqual(validatedAckPath(path.join(path.parse(process.cwd()).root, 'tmp', 'open-ack-v0100-req-1.json'), 'req-1', home), null);
 assert.strictEqual(
-    validatedAckPath('/home/tester/.arrayview/open-ack-v0100-other.json', 'req-1', home),
+    validatedAckPath(path.join(home, '.arrayview', 'open-ack-v0100-other.json'), 'req-1', home),
     null
 );
 assert.strictEqual(
-    validatedAckPath('/home/tester/.arrayview/sub/open-ack-v0100-req-1.json', 'req-1', home),
+    validatedAckPath(path.join(home, '.arrayview', 'sub', 'open-ack-v0100-req-1.json'), 'req-1', home),
     null
 );
 

arrayview-0.31.1/src/arrayview/_overlays.py

@@ -1,76 +0,0 @@
-"""Shared overlay compositing helpers."""
-
-from __future__ import annotations
-
-import numpy as np
-
-from arrayview._render import (
-    _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