arrayview 0.30.0__tar.gz → 0.31.1__tar.gz

{arrayview-0.30.0 → arrayview-0.31.1}/.mex/context/project-state.md

@@ -32,8 +32,25 @@ last_updated: 2026-06-30
 - qMRI map toggle (`_islandToggleQmriMap`) fade animation now covers dimbar and array-name in addition to panes and colorbars
 - Segmentation menu shares the ROI layout (yellow accent, magnifier action icon, common `#export-overlay` modal). Pre-activation shows a pulsing "nnInteractive · connecting" row that morphs into the normal shape toolbar once `/seg/activate` resolves
 - Overlays are a plugin tile (`OV`): per-overlay row with colour swatch, editable label, eye toggle, × delete; shared opacity slider; `+ add overlay` opens a filesystem picker rooted at the launched file's directory
+- The floating overlay HUD is reconciled as soon as startup loading ends, so it
+  is visible on first load and `/ o` toggles it correctly from the first press.
+  Its drag grip allows viewport-clamped repositioning that survives mode and
+  layout reconciliation for the current viewer session. Hovering a visible row
+  focuses that mask and dims the other visible overlays across normal, compare,
+  multiview, and qMRI render paths. The HUD and overlay drawer can switch masks
+  between filled regions and outline-only contours.
 - Vector field is a plugin tile (`VF`): row with visibility toggle + density/length sliders bi-directionally wired to the `[ ] { }` keyboard commands
-- CLI `--overlay FILE` can be repeated to load multiple overlays at launch
+- CLI `--overlay FILE` can be repeated to load multiple overlays at launch;
+  unnamed overlays use the filename stem and `NAME=FILE` supplies an explicit
+  HUD label.
+- Stack collections support `--overlay-dir PATTERN` to discover per-case mask
+  filenames as sparse overlay roles; missing masks render as empty and common
+  patient/modality directory layouts pair automatically. `--case-regex` remains
+  an override for unusual layouts. CLI header scans show an in-place file counter
+  and elapsed time on interactive terminals.
+- Reused collection sessions are protected by per-tab leases, including their
+  overlay sessions, and VS Code opener readiness now verifies the requested
+  session metadata before acknowledging `backend_ready`.
 - Filesystem picker endpoint (`GET /fs/list`) clamped to `$HOME`. Accepts `base_sid` + `mode` (`overlay` | `vectorfield`) to filter entries by a cheap header-shape peek (`.npy`, `.nii`/`.nii.gz`, `.h5`, `.zarr`); overlay mode requires identical shape, vectorfield mode requires base shape plus one axis of size 3
 - Island collapse affordance: inline `~` at the island's top-right animates the panel into the bottom-left `~` hint circle; external `~` hint only visible while the island is actually collapsed. New `/` hint circle at bottom-right opens the tool menu
 - Compare center tool menu: `/` now re-opens the last-used compare center mode from the tool menu, while compare pane header buttons select diff / overlay / wipe directly. Eligible two-array compare layouts can switch into a big-left arrangement with a wider center pane, and the diff colorbar now matches that center-pane width.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: arrayview
-Version: 0.30.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.30.0 → arrayview-0.31.1}/docs/comparing.md

@@ -37,7 +37,7 @@ Or use the file picker (`Cmd/Ctrl+O`) or drag-and-drop.
 uvx arrayview volume.nii.gz --overlay mask.nii.gz
 ```
 
-Binary mask (0/1), same spatial shape. `[`/`]` adjusts blend opacity. Multiple overlays get automatic palette colors.
+Binary mask (0/1), same spatial shape. `[`/`]` adjusts blend opacity. Multiple overlays get automatic palette colors. Hover an overlay HUD row to focus that mask while dimming the others. Use the overlay HUD or `/ o` to switch between filled masks and outline-only contours.
 
 For cohort review, use `--stack` so image and overlay patterns are paired into
 aligned stacks:

{arrayview-0.30.0 → arrayview-0.31.1}/docs/loading.md

@@ -85,8 +85,18 @@ Native windows also show a static preview while the live viewer warms up.
 ```bash
 uvx arrayview base.npy moving.npy           # compare mode
 uvx arrayview volume.nii.gz --overlay mask.nii.gz
+uvx arrayview volume.nii.gz --overlay "ground truth=mask.nii.gz"
 ```
 
+An unnamed overlay uses the filename stem as its display name (`mask` above).
+Use `NAME=FILE` when a more descriptive label is useful.
+The overlay list opens at the top-right of the image and can be repositioned
+with its small drag grip. Hover a visible row to focus that mask; the other
+visible masks are dimmed until the pointer leaves the list. Use the HUD
+`filled`/`outline` button, or the same control in `/ o`, to switch masks between
+filled regions and contour-only outlines. The eye in the HUD header hides or
+shows all overlays at once.
+
 ## Directory Pattern Collections
 
 Use `--stack` when reviewing many arrays. Passing a directory scans supported
@@ -121,6 +131,18 @@ uvx arrayview --stack \
   --overlay "pred=data/**/pred/**/*.nii.gz"
 ```
 
+When every case has a directory containing separately named masks,
+`--overlay-dir` discovers one overlay role per filename. Masks that are absent
+for a case are shown as empty. ArrayView infers the shared case directory from
+layouts such as `sub-0001/T1_W/` and `sub-0001/masks/`:
+
+```bash
+uvx arrayview --stack "data/*/T1_W/*.nii.gz" \
+  --overlay-dir "data/*/masks"
+```
+
+Repeat `--overlay-dir` to combine masks from multiple per-case directories.
+
 ArrayView pairs files by sorted match order. The first match from each pattern
 belongs to the first case, the second match belongs to the second case, and so
 on. Use `--dry-run` to inspect matches without opening a viewer.
@@ -129,8 +151,8 @@ on. Use `--dry-run` to inspect matches without opening a viewer.
 uvx arrayview --stack "data/**/*_0000.nii.gz" --overlay "gt=data/**/labels/*.nii.gz" --dry-run
 ```
 
-If sorted order is not enough, pass a regex with a `case` group to pair files
-by case id instead:
+For unusual or ambiguous layouts, pass a regex with a `case` group to override
+automatic directory inference:
 
 ```bash
 uvx arrayview --stack "data/**/*.nii.gz" --case-regex "(?P<case>patient-[0-9]+)"

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "arrayview"
-version = "0.30.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.30.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.30.0 → arrayview-0.31.1}/src/arrayview/_io.py

@@ -7,6 +7,7 @@ import glob
 import os
 import re
 import threading
+from concurrent.futures import ThreadPoolExecutor
 from collections import OrderedDict
 
 import numpy as np
@@ -249,6 +250,8 @@ class _NiftiSeries:
                     self._vol_cache.move_to_end(cache_key)
                     return self._vol_cache[cache_key]
             filepath = self._file_matrix[p_idx][m_idx]
+            if filepath is None:
+                return np.zeros(self._vol_shape, dtype=self._dtype)
             nib = _nib()
             img = nib.load(filepath)
             canon = nib.as_closest_canonical(img)
@@ -347,6 +350,8 @@ class _FileSeries:
                 self._vol_cache.move_to_end(cache_key)
                 return self._vol_cache[cache_key]
         filepath = self._file_matrix[p_idx][m_idx]
+        if filepath is None:
+            return np.zeros(self._vol_shape, dtype=self._dtype)
         vol = load_data(filepath)
         with self._cache_lock:
             self._vol_cache[cache_key] = vol
@@ -493,6 +498,8 @@ class _RaggedFileSeries:
                     self._vol_cache.move_to_end(cache_key)
                     return self._vol_cache[cache_key]
             filepath = self._file_matrix[p_idx][m_idx]
+            if filepath is None:
+                return np.zeros(self._spatial_shapes[p_idx][m_idx], dtype=self._dtype)
             if self._all_nifti:
                 nib = _nib()
                 img = nib.load(filepath)
@@ -612,7 +619,43 @@ def _collection_pattern_map(pattern, case_regex):
     return by_case
 
 
-def _series_from_file_matrix(file_matrix, *, load="lazy", stack="auto"):
+def _collection_ancestor_case_key(filepath, depth):
+    parent = os.path.abspath(filepath)
+    for _ in range(depth):
+        parent = os.path.dirname(parent)
+    return os.path.basename(parent)
+
+
+def _collection_paths_map(paths, pattern, *, ancestor_depth):
+    by_case = {}
+    for path in paths:
+        case = _collection_ancestor_case_key(path, ancestor_depth)
+        if not case or case in by_case:
+            return None
+        by_case[case] = path
+    return by_case
+
+
+def _infer_collection_layout_maps(path_lists, patterns):
+    """Infer a shared per-case directory depth for collection patterns."""
+    if not path_lists or len(path_lists[0]) < 2:
+        return None, None
+    for depth in (1, 2, 3):
+        maps = [
+            _collection_paths_map(paths, pattern, ancestor_depth=depth)
+            for paths, pattern in zip(path_lists, patterns)
+        ]
+        if any(by_case is None for by_case in maps):
+            continue
+        case_ids = set(maps[0])
+        if case_ids and all(set(by_case) == case_ids for by_case in maps[1:]):
+            return maps, depth
+    return None, None
+
+
+def _series_from_file_matrix(
+    file_matrix, *, load="lazy", stack="auto", scan_progress=None, scan_label=None
+):
     if load not in {"lazy", "eager"}:
         raise ValueError("load must be 'lazy' or 'eager'.")
     if stack not in {"auto", "dense", "ragged"}:
@@ -620,17 +663,19 @@ def _series_from_file_matrix(file_matrix, *, load="lazy", stack="auto"):
     if not file_matrix or not file_matrix[0]:
         raise ValueError("Cannot build an empty file series.")
 
-    all_paths = [path for row in file_matrix for path in row]
+    all_paths = [path for row in file_matrix for path in row if path is not None]
+    if not all_paths:
+        raise ValueError("Cannot build a file series without any files.")
     all_nifti = all(_is_nifti_path(path) for path in all_paths)
     ref_shape = None
     ref_dtype = None
     spatial_meta = None
 
     if all_nifti:
-        nib = _nib()
         spatial_shapes = []
-        for fpath in all_paths:
-            img, item_meta = _nifti_header_with_meta(fpath)
+        for fpath, img, item_meta in _iter_nifti_headers(
+            all_paths, scan_progress=scan_progress, scan_label=scan_label
+        ):
             shape = tuple(item_meta["canonical_shape"])
             dtype = img.get_data_dtype()
             spatial_shapes.append(shape)
@@ -651,8 +696,14 @@ def _series_from_file_matrix(file_matrix, *, load="lazy", stack="auto"):
         shape_matrix = []
         pos = 0
         for row in file_matrix:
-            shape_matrix.append(spatial_shapes[pos : pos + len(row)])
-            pos += len(row)
+            row_shapes = []
+            for path in row:
+                if path is None:
+                    row_shapes.append(ref_shape)
+                else:
+                    row_shapes.append(spatial_shapes[pos])
+                    pos += 1
+            shape_matrix.append(row_shapes)
         shapes_differ = any(shape != ref_shape for shape in spatial_shapes)
         if stack == "dense" and shapes_differ:
             raise ValueError("Dense stacking requires every file to have the same shape.")
@@ -668,8 +719,9 @@ def _series_from_file_matrix(file_matrix, *, load="lazy", stack="auto"):
             series = _NiftiSeries(file_matrix, ref_shape, ref_dtype, spatial_meta)
         if load == "eager":
             for p, row in enumerate(file_matrix):
-                for m, _path in enumerate(row):
-                    series._get_volume(p, m)
+                for m, path in enumerate(row):
+                    if path is not None:
+                        series._get_volume(p, m)
         return series, spatial_meta
 
     spatial_shapes = []
@@ -691,11 +743,19 @@ def _series_from_file_matrix(file_matrix, *, load="lazy", stack="auto"):
                 f"Dtype mismatch: {os.path.basename(fpath)!r} has dtype "
                 f"{dtype}, expected {ref_dtype}."
             )
+        if scan_progress is not None:
+            scan_progress(scan_label, fpath)
     shape_matrix = []
     pos = 0
     for row in file_matrix:
-        shape_matrix.append(spatial_shapes[pos : pos + len(row)])
-        pos += len(row)
+        row_shapes = []
+        for path in row:
+            if path is None:
+                row_shapes.append(ref_shape)
+            else:
+                row_shapes.append(spatial_shapes[pos])
+                pos += 1
+        shape_matrix.append(row_shapes)
     shapes_differ = any(shape != ref_shape for shape in spatial_shapes)
     if stack == "dense" and shapes_differ:
         raise ValueError("Dense stacking requires every file to have the same shape.")
@@ -705,23 +765,63 @@ def _series_from_file_matrix(file_matrix, *, load="lazy", stack="auto"):
         series = _FileSeries(file_matrix, ref_shape, ref_dtype, spatial_meta=None)
     if load == "eager":
         for p, row in enumerate(file_matrix):
-            for m, _path in enumerate(row):
-                series._get_volume(p, m)
+            for m, path in enumerate(row):
+                if path is not None:
+                    series._get_volume(p, m)
     return series, None
 
 
-def load_dir_collection(base_patterns, overlays=None, case_regex=None, *, load="lazy", stack="auto"):
+def _collection_scan_workers():
+    raw = os.environ.get("ARRAYVIEW_COLLECTION_SCAN_WORKERS")
+    if raw is not None:
+        try:
+            return max(1, int(raw))
+        except ValueError:
+            return 1
+    cpu = os.cpu_count() or 4
+    return max(1, min(8, cpu))
+
+
+def _iter_nifti_headers(paths, *, scan_progress=None, scan_label=None):
+    workers = _collection_scan_workers()
+    if workers <= 1 or len(paths) < 8:
+        for path in paths:
+            img, item_meta = _nifti_header_with_meta(path)
+            if scan_progress is not None:
+                scan_progress(scan_label, path)
+            yield path, img, item_meta
+        return
+
+    with ThreadPoolExecutor(max_workers=workers) as executor:
+        for path, result in zip(paths, executor.map(_nifti_header_with_meta, paths)):
+            img, item_meta = result
+            if scan_progress is not None:
+                scan_progress(scan_label, path)
+            yield path, img, item_meta
+
+
+def load_dir_collection(
+    base_patterns,
+    overlays=None,
+    case_regex=None,
+    *,
+    load="lazy",
+    stack="auto",
+    scan_progress=None,
+):
     """Load recursive collection patterns as aligned lazy image/overlay stacks.
 
     *base_patterns* are image channel/modality patterns.  *overlays* is an
-    ordered list of ``(name, pattern)`` pairs.  By default, each pattern's
-    sorted matches are paired by position.  With *case_regex*, files are paired
-    by the regex's named ``case`` group instead.
+    ordered list of ``(name, pattern)`` pairs. A third true value marks a
+    sparse overlay whose missing cases should render as empty masks. By
+    default, each pattern's sorted matches are paired by position. With
+    *case_regex*, files are paired by the regex's named ``case`` group instead.
     """
     if not base_patterns:
         raise ValueError("--stack requires at least one positional image pattern.")
     overlays = overlays or []
 
+    inferred_case_depth = None
     if case_regex:
         base_maps = [
             _collection_pattern_map(pattern, case_regex=case_regex)
@@ -738,56 +838,125 @@ def load_dir_collection(base_patterns, overlays=None, case_regex=None, *, load="
         base_matrix = [[by_case[case] for by_case in base_maps] for case in case_ids]
     else:
         base_lists = [_collection_pattern_paths(pattern) for pattern in base_patterns]
-        n_cases = len(base_lists[0])
-        for idx, paths in enumerate(base_lists[1:], start=2):
-            if len(paths) != n_cases:
-                raise ValueError(
-                    f"Image pattern {idx} matched {len(paths)} file(s), "
-                    f"expected {n_cases} to match image pattern 1."
-                )
-        case_ids = [
-            _default_collection_case_key(path)
-            for path in base_lists[0]
-        ]
-        if len(set(case_ids)) != len(case_ids):
+        inferred_maps, inferred_case_depth = _infer_collection_layout_maps(
+            base_lists, base_patterns
+        )
+        if inferred_maps is not None:
+            case_ids = sorted(inferred_maps[0])
+            base_matrix = [
+                [by_case[case] for by_case in inferred_maps] for case in case_ids
+            ]
+        else:
+            n_cases = len(base_lists[0])
+            for idx, paths in enumerate(base_lists[1:], start=2):
+                if len(paths) != n_cases:
+                    raise ValueError(
+                        f"Image pattern {idx} matched {len(paths)} file(s), "
+                        f"expected {n_cases} to match image pattern 1."
+                    )
             case_ids = [
-                os.path.basename(os.path.dirname(path)) or _default_collection_case_key(path)
+                _default_collection_case_key(path)
                 for path in base_lists[0]
             ]
-        base_matrix = [list(row) for row in zip(*base_lists)]
-    data, spatial_meta = _series_from_file_matrix(base_matrix, load=load, stack=stack)
+            if len(set(case_ids)) != len(case_ids):
+                case_ids = [
+                    os.path.basename(os.path.dirname(path))
+                    or _default_collection_case_key(path)
+                    for path in base_lists[0]
+                ]
+            base_matrix = [list(row) for row in zip(*base_lists)]
+    data, spatial_meta = _series_from_file_matrix(
+        base_matrix,
+        load=load,
+        stack=stack,
+        scan_progress=scan_progress,
+        scan_label="images",
+    )
     spatial_shape = data._vol_shape
 
     overlay_items = []
     overlay_reports = []
-    for name, pattern in overlays:
-        if case_regex:
+    for overlay_spec in overlays:
+        name, pattern = overlay_spec[:2]
+        allow_missing = len(overlay_spec) > 2 and bool(overlay_spec[2])
+        report_pattern = overlay_spec[3] if len(overlay_spec) > 3 else pattern
+        if isinstance(pattern, dict):
+            by_case = pattern
+            missing_cases = [case for case in case_ids if case not in by_case]
+            if missing_cases and not allow_missing:
+                raise ValueError(
+                    f"Overlay {name!r} is missing case(s): "
+                    f"{', '.join(repr(c) for c in missing_cases)}."
+                )
+            matrix = [[by_case.get(case)] for case in case_ids]
+            extras = sorted(set(by_case.keys()) - set(case_ids))
+        elif case_regex:
             by_case = _collection_pattern_map(pattern, case_regex=case_regex)
             missing_cases = [case for case in case_ids if case not in by_case]
-            if missing_cases:
+            if missing_cases and not allow_missing:
                 raise ValueError(
                     f"Overlay {name!r} is missing case(s): "
                     f"{', '.join(repr(c) for c in missing_cases)}."
                 )
-            matrix = [[by_case[case]] for case in case_ids]
+            matrix = [[by_case.get(case)] for case in case_ids]
             extras = sorted(set(by_case.keys()) - set(case_ids))
+        elif inferred_case_depth is not None:
+            paths = _collection_pattern_paths(pattern)
+            by_case = _collection_paths_map(
+                paths, pattern, ancestor_depth=inferred_case_depth
+            )
+            if by_case is None:
+                raise ValueError(
+                    f"Overlay {name!r} has multiple files for an inferred case. "
+                    "Use --case-regex to describe this layout explicitly."
+                )
+            missing_cases = [case for case in case_ids if case not in by_case]
+            if missing_cases and not allow_missing:
+                raise ValueError(
+                    f"Overlay {name!r} is missing case(s): "
+                    f"{', '.join(repr(c) for c in missing_cases)}."
+                )
+            matrix = [[by_case.get(case)] for case in case_ids]
+            extras = sorted(set(by_case) - set(case_ids))
         else:
             paths = _collection_pattern_paths(pattern)
-            if len(paths) != len(case_ids):
+            if len(paths) != len(case_ids) and not allow_missing:
                 raise ValueError(
                     f"Overlay {name!r} matched {len(paths)} file(s), "
                     f"expected {len(case_ids)} to match image pattern 1."
                 )
+            if allow_missing:
+                raise ValueError(
+                    "Could not infer case directories for sparse overlays. "
+                    "Use a per-case directory layout or pass --case-regex."
+                )
             matrix = [[path] for path in paths]
             extras = []
-        ov_data, _ov_meta = _series_from_file_matrix(matrix, load=load, stack=stack)
+        ov_data, _ov_meta = _series_from_file_matrix(
+            matrix,
+            load=load,
+            stack=stack,
+            scan_progress=scan_progress,
+            scan_label=name,
+        )
         if not getattr(data, "_av_ragged", False) and ov_data._vol_shape != spatial_shape:
             raise ValueError(
                 f"Overlay {name!r} has spatial shape {ov_data._vol_shape}, "
                 f"expected {spatial_shape}."
             )
-        overlay_items.append({"name": name, "data": ov_data, "pattern": pattern})
-        overlay_reports.append({"name": name, "pattern": pattern, "ignored_cases": extras})
+        overlay_items.append({"name": name, "data": ov_data, "pattern": report_pattern})
+        overlay_reports.append(
+            {
+                "name": name,
+                "pattern": report_pattern,
+                "ignored_cases": extras,
+                "missing_cases": (
+                    missing_cases
+                    if case_regex or inferred_case_depth is not None
+                    else []
+                ),
+            }
+        )
 
     summary = {
         "cases": case_ids,