arrayview 0.46.0__py3-none-any.whl → 0.46.2__py3-none-any.whl

arrayview/_analysis.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import itertools
+import os
 
 import numpy as np
 
@@ -18,6 +19,29 @@ def _visible_shape(session) -> list[int]:
     return [int(s) for s in shape]
 
 
+def _code_source(session) -> dict | None:
+    """Say how a copied line of code should name this array.
+
+    Arrays passed from Python are named by the caller's variable. Arrays
+    opened from a file are reopened with the command line and that file.
+    """
+    code_source = getattr(session, "code_source", None)
+    if code_source:
+        return code_source
+    filepath = getattr(session, "filepath", None)
+    if not filepath:
+        return None
+    import shlex
+
+    path = os.path.abspath(filepath)
+    home = os.path.expanduser("~")
+    if path.startswith(home + os.sep) and shlex.quote(path) == path:
+        path = "~" + path[len(home):]
+    else:
+        path = shlex.quote(path)
+    return {"kind": "file", "path": path}
+
+
 def _build_metadata(session) -> dict:
     """Build metadata shared by HTTP routes and WebSocket startup."""
     target_shape = session.spatial_shape if session.rgb_axis is not None else session.shape
@@ -34,6 +58,11 @@ def _build_metadata(session) -> dict:
         "is_rgb": session.rgb_axis is not None,
         "has_source_file": bool(getattr(session, "filepath", None)),
     }
+    if getattr(session, "initial_view", None):
+        meta["initial_view"] = session.initial_view
+    code_source = _code_source(session)
+    if code_source is not None:
+        meta["code_source"] = code_source
     collection_spatial_ndim = getattr(session, "collection_spatial_ndim", None)
     default_shape = target_shape
     if collection_spatial_ndim is not None:
@@ -63,6 +92,9 @@ def _build_metadata(session) -> dict:
         )
     if getattr(session, "array_keys", None):
         meta["array_keys"] = session.array_keys
+        meta["array_key"] = getattr(session, "array_key", None)
+        meta["array_prompt"] = bool(getattr(session, "array_prompt", False))
+        meta["array_filename"] = os.path.basename(getattr(session, "array_filepath", "") or "")
     if collection_spatial_ndim is not None:
         meta["collection_spatial_ndim"] = int(collection_spatial_ndim)
     if getattr(session.data, "_av_ragged", False):
@@ -70,6 +102,9 @@ def _build_metadata(session) -> dict:
             [list(shape) for shape in row]
             for row in session.data.ragged_spatial_shapes
         ]
+    case_names = getattr(session.data, "case_names", None)
+    if case_names:
+        meta["case_names"] = [str(name) for name in case_names]
     case_voxel_spacings = getattr(session.data, "case_voxel_spacings", None)
     if case_voxel_spacings:
         meta["case_voxel_spacings"] = [

arrayview/_extra_ports.py

@@ -91,7 +91,7 @@ def _start_extra_port() -> tuple[int, dict] | None:
             timeout_keep_alive=30,
             ws_ping_interval=None,
             ws="websockets",
-            ws_per_message_deflate=True,
+            ws_per_message_deflate=False,
         )
         server = uvicorn.Server(config)
         task = asyncio.create_task(server.serve(sockets=[sock]))

arrayview/_io.py

@@ -67,6 +67,38 @@ def _is_viewable_mat_array(value):
     )
 
 
+def _is_viewable_h5_dataset(ds):
+    """True for HDF5 datasets in a v7.3 .mat file ArrayView can display.
+
+    MATLAB v7.3 stores complex arrays as a compound dtype with 'real' and
+    'imag' fields, which has dtype kind 'V' rather than 'c'.
+    """
+    import h5py
+
+    if not isinstance(ds, h5py.Dataset) or len(ds.shape) < 1:
+        return False
+    names = ds.dtype.names
+    if names:
+        return "real" in names and "imag" in names
+    return ds.dtype.kind in ("b", "i", "u", "f", "c")
+
+
+def _h5_display_dtype(ds):
+    """Dtype string to show for a v7.3 .mat dataset (compound complex → complex)."""
+    if ds.dtype.names:
+        return "complex128" if ds.dtype["real"].itemsize == 8 else "complex64"
+    return str(ds.dtype)
+
+
+def array_choice_placeholder():
+    """Stand-in data for a multi-array file whose array is not chosen yet.
+
+    The session exists so the viewer can open and ask which array to load;
+    nothing from the file is read until the user picks one.
+    """
+    return np.zeros((2, 2), dtype=np.float32)
+
+
 def list_npz_keys(filepath):
     """Return [{key, shape, dtype}] for each ndarray in an .npz file.
 
@@ -106,8 +138,8 @@ def list_mat_keys(filepath):
         keys = []
         for k in f.keys():
             ds = f[k]
-            if isinstance(ds, h5py.Dataset) and len(ds.shape) >= 1 and ds.dtype.kind in ("b", "i", "u", "f", "c"):
-                keys.append({"key": k, "shape": list(ds.shape), "dtype": str(ds.dtype)})
+            if _is_viewable_h5_dataset(ds):
+                keys.append({"key": k, "shape": list(ds.shape), "dtype": _h5_display_dtype(ds)})
         f.close()
         return keys
 
@@ -1249,6 +1281,9 @@ def load_dir_collection(
         scan_progress=scan_progress,
         scan_label="images",
     )
+    # Lets the viewer label each case by its id (e.g. the patient folder)
+    # instead of its position in the stack.
+    data.case_names = [str(case) for case in case_ids]
     spatial_shape = data._vol_shape
 
     overlay_items = []
@@ -1726,11 +1761,11 @@ def load_data(filepath, key=None, *, progress=None):
             import h5py
 
             f = h5py.File(filepath, "r")
-            arrays = {k: f[k] for k in f.keys() if isinstance(f[k], h5py.Dataset)}
+            arrays = {k: f[k] for k in f.keys() if _is_viewable_h5_dataset(f[k])}
             if key is not None:
-                return np.array(arrays[key])
+                return _fix_mat_complex(np.array(arrays[key]))
             if len(arrays) == 1:
-                return np.array(next(iter(arrays.values())))
+                return _fix_mat_complex(np.array(next(iter(arrays.values()))))
             raise ValueError(
                 f".mat (v7.3) file contains multiple datasets: {list(arrays.keys())}. "
                 "Select one in the viewer or pass a key."

arrayview/_launcher.py

@@ -1312,6 +1312,8 @@ def _load_session_from_filepath(
     related_sids: list[str] | None = None,
     source_staging_dir: str | None = None,
     watch: bool = False,
+    initial_view: dict | None = None,
+    code_source: dict | None = None,
 ) -> dict:
     requested_sid = uuid.uuid4().hex
     payload = {
@@ -1321,11 +1323,18 @@ def _load_session_from_filepath(
         "requested_sid": requested_sid,
         "release_on_disconnect": release_on_disconnect,
         "related_sids": related_sids or [],
+        # Multi-array .npz/.mat: open the first array instead of returning
+        # the key list; the viewer then offers the choice.
+        "array_default": True,
     }
     if source_staging_dir:
         payload["source_staging_dir"] = source_staging_dir
     if watch:
         payload["watch"] = True
+    if initial_view:
+        payload["initial_view"] = initial_view
+    if code_source:
+        payload["code_source"] = code_source
     if rgb:
         payload["rgb"] = True
     if dir_patterns:
@@ -1662,6 +1671,7 @@ def _register_cli_session_with_existing_server_impl(
     native_request_id: str | None = None,
     source_staging_dirs: dict[str, str] | None = None,
     watch: bool = False,
+    initial_view: dict | None = None,
     _loaded_sids: list[str],
 ) -> dict[str, object]:
     overlay_sids_list: list[str] = []
@@ -1716,6 +1726,7 @@ def _register_cli_session_with_existing_server_impl(
         related_sids=[*compare_sids, *overlay_sids_list],
         source_staging_dir=(source_staging_dirs or {}).get(base_file),
         watch=watch,
+        initial_view=initial_view,
     )
     if "error" in result:
         error = str(result["error"])
@@ -1794,6 +1805,7 @@ def _handle_cli_existing_server(
     use_native_shell: bool,
     dims_override: tuple[int, int] | None,
     watch: bool,
+    initial_view: dict | None = None,
     window_mode: str | None,
     floating: bool,
     is_remote: bool = False,
@@ -1844,6 +1856,7 @@ def _handle_cli_existing_server(
             native_request_id=native_request_id,
             source_staging_dirs=source_staging_dirs,
             watch=watch,
+            initial_view=initial_view,
         )
         # Inside this try on purpose: the generated bundle is removed in the
         # finally below, and these sessions read from it.
@@ -1899,6 +1912,7 @@ def _handle_cli_existing_server(
                     dims_override=dims_override,
                     use_native_shell=use_native_shell,
                     watch=watch,
+                    initial_view=initial_view,
                     window_mode=window_mode,
                     floating=floating,
                     is_remote=is_remote,
@@ -2033,6 +2047,7 @@ def _handle_cli_spawned_daemon(
     dims_override: tuple[int, int] | None,
     use_native_shell: bool,
     watch: bool,
+    initial_view: dict | None = None,
     window_mode: str | None,
     floating: bool,
     is_remote: bool,
@@ -2095,6 +2110,7 @@ def _handle_cli_spawned_daemon(
                 use_native_shell=use_native_shell,
                 dims_override=dims_override,
                 watch=watch,
+                initial_view=initial_view,
                 window_mode=window_mode,
                 floating=floating,
                 is_remote=is_remote,
@@ -2167,6 +2183,7 @@ def _handle_cli_spawned_daemon(
             f" cleanup_dir={repr(cleanup_dir)},"
             f" source_staging_dirs={repr(source_staging_dirs or {})},"
             f" watch={watch},"
+            f" initial_view={repr(initial_view)},"
             f")"
         )
 
@@ -2776,8 +2793,10 @@ async def _serve_background(
         log_level="error",
         timeout_keep_alive=30,
         ws_ping_interval=None,
-        ws="websockets",  # S7: explicit backend — enables permessage-deflate compression
-        ws_per_message_deflate=True,  # S7: negotiate deflate with browser (transparent)
+        ws="websockets",
+        # Deflate costs more than rendering a large slice and stalls playback.
+        # A 256×256 frame measured 18 fps with it and 54 fps without it.
+        ws_per_message_deflate=False,
     )
     server = _uvicorn().Server(config)
     if stop_when_closed:
@@ -3473,6 +3492,30 @@ class ViewHandle(str):
         return False
 
 
+def _caller_variable_name(obj) -> str | None:
+    """Name of the caller's variable that holds ``obj``, if there is one.
+
+    Used only to write a copyable ``view(<name>, ...)`` line, so a miss is
+    harmless: expressions such as ``view(a[0])`` simply have no name.
+    """
+    import inspect
+
+    frame = inspect.currentframe()
+    try:
+        caller = frame.f_back.f_back if frame and frame.f_back else None
+        if caller is None:
+            return None
+        for scope in (caller.f_locals, caller.f_globals):
+            for key, value in list(scope.items()):
+                if value is obj and key.isidentifier() and not key.startswith("_"):
+                    return key
+    except Exception:
+        return None
+    finally:
+        del frame
+    return None
+
+
 def view(
     *arrays,
     name=None,
@@ -3484,6 +3527,14 @@ def view(
     rgb: bool | list = False,
     overlay=None,
     floating: bool = False,
+    mode: str | None = None,
+    dims=None,
+    index=None,
+    cmap: str | None = None,
+    vmin: float | None = None,
+    vmax: float | None = None,
+    log: bool = False,
+    complex: str | None = None,
 ):
     """
     Launch the viewer. Does not block the main Python process.
@@ -3523,6 +3574,16 @@ def view(
     ``overlay`` — a single array or list of arrays to composite as overlays.
     Each overlay is assigned an auto-palette color from _OVERLAY_PALETTE.
 
+    ``mode``, ``dims``, ``index``, ``cmap``, ``vmin``/``vmax`` and ``log`` set
+    the view the viewer opens with: the viewing mode (``"ortho"``,
+    ``"mosaic"``, ``"qmri"``, ``"qmri-ortho"``, ``"qmri-mosaic"``), the two
+    dimensions shown as x and y (three for ortho: its volume dims; three for
+    the mosaics: x, y and the gridded dim), the position along every
+    dimension, the colormap, the display range and log scale. ``complex``
+    picks what complex data shows: ``"mag"``, ``"phase"``, ``"real"`` or
+    ``"imag"`` (``"mag"`` shows the absolute value of real data). Pressing
+    ``E`` in the viewer copies the current view as such a call.
+
     Returns a ``ViewHandle`` for a single array, or a tuple of ``ViewHandle``
     objects for multiple arrays (one per array). In inline/Jupyter mode with
     multiple arrays, the IFrame is displayed automatically and a uniform tuple
@@ -3534,6 +3595,12 @@ def view(
     import numpy as np
     from arrayview._io import _tensor_to_numpy
 
+    _initial_view = _session_mod.initial_view_spec(
+        mode=mode, dims=dims, index=index, cmap=cmap, vmin=vmin, vmax=vmax, log=log,
+        complex=complex,
+    )
+    _code_name = _caller_variable_name(arrays[0]) if arrays else None
+
     height = _normalize_inline_height(height)
     _inline_mode_heights = _normalize_inline_mode_heights(mode_heights)
 
@@ -3602,6 +3669,13 @@ def view(
     data = arrays[0]
     name = names[0]
     rgb_primary = rgbs[0]
+    if _initial_view and "index" in _initial_view:
+        _ndim = len(getattr(data, "shape", ()))
+        if len(_initial_view["index"]) != _ndim:
+            raise ValueError(
+                f"index has {len(_initial_view['index'])} entries but the array "
+                f"has {_ndim} dimensions"
+            )
 
     # --- Normalise string window modes ---
     _raw_window = window
@@ -3631,6 +3705,18 @@ def view(
     else:
         _invocation = Invocation.PYTHON
 
+    # Julia and MATLAB callers are not Python frames, so only their explicit
+    # name can stand in for the variable.
+    if _code_name is None or _invocation in (Invocation.JULIA, Invocation.MATLAB):
+        _code_name = name if str(name).isidentifier() else "x"
+    _code_source = {
+        "kind": {
+            Invocation.JULIA: "julia",
+            Invocation.MATLAB: "matlab",
+        }.get(_invocation, "python"),
+        "name": _code_name,
+    }
+
     if isinstance(_raw_window, str):
         _requested_window = _raw_window
     elif _raw_window is True:
@@ -3701,6 +3787,8 @@ def view(
             mode_heights=_inline_mode_heights,
             floating=floating,
             launch_context=_launch_context,
+            initial_view=_initial_view,
+            code_source=_code_source,
         )
 
     # VS Code tunnel/remote: use the server + WebSocket path. The opener owns
@@ -3724,6 +3812,7 @@ def view(
                     _tmp_path = _tmp.name
                 try:
                     np.save(_tmp_path, _array)
+                    _is_primary = not _loaded_sids
                     _result = _load_session_from_filepath(
                         port,
                         _tmp_path,
@@ -3731,6 +3820,8 @@ def view(
                         rgb=_rgb,
                         expected_server_id=_expected_server_id,
                         release_on_disconnect=inline,
+                        initial_view=_initial_view if _is_primary else None,
+                        code_source=_code_source if _is_primary else None,
                     )
                 finally:
                     try:
@@ -3827,6 +3918,8 @@ def view(
     session = _session_mod.Session(data, name=name)
     if rgb_primary:
         _setup_rgb(session)
+    session.initial_view = _initial_view
+    session.code_source = _code_source
     _session_mod.SESSIONS[session.sid] = session
 
     # Register compare sessions (arrays[1:])
@@ -4257,6 +4350,8 @@ def _view_julia(
     mode_heights: dict[str, int] | None = None,
     floating: bool = False,
     launch_context=None,
+    initial_view: dict | None = None,
+    code_source: dict | None = None,
 ):
     """Julia-specific view() path: run the server in a subprocess so it is
     completely independent of Julia's GIL.
@@ -4278,6 +4373,8 @@ def _view_julia(
         force_vscode=force_vscode,
         floating=floating,
         launch_context=launch_context,
+        initial_view=initial_view,
+        code_source=code_source,
     )
 
 
@@ -4293,6 +4390,8 @@ def _view_subprocess(
     force_vscode: bool = False,
     floating: bool = False,
     launch_context=None,
+    initial_view: dict | None = None,
+    code_source: dict | None = None,
 ) -> str:
     """Run the viewer in a separate subprocess server.
 
@@ -4348,6 +4447,8 @@ def _view_subprocess(
                 expected_server_id=active_server_id,
                 native_request_id=native_request_id,
                 release_on_disconnect=True,
+                initial_view=initial_view,
+                code_source=code_source,
             )
             if "error" in result:
                 raise RuntimeError(result["error"])
@@ -4412,7 +4513,9 @@ def _view_subprocess(
                     f"_serve_daemon({repr(tmp_path)}, {port}, {repr(sid)}, "
                     f"name={repr(name)}, cleanup=True, "
                     f"persist={persist_daemon}, "
-                    f"connect_timeout={repr(daemon_connect_timeout)}, rgb={rgb})"
+                    f"connect_timeout={repr(daemon_connect_timeout)}, rgb={rgb}, "
+                    f"initial_view={repr(initial_view)}, "
+                    f"code_source={repr(code_source)})"
                 )
                 daemon_proc = subprocess.Popen(
                     [sys.executable, "-c", script],
@@ -4547,6 +4650,8 @@ def _serve_empty(port: int) -> None:
             _server_mod().app,
             log_level="error",
             timeout_keep_alive=30,
+            ws="websockets",
+            ws_per_message_deflate=False,
         )
         server = _uvicorn().Server(config)
         asyncio.run(server.serve(sockets=socks))
@@ -4586,6 +4691,8 @@ def _serve_daemon(
     cleanup_dir: str | None = None,
     source_staging_dirs: dict[str, str] | None = None,
     watch: bool = False,
+    initial_view: dict | None = None,
+    code_source: dict | None = None,
 ) -> None:
     """Background server process. Loads data, serves it.
     persist=True: never exits (used on remote tunnel so port stays alive).
@@ -4639,6 +4746,8 @@ def _serve_daemon(
             bootstrap,
             log_level="error",
             timeout_keep_alive=30,
+            ws="websockets",
+            ws_per_message_deflate=False,
         )
         server = _uvicorn().Server(config)
         uvicorn_server.append(server)
@@ -4691,6 +4800,7 @@ def _serve_daemon(
 
     def _load():
         from arrayview._io import (
+            array_choice_placeholder,
             load_data,
             load_data_with_meta,
             load_dir_collection,
@@ -4705,8 +4815,8 @@ def _serve_daemon(
                 if dir_patterns is None and not cleanup
                 else None
             )
-            # Multi-array .npz/.mat: load the first array so the session is
-            # created, then store keys so the viewer can show a picker.
+            # Multi-array .npz/.mat: create the session with a placeholder and
+            # store the keys; the viewer asks which array to load.
             _array_keys = None
             if dir_patterns is not None:
                 data, spatial_meta, dir_overlay_items, _summary = load_dir_collection(
@@ -4723,8 +4833,12 @@ def _serve_daemon(
                     _array_keys = list_array_keys(filepath)
                 except Exception:
                     pass
-                _load_key = _array_keys[0]["key"] if _array_keys else None
-                data, spatial_meta = load_data_with_meta(filepath, key=_load_key)
+                if _array_keys and len(_array_keys) > 1:
+                    _load_key = None
+                    data, spatial_meta = array_choice_placeholder(), None
+                else:
+                    _load_key = _array_keys[0]["key"] if _array_keys else None
+                    data, spatial_meta = load_data_with_meta(filepath, key=_load_key)
                 dir_overlay_items = None
                 collection_spatial_ndim = None
             else:
@@ -4748,6 +4862,10 @@ def _serve_daemon(
             if filepath in source_staging_dirs:
                 session._source_staging_dirs = [source_staging_dirs[filepath]]
             session.sid = sid
+            _session_mod.apply_launch_view(
+                session,
+                {"initial_view": initial_view, "code_source": code_source},
+            )
             if signature_before_load is not None:
                 signature_after_load = file_signature(filepath)
                 if signature_before_load == signature_after_load:
@@ -4758,6 +4876,9 @@ def _serve_daemon(
             if _array_keys and len(_array_keys) > 1:
                 session.array_keys = _array_keys
                 session.array_filepath = filepath
+                session.array_key = _load_key
+                # Nothing is loaded yet; the viewer asks once which array to show.
+                session.array_prompt = True
             if spatial_meta is not None:
                 session.original_volume = data
             if rgb:
@@ -5656,6 +5777,28 @@ def arrayview():
             "Also accepts 0-based integer pair like '2,3'."
         ),
     )
+    parser.add_argument(
+        "--index",
+        metavar="I,J,...",
+        default=None,
+        help="Open at this position: one 0-based index per dimension, e.g. '128,128,40'.",
+    )
+    parser.add_argument(
+        "--mode",
+        default=None,
+        choices=["ortho", "mosaic", "qmri", "qmri-ortho", "qmri-mosaic"],
+        help="Open in this viewing mode. With ortho or a mosaic, --dims takes three dims.",
+    )
+    parser.add_argument("--cmap", default=None, help="Open with this colormap, e.g. 'gray'.")
+    parser.add_argument("--vmin", type=float, default=None, help="Lower end of the display range (with --vmax).")
+    parser.add_argument("--vmax", type=float, default=None, help="Upper end of the display range (with --vmin).")
+    parser.add_argument("--log", action="store_true", help="Open with log scale on.")
+    parser.add_argument(
+        "--complex",
+        default=None,
+        choices=["mag", "phase", "real", "imag"],
+        help="Which part of complex data to show (mag shows |x| of real data).",
+    )
     parser.add_argument(
         "--name",
         default=None,
@@ -5816,13 +5959,31 @@ def arrayview():
         return
 
     dims_override: tuple[int, int] | None = None
-    if args.dims:
+    view_dims: list[str] | None = None
+    if args.dims and args.mode in ("ortho", "mosaic", "qmri-mosaic"):
+        # Three dims: not an x/y pair, so they only travel with the view.
+        view_dims = args.dims.split(",")
+    elif args.dims:
         dims_override = _parse_dims_spec(args.dims)
         if dims_override is None:
             parser.error(
                 f"--dims {args.dims!r} is invalid. "
                 "Use e.g. 'x,y,:,:' or ':,:,x,y' or '0,1'."
             )
+    initial_view: dict | None = None
+    try:
+        initial_view = _session_mod.initial_view_spec(
+            mode=args.mode,
+            dims=view_dims or dims_override,
+            index=args.index.split(",") if args.index else None,
+            cmap=args.cmap,
+            vmin=args.vmin,
+            vmax=args.vmax,
+            log=args.log,
+            complex=args.complex,
+        )
+    except ValueError as exc:
+        parser.error(str(exc))
     if getattr(args, "stack_flag_removed", False):
         parser.error(
             "--stack has been renamed to --match, because it never controlled "
@@ -6447,6 +6608,7 @@ def arrayview():
                 vfield_components_dim=vfield_components_dim,
                 use_native_shell=use_native_shell,
                 dims_override=dims_override,
+                initial_view=initial_view,
                 watch=getattr(args, "watch", False),
                 window_mode=window_mode,
                 floating=args.floating,
@@ -6479,6 +6641,7 @@ def arrayview():
             overlay_files=[] if args.stack_mode else file_overlay_paths,
             overlay_names=[] if args.stack_mode else file_overlay_names,
             dims_override=dims_override,
+            initial_view=initial_view,
             use_native_shell=use_native_shell,
             watch=getattr(args, "watch", False),
             window_mode=window_mode,

arrayview/_overlays.py

@@ -26,6 +26,22 @@ def _parse_hex_color(hex_str: str) -> np.ndarray | None:
         return None
 
 
+def _parse_overlay_color_token(token: str) -> tuple[np.ndarray | None, frozenset[int]]:
+    """Parse one ``overlay_colors`` entry: ``RRGGBB`` or ``RRGGBB~2.5``.
+
+    The optional ``~`` suffix lists label values of a label-map overlay that
+    the viewer has switched off.
+    """
+    color_part, _, hidden_part = token.partition("~")
+    hidden = set()
+    for value in hidden_part.split("."):
+        try:
+            hidden.add(int(value))
+        except ValueError:
+            pass
+    return _parse_hex_color(color_part), frozenset(hidden)
+
+
 def _composite_overlays(
     rgba: np.ndarray,
     overlay_sid_str: str | None,
@@ -50,7 +66,11 @@ def _composite_overlays(
         [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
+        color, hidden = (
+            _parse_overlay_color_token(colors_raw[i])
+            if i < len(colors_raw)
+            else (None, frozenset())
+        )
         alpha = overlay_alpha
         if i < len(alphas_raw):
             try:
@@ -73,6 +93,7 @@ def _composite_overlays(
             is_label=_overlay_is_label_map(sid, ov_raw),
             override_color=color,
             outline_only=overlay_outline,
+            hidden_labels=hidden,
         )
     return rgba
 
@@ -114,7 +135,11 @@ def _composite_mosaic_overlays(
     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
+        color, hidden = (
+            _parse_overlay_color_token(colors_raw[i])
+            if i < len(colors_raw)
+            else (None, frozenset())
+        )
         try:
             alpha = float(alphas_raw[i]) if i < len(alphas_raw) else overlay_alpha
         except ValueError:
@@ -146,5 +171,6 @@ def _composite_mosaic_overlays(
             is_label=_overlay_is_label_map(sid, grid),
             override_color=color,
             outline_only=overlay_outline,
+            hidden_labels=hidden,
         )
     return rgba