arrayview 0.27.2__py3-none-any.whl → 0.28.0__py3-none-any.whl

arrayview/ARCHITECTURE.md

@@ -6,14 +6,12 @@
 CLI / Python API
    ├─ view() / _launcher.py → FastAPI server (_server.py)       [network mode]
    │     /ws/{sid} WebSocket, /load register arrays, /seg/* segmentation
-   └─ Stdio server (_stdio_server.py)                           [direct webview mode]
-         stdin/stdout JSON+binary, no network — VS Code extension spawns subprocess
 
-Server (either mode)
+Server
    ├─ _session.py    Session objects, caches, render thread
    ├─ _render.py     Slice extraction → RGBA → PNG pipeline
    ├─ _analysis.py / _diff.py / _overlays.py / _vectorfield.py
-   │                 Shared backend helpers used by FastAPI and stdio
+   │                 Shared backend helpers used by routes and WebSocket handlers
    └─ _io.py         File loading (numpy, nifti, zarr, DICOM, …)
 
 Frontend (_viewer.html — single self-contained HTML file)
@@ -29,7 +27,7 @@ Frontend (_viewer.html — single self-contained HTML file)
 |--------------------|------------------------------------|-------------|
 | Jupyter            | Inline iframe                      | network     |
 | VS Code local      | Webview panel (network)            | network     |
-| VS Code tunnel     | Direct webview (stdio)             | stdio       |
+| VS Code tunnel     | Webview panel (forwarded WebSocket)| network     |
 | Julia              | System browser                     | network     |
 | CLI / Python script | Native pywebview                   | network     |
 | SSH terminal       | Prints URL — user forwards port with `ssh -L` | network |
@@ -54,10 +52,9 @@ Detection logic lives in `_platform.py`. Display opening logic lives in `_launch
 | `_segmentation.py` | 227 | nnInteractive segmentation client (pure HTTP, no nnInteractive dependency) |
 | `_server.py` | 3704 | FastAPI app, all REST + WebSocket routes, HTML template serving |
 | `_session.py` | 344 | `Session` class, global state (sockets, loops), render thread, prefetch, cache budgets, constants |
-| `_stdio_server.py` | 767 | Stdio transport for VS Code direct webview — JSON stdin, binary stdout |
 | `_torch.py` | 217 | PyTorch integration: `view_batch()`, `TrainingMonitor` (lazy torch import) |
 | `_vectorfield.py` | 231 | Shared vector field layout validation and arrow sampling |
-| `_vscode.py` | 1014 | VS Code extension install/management, signal-file IPC, shared-memory IPC, browser opening |
+| `_vscode.py` | 1014 | VS Code extension install/management, signal-file IPC, tunnel URL opening |
 | `_viewer.html` | 24103 | **The entire frontend** — CSS + JS in a single file, all viewing modes |
 | `_shell.html` | 174 | Tab-bar shell for native pywebview — wraps viewer iframes, manages multi-tab sessions |
 
@@ -80,7 +77,7 @@ The frontend is a single self-contained HTML file (~24k lines). No build step, n
 **JavaScript (lines ~2439–24103)**
 | Section | What it covers |
 |---------|----------------|
-| Constants and Transport Setup | WS URL construction, stdio/postMessage transport abstraction |
+| Constants and Transport Setup | HTTP/WebSocket URL construction |
 | Viewer State Variables | All mutable state: current slice indices, zoom, mode flags |
 | Mode Registry | Mode name → enter/exit function mapping |
 | PanManager | Canvas panning state machine (normal + compare modes) |
@@ -218,7 +215,7 @@ Slice data arrives as raw binary (RGBA bytes). The header format and byte offset
    └─ Open display                      # _launcher.py → _vscode.py / pywebview / browser
 
 2. Browser loads _viewer.html           # _server.py serves from package resources
-   ├─ Establish WebSocket /ws/{sid}     # or stdio transport for VS Code direct
+   ├─ Establish WebSocket /ws/{sid}
    └─ Fetch /meta/{sid}                 # Session metadata: shape, dtype, colormaps
 
 3. User scrolls / interacts
@@ -233,6 +230,3 @@ Slice data arrives as raw binary (RGBA bytes). The header format and byte offset
        ├─ drawImage() to canvas
        └─ Update info bar, colorbar, eggs
 ```
-
-### Stdio Transport Variant (VS Code Direct Webview)
-Same pipeline, but `_stdio_server.py` replaces the FastAPI+WebSocket layer. Messages are JSON on stdin, binary responses are length-prefixed on stdout. The VS Code extension bridges between the webview's `postMessage` and the subprocess stdio.

arrayview/__init__.py

@@ -7,12 +7,13 @@ __all__ = [
     "arrayview",
     "view",
     "view_batch",
+    "view_dir",
     "zarr_chunk_preset",
 ]
 
 
 def __getattr__(name: str):
-    if name in {"arrayview", "view", "ViewHandle"}:
+    if name in {"arrayview", "view", "view_dir", "ViewHandle"}:
         from arrayview import _launcher
 
         return getattr(_launcher, name)

arrayview/_analysis.py

@@ -19,7 +19,7 @@ def _visible_shape(session) -> list[int]:
 
 
 def _build_metadata(session) -> dict:
-    """Build metadata for HTTP and stdio transports."""
+    """Build metadata shared by HTTP routes and WebSocket startup."""
     target_shape = session.spatial_shape if session.rgb_axis is not None else session.shape
     meta = {
         "shape": [int(s) for s in target_shape],

arrayview/_io.py

@@ -2,7 +2,10 @@
 
 from __future__ import annotations
 
+import fnmatch
 import os
+import threading
+from collections import OrderedDict
 
 import numpy as np
 
@@ -174,17 +177,438 @@ def _load_nifti_with_meta(filepath):
     return arr, meta
 
 
-def load_data_with_meta(filepath, key=None):
+# ---------------------------------------------------------------------------
+# File series — lazy 4D/5D view over a directory of same-shape volumes
+# ---------------------------------------------------------------------------
+
+
+class _NiftiSeries:
+    """Lazy 4D/5D view over a directory of same-shape NIfTI files.
+
+    ``file_matrix`` is a P x M list-of-lists of filepaths (P patients,
+    M modalities).  With M == 1 the shape is ``(*vol_shape, P)``; with
+    M > 1 it is ``(*vol_shape, P, M)``.  ``__getitem__`` maps the trailing
+    stack axis/axes to the source file, opens it (canonical reorient,
+    LRU-cached), and forwards the spatial key so only the requested slice
+    is materialised.
+    """
+
+    _av_lazy = True
+
+    def __init__(self, file_matrix, vol_shape, dtype, spatial_meta=None):
+        self._file_matrix = file_matrix
+        self._vol_shape = tuple(vol_shape)
+        self._dtype = np.dtype(dtype)
+        self._spatial_meta = spatial_meta
+        n_patients = len(file_matrix)
+        n_modalities = len(file_matrix[0]) if file_matrix else 0
+        if n_modalities <= 1:
+            self.shape = (*self._vol_shape, n_patients)
+            self._stack_axes = (len(self.shape) - 1,)
+        else:
+            self.shape = (*self._vol_shape, n_patients, n_modalities)
+            self._stack_axes = (len(self.shape) - 2, len(self.shape) - 1)
+        self.ndim = len(self.shape)
+        self._vol_cache: OrderedDict = OrderedDict()
+        self._vol_cache_cap = int(
+            os.environ.get("ARRAYVIEW_NIFTI_SERIES_VOL_CACHE", 3)
+        )
+        self._cache_lock = threading.Lock()
+
+    @property
+    def dtype(self):
+        return self._dtype
+
+    def _get_volume(self, p_idx, m_idx):
+        cache_key = (p_idx, m_idx)
+        with self._cache_lock:
+            if cache_key in self._vol_cache:
+                self._vol_cache.move_to_end(cache_key)
+                return self._vol_cache[cache_key]
+        filepath = self._file_matrix[p_idx][m_idx]
+        nib = _nib()
+        img = nib.load(filepath)
+        canon = nib.as_closest_canonical(img)
+        vol = np.asarray(canon.dataobj)
+        with self._cache_lock:
+            self._vol_cache[cache_key] = vol
+            self._vol_cache.move_to_end(cache_key)
+            while len(self._vol_cache) > self._vol_cache_cap:
+                self._vol_cache.popitem(last=False)
+        return vol
+
+    def __getitem__(self, key):
+        if not isinstance(key, tuple):
+            key = (key,)
+        has_special = any(k is None or k is Ellipsis for k in key)
+        if not has_special and len(key) <= self.ndim:
+            padded = list(key) + [slice(None)] * (self.ndim - len(key))
+            stack_vals = [padded[i] for i in self._stack_axes]
+            if all(isinstance(s, (int, np.integer)) for s in stack_vals):
+                spatial_positions = [
+                    i for i in range(self.ndim) if i not in self._stack_axes
+                ]
+                spatial_key = tuple(padded[i] for i in spatial_positions)
+                n_p = len(self._file_matrix)
+                n_m = len(self._file_matrix[0]) if self._file_matrix else 0
+                p_idx = int(stack_vals[0])
+                if p_idx < 0:
+                    p_idx += n_p
+                if len(self._stack_axes) == 1:
+                    m_idx = 0
+                else:
+                    m_idx = int(stack_vals[1])
+                    if m_idx < 0:
+                        m_idx += n_m
+                vol = self._get_volume(p_idx, m_idx)
+                return vol[spatial_key]
+        return np.asarray(self)[key]
+
+    def __array__(self, dtype=None):
+        result = np.empty(self.shape, dtype=self._dtype)
+        for p, row in enumerate(self._file_matrix):
+            for m, fpath in enumerate(row):
+                vol = self._get_volume(p, m)
+                if len(self._stack_axes) == 1:
+                    result[..., p] = vol
+                else:
+                    result[..., p, m] = vol
+        if dtype is not None:
+            result = result.astype(dtype)
+        return result
+
+
+class _FileSeries:
+    """Lazy 4D/5D view over a directory of same-shape array files.
+
+    Like ``_NiftiSeries`` but works with any supported file format
+    (.npy, .npz, .zarr, .pt/.pth, .h5/.hdf5, .tif/.tiff, .mat).
+    Uses ``load_data`` for each volume — no nibabel reorientation.
+    """
+
+    _av_lazy = True
+
+    def __init__(self, file_matrix, vol_shape, dtype, spatial_meta=None):
+        self._file_matrix = file_matrix
+        self._vol_shape = tuple(vol_shape)
+        self._dtype = np.dtype(dtype)
+        self._spatial_meta = spatial_meta
+        n_patients = len(file_matrix)
+        n_modalities = len(file_matrix[0]) if file_matrix else 0
+        if n_modalities <= 1:
+            self.shape = (*self._vol_shape, n_patients)
+            self._stack_axes = (len(self.shape) - 1,)
+        else:
+            self.shape = (*self._vol_shape, n_patients, n_modalities)
+            self._stack_axes = (len(self.shape) - 2, len(self.shape) - 1)
+        self.ndim = len(self.shape)
+        self._vol_cache: OrderedDict = OrderedDict()
+        self._vol_cache_cap = int(
+            os.environ.get("ARRAYVIEW_FILE_SERIES_VOL_CACHE", 3)
+        )
+        self._cache_lock = threading.Lock()
+
+    @property
+    def dtype(self):
+        return self._dtype
+
+    def _get_volume(self, p_idx, m_idx):
+        cache_key = (p_idx, m_idx)
+        with self._cache_lock:
+            if cache_key in self._vol_cache:
+                self._vol_cache.move_to_end(cache_key)
+                return self._vol_cache[cache_key]
+        filepath = self._file_matrix[p_idx][m_idx]
+        vol = load_data(filepath)
+        with self._cache_lock:
+            self._vol_cache[cache_key] = vol
+            while len(self._vol_cache) > self._vol_cache_cap:
+                self._vol_cache.popitem(last=False)
+        return vol
+
+    def __getitem__(self, key):
+        if not isinstance(key, tuple):
+            key = (key,)
+        has_special = any(k is None or k is Ellipsis for k in key)
+        if not has_special and len(key) <= self.ndim:
+            padded = list(key) + [slice(None)] * (self.ndim - len(key))
+            stack_vals = [padded[i] for i in self._stack_axes]
+            if all(isinstance(s, (int, np.integer)) for s in stack_vals):
+                spatial_positions = [
+                    i for i in range(self.ndim) if i not in self._stack_axes
+                ]
+                spatial_key = tuple(padded[i] for i in spatial_positions)
+                n_p = len(self._file_matrix)
+                n_m = len(self._file_matrix[0]) if self._file_matrix else 0
+                p_idx = int(stack_vals[0])
+                if p_idx < 0:
+                    p_idx += n_p
+                if len(self._stack_axes) == 1:
+                    m_idx = 0
+                else:
+                    m_idx = int(stack_vals[1])
+                    if m_idx < 0:
+                        m_idx += n_m
+                vol = self._get_volume(p_idx, m_idx)
+                return vol[spatial_key]
+        return np.asarray(self)[key]
+
+    def __array__(self, dtype=None):
+        result = np.empty(self.shape, dtype=self._dtype)
+        for p, row in enumerate(self._file_matrix):
+            for m, fpath in enumerate(row):
+                vol = self._get_volume(p, m)
+                if len(self._stack_axes) == 1:
+                    result[..., p] = vol
+                else:
+                    result[..., p, m] = vol
+        if dtype is not None:
+            result = result.astype(dtype)
+        return result
+
+
+def _is_nifti_path(filepath):
+    """True if *filepath* ends with .nii or .nii.gz."""
+    return filepath.endswith(".nii") or filepath.endswith(".nii.gz")
+
+
+def _get_ext(filepath):
+    """Return the extension of *filepath*, normalising .nii.gz and .zarr.zip."""
+    lower = filepath.lower()
+    if lower.endswith(".nii.gz"):
+        return ".nii.gz"
+    if lower.endswith(".zarr.zip"):
+        return ".zarr.zip"
+    return os.path.splitext(lower)[1]
+
+
+def _load_file_series(path, select=None):
+    """Build a lazy series from a directory of supported array files.
+
+    Walks *path* recursively, groups files of any supported format by
+    immediate parent folder (= patient).  With *select* (a list of fnmatch
+    patterns), picks one file per pattern per patient → 5D ``(*vol, P, M)``.
+    Without *select*, requires exactly one file per patient → 4D ``(*vol, P)``.
+
+    If every file is NIfTI (.nii/.nii.gz), delegates to
+    ``_load_nifti_series`` for canonical reorientation.  Otherwise builds
+    a ``_FileSeries`` using ``load_data`` per volume.
+
+    Returns ``(series, spatial_meta)``.
+    """
+    # ── collect files by parent directory ──────────────────────────
+    patients: dict[str, list[str]] = {}
+    all_nifti = True
+
+    for root, dirs, files in os.walk(path):
+        supported = sorted(
+            os.path.join(root, f)
+            for f in files
+            if _get_ext(f) in _SUPPORTED_EXTS
+        )
+        if supported:
+            patients[root] = supported
+            if all_nifti:
+                all_nifti = all(_is_nifti_path(p) for p in supported)
+            # A directory with supported files is the series unit.  Do not
+            # treat nested sub-folders as additional patients.
+            dirs[:] = []
+
+    if not patients:
+        raise ValueError(
+            f"No supported array files found under {path!r}. "
+            f"Supported: {', '.join(sorted(_SUPPORTED_EXTS))}"
+        )
+
+    # NIfTI-only → preserve canonical reorientation + lazy dataobj slicing
+    if all_nifti:
+        return _load_nifti_series(path, select=select)
+
+    # ── build file matrix ──────────────────────────────────────────
+    select_patterns = select or []
+    patient_dirs = sorted(patients.keys())
+    file_matrix: list[list[str]] = []
+
+    if select_patterns:
+        for pdir in patient_dirs:
+            selected: list[str] = []
+            for pattern in select_patterns:
+                matches = [
+                    f
+                    for f in patients[pdir]
+                    if fnmatch.fnmatch(os.path.basename(f), pattern)
+                ]
+                if not matches:
+                    raise ValueError(
+                        f"Folder {pdir!r}: no file matches --select "
+                        f"pattern {pattern!r}. Available: "
+                        f"{[os.path.basename(f) for f in patients[pdir]]}"
+                    )
+                if len(matches) > 1:
+                    raise ValueError(
+                        f"Folder {pdir!r}: multiple files match "
+                        f"--select pattern {pattern!r}: "
+                        f"{[os.path.basename(f) for f in matches]}. "
+                        "Make patterns more specific."
+                    )
+                selected.append(matches[0])
+            file_matrix.append(selected)
+    else:
+        for pdir in patient_dirs:
+            files = patients[pdir]
+            if len(files) == 1:
+                file_matrix.append([files[0]])
+            else:
+                raise ValueError(
+                    f"Folder {pdir!r} contains {len(files)} files: "
+                    f"{[os.path.basename(f) for f in files]}. "
+                    "Use --select PATTERN to pick one (or more) per folder. "
+                    "Example: --select '*t1*' --select '*t2*' --select '*flair*'"
+                )
+
+    # ── validate shape / dtype uniformity ──────────────────────────
+    ref_shape = None
+    ref_dtype = None
+    for row in file_matrix:
+        for fpath in row:
+            arr = load_data(fpath)
+            shape = arr.shape
+            dtype = arr.dtype
+            if ref_shape is None:
+                ref_shape = shape
+                ref_dtype = dtype
+            elif shape != ref_shape:
+                raise ValueError(
+                    f"Shape mismatch: {os.path.basename(fpath)!r} has shape "
+                    f"{shape}, expected {ref_shape}."
+                )
+            elif dtype != ref_dtype:
+                raise ValueError(
+                    f"Dtype mismatch: {os.path.basename(fpath)!r} has dtype "
+                    f"{dtype}, expected {ref_dtype}."
+                )
+
+    series = _FileSeries(file_matrix, ref_shape, ref_dtype, spatial_meta=None)
+    return series, None
+
+
+def _load_nifti_series(path, select=None):
+    """Build a lazy ``_NiftiSeries`` from a directory of NIfTI files.
+
+    Walks *path* recursively, groups ``.nii``/``.nii.gz`` by immediate parent
+    folder (= patient).  With *select* (a list of fnmatch patterns), picks one
+    file per pattern per patient → 5D ``(*vol, P, M)``.  Without *select*,
+    requires exactly one NIfTI per patient → 4D ``(*vol, P)``.
+
+    Returns ``(series, spatial_meta)``.
+    """
+    nib = _nib()
+
+    patients: dict[str, list[str]] = {}
+    for root, dirs, files in os.walk(path):
+        nii_files = sorted(
+            os.path.join(root, f)
+            for f in files
+            if f.endswith(".nii") or f.endswith(".nii.gz")
+        )
+        if nii_files:
+            patients[root] = nii_files
+            # A directory with NIfTI files is the series unit.  Do not treat
+            # nested mask/derived-output folders as additional patients.
+            dirs[:] = []
+
+    if not patients:
+        raise ValueError(
+            f"No NIfTI files (.nii/.nii.gz) found under {path!r}. "
+            "If the folder contains DICOM (.dcm) files, convert them to NIfTI "
+            "first (e.g. `dcm2niix -o <out> <dicom_dir>`)."
+        )
+
+    select_patterns = select or []
+    patient_dirs = sorted(patients.keys())
+    file_matrix: list[list[str]] = []
+
+    if select_patterns:
+        for pdir in patient_dirs:
+            selected: list[str] = []
+            for pattern in select_patterns:
+                matches = [
+                    f
+                    for f in patients[pdir]
+                    if fnmatch.fnmatch(os.path.basename(f), pattern)
+                ]
+                if not matches:
+                    raise ValueError(
+                        f"Patient folder {pdir!r}: no file matches --select "
+                        f"pattern {pattern!r}. Available: "
+                        f"{[os.path.basename(f) for f in patients[pdir]]}"
+                    )
+                if len(matches) > 1:
+                    raise ValueError(
+                        f"Patient folder {pdir!r}: multiple files match "
+                        f"--select pattern {pattern!r}: "
+                        f"{[os.path.basename(f) for f in matches]}. "
+                        "Make patterns more specific."
+                    )
+                selected.append(matches[0])
+            file_matrix.append(selected)
+    else:
+        for pdir in patient_dirs:
+            nii_files = patients[pdir]
+            if len(nii_files) == 1:
+                file_matrix.append([nii_files[0]])
+            else:
+                raise ValueError(
+                    f"Patient folder {pdir!r} contains {len(nii_files)} NIfTI "
+                    f"files: {[os.path.basename(f) for f in nii_files]}. "
+                    "Use --select PATTERN to pick one (or more) per patient. "
+                    "Example: --select '*t1*' --select '*t2*' --select '*flair*'"
+                )
+
+    ref_shape = None
+    ref_dtype = None
+    for row in file_matrix:
+        for fpath in row:
+            img = nib.load(fpath)
+            shape = tuple(int(s) for s in img.shape)
+            dtype = img.get_data_dtype()
+            if ref_shape is None:
+                ref_shape = shape
+                ref_dtype = dtype
+            elif shape != ref_shape:
+                raise ValueError(
+                    f"Shape mismatch: {os.path.basename(fpath)!r} has shape "
+                    f"{shape}, expected {ref_shape}."
+                )
+            elif dtype != ref_dtype:
+                raise ValueError(
+                    f"Dtype mismatch: {os.path.basename(fpath)!r} has dtype "
+                    f"{dtype}, expected {ref_dtype}."
+                )
+
+    _, spatial_meta = _load_nifti_with_meta(file_matrix[0][0])
+    series = _NiftiSeries(file_matrix, ref_shape, ref_dtype, spatial_meta=spatial_meta)
+    return series, spatial_meta
+
+
+def load_data_with_meta(filepath, key=None, select=None):
     """Like load_data but also returns spatial metadata for NIfTI files.
 
     Returns (array, meta_or_None). meta is None for non-NIfTI formats.
+    When *filepath* is a directory, loads it as a file series (see
+    ``_load_file_series``).
     """
+    if os.path.isdir(filepath):
+        return _load_file_series(filepath, select=select)
     if filepath.endswith(".nii") or filepath.endswith(".nii.gz"):
         return _load_nifti_with_meta(filepath)
     return load_data(filepath, key=key), None
 
 
 def load_data(filepath, key=None):
+    if os.path.isdir(filepath):
+        series, _meta = _load_file_series(filepath)
+        return series
     if filepath.endswith(".npy"):
         # Eager-load small-to-medium files into RAM.  mmap_mode="r" on a C-order
         # 4D+ array forces scattered page faults for every orthogonal slice
@@ -326,6 +750,9 @@ FULL_LOAD_EXTS = frozenset([".pt", ".pth", ".tif", ".tiff", ".mat"])
 def _peek_file_shape(fpath: str, ext: str):
     """Try to return shape quickly without loading the full array. Returns None on failure."""
     try:
+        if os.path.isdir(fpath):
+            series, _ = _load_file_series(fpath)
+            return list(series.shape)
         if ext == ".npy":
             arr = np.load(fpath, mmap_mode="r", allow_pickle=False)
             return list(arr.shape)

arrayview/_launch_plan.py

@@ -37,7 +37,6 @@ class Invocation(_StrEnum):
     PYTHON = "python"
     JUPYTER = "jupyter"
     JULIA = "julia"
-    STDIO = "stdio"
     CODEX = "codex"
 
 
@@ -52,8 +51,6 @@ class Environment(_StrEnum):
 
 class Transport(_StrEnum):
     HTTP = "http"
-    STDIO_FILE = "stdio_file"
-    STDIO_SHM = "stdio_shm"
     NONE = "none"
 
 
@@ -77,7 +74,6 @@ class Registration(_StrEnum):
     HTTP_LOAD = "http_load"
     DAEMON_STARTUP = "daemon_startup"
     IN_PROCESS_SESSION = "in_process_session"
-    STDIO_REGISTER = "stdio_register"
     RELAY = "relay"