arrayview 0.31.2__tar.gz → 0.32.0__tar.gz

{arrayview-0.31.2 → arrayview-0.32.0}/.github/workflows/launch-contracts.yml

@@ -30,12 +30,12 @@ jobs:
         os: [ubuntu-latest, macos-latest, windows-latest]
     runs-on: ${{ matrix.os }}
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v6
         with:
           python-version: "3.12"
-      - uses: astral-sh/setup-uv@v6
-      - uses: actions/setup-node@v4
+      - uses: astral-sh/setup-uv@v8
+      - uses: actions/setup-node@v6
         with:
           node-version: "22"
       - run: uv sync --frozen --group dev --group test

{arrayview-0.31.2 → arrayview-0.32.0}/.mex/context/lifecycle.md

@@ -16,7 +16,7 @@ edges:
     condition: when component boundaries or display routing need broader context
   - target: context/stack.md
     condition: when VS Code, FastAPI, WebSocket, or packaging details are needed
-last_updated: 2026-06-19
+last_updated: 2026-07-14
 ---
 
 # Lifecycle
@@ -60,8 +60,10 @@ This contract describes who owns the backend, when it starts, and what closes it
 
 - Remote or tunnel launches may persist when `--serve` or tunnel display ownership requires it.
 - VS Code tunnel display uses forwarded localhost URLs; the extension should configure the port, promote privacy when available, and resolve the URL with `asExternalUri`.
-- With multiple registered tunnel windows, a missing or stale `ARRAYVIEW_WINDOW_ID` uses the shared broadcast signal; only the focused VS Code window may claim it.
+- With multiple registered tunnel windows, a missing `ARRAYVIEW_WINDOW_ID` first recovers the exact live registration from the terminal's IPC hook. Only when no exact registration exists does it use the shared focused-window broadcast fallback.
 - An exact registered `ARRAYVIEW_WINDOW_ID` wins; do not redirect it to a newer same-parent registration because live tunnel windows can share ancestry.
+- Protocol request claims are atomic across extension hosts. Compatibility queue copies with the same request ID must never open in a sibling window or overwrite a terminal ACK.
+- Tunnel `asExternalUri` results must be non-loopback. Remote-SSH may legitimately resolve to a local forwarded URL and must not be subjected to tunnel-only public-port commands.
 - Plain SSH should use `localhost` forwarding guidance and stay transient unless a shared server was explicitly requested.
 
 ## Shared Rules
@@ -70,6 +72,14 @@ This contract describes who owns the backend, when it starts, and what closes it
 - `release_session()` is the session-release primitive.
 - Viewer WebSocket connect/disconnect owns active viewer counts.
 - URL panel disposal must release every SID encoded in the URL: `sid`, `compare_sid`, `compare_sids`, and `overlay_sid`.
+- Tunnel panel disposal posts release requests to the local backend immediately;
+  the forwarded public URL is display-only and is not the cleanup authority.
+- Reused file and collection sessions acquire one lease per tab, so closing one
+  tab cannot invalidate another tab that shares the same SID.
+- A VS Code readiness ACK includes the live opener version and is terminal only
+  after the requested SID exists and the viewer reports its first rendered frame.
+- Existing-server tunnel loads publish a pending SID before loading large files, so port resolution can overlap disk I/O. Pending metadata probes return immediately and the WebSocket waits on the shared pending-session event.
+- Older ArrayView packages must not delete or downgrade a newer installed opener.
 - Tunnel registration cleanup must not remove live same-tunnel sibling windows.
 - Explicit cleanup wins over implicit disappearance.
 - Any VS Code extension source change must rebuild `src/arrayview/arrayview-opener.vsix` and keep the packaged version in sync.

{arrayview-0.31.2 → arrayview-0.32.0}/.mex/context/project-state.md

@@ -7,7 +7,7 @@ triggers:
   - "recent work"
   - "active feature"
   - "shipped recently"
-last_updated: 2026-06-30
+last_updated: 2026-07-20
 ---
 
 # Project State
@@ -20,8 +20,8 @@ last_updated: 2026-06-30
 - Rendering pipeline: colormaps, complex modes, mosaic, RGB/RGBA, projections, overlays
 - Backend transport: FastAPI HTTP/WebSocket is the single viewer transport; shared helpers keep route modules small for metadata/analysis, compare/diff, overlay compositing, and vector field layout/arrow sampling.
 - NIfTI spatial metadata, RAS resampling
-- Directory collections are header-scanned and lazy by default: compatible files form a dense virtual stack, mixed shapes use a ragged collection, and `--load lazy|eager` plus `--stack-policy auto|dense|ragged` make both choices explicit. Compressed NIfTI volumes use a byte-bounded LRU cache; `view_dir()` exposes the same controls.
-- VS Code extension v0.14.27 — stable window ID via `EnvironmentVariableCollection`; `arrayview.openInFloatingWindow` setting moves new tabs to a floating window; `view(arr, floating=True)` and `arrayview file.npy --floating` open in a floating window per-call regardless of global setting; remote/tunnel display uses the same forwarded HTTP/WebSocket path as local VS Code; floating mode uses a single persistent shell hub panel (`_shell.html`) so all arrays share one floating window as tabs instead of opening separate windows; second CLI calls inject tabs via `new_tab` postMessage relay (extension -> hub wrapper -> shell iframe)
+- Directory collections are header-scanned and lazy by default: compatible files form a dense virtual stack, mixed shapes use a ragged collection, and `--load lazy|eager` plus `--stack-policy auto|dense|ragged` make both choices explicit. Supported 3D `.nii.gz` stacks now return the requested axial plane while the same one-pass decode finishes in the byte-bounded LRU cache; unsupported layouts fall back safely. Patient changes show a centered loading card until the matching frame arrives. `view_dir()` exposes the same collection controls.
+- VS Code extension v0.14.43 — exact tunnel-window recovery from the terminal IPC hook, atomic cross-window request claims, non-loopback tunnel URL enforcement, queued concurrent requests, remote-only tunnel claims, live opener-version ACKs, first-frame readiness, and immediate local-backend session release. Successful port-public promotion is cached per external tunnel URL, and existing-server tunnel loads overlap port setup with pending background data loading.
 - Colorbar refactor: `ColorBar` JS class partially migrated (in progress)
 - Colormap picker: `c` opens an expanded colorbar-island grid without changing the colormap; subsequent `c` taps cycle, hover/hjkl/arrows live-preview, Enter/click commits, Esc cancels, and auto-dismiss pauses while hovered
 - Cold-start loading spinner in VS Code and native shell
@@ -48,9 +48,10 @@ last_updated: 2026-06-30
   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`.
+- Reused file and collection sessions are protected by per-tab leases, including
+  collection overlay sessions. The VS Code opener verifies the local SID before
+  creating a panel and waits for the viewer's first rendered frame 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.
@@ -59,6 +60,10 @@ last_updated: 2026-06-30
 
 ## Recently Completed
 
+- Jupyter inline viewports automatically fit ortho content and restore the
+  normal `height` on exit. `mode_heights` remains available for explicit
+  overrides. Direct, proxied, multi-array, and IJulia inline paths share the
+  same mode-change bridge.
 - ROI keybind changed from `r` to `Shift+R` (`R`); rotate/flip is now `r`, transpose is `t`
 - Crossfade animation added to rotate/transpose transitions
 - `--version` flag and version string in help overlay
@@ -85,6 +90,7 @@ last_updated: 2026-06-30
 
 ## In Progress
 
+- VS Code tunnel opener v0.14.43 is installed on disk and fully covered by focused lifecycle/ACK tests; active 0.14.42 extension hosts still need one window reload before post-change live timing and multi-window verification.
 - Smooth immersive transition — stale scrub geometry handoff is fixed, immersive overlay fade-in is held until after the class switch, shared slim colorbar returns through `drawSlimColorbar()` on reverse, and active scrub suppresses minimap/overflow/drag side effects. Single-pane scrub now targets the actual centered immersive viewport rect instead of a hardcoded corner box, the dimbar stays above the pane during scrub, the shared colorbar sits behind the growing pane, and the phantom extra `av-view-wrap` footprint in normal mode was removed by rebinding `NormalLayout` to the real `#viewer` canvas. Cross-mode parity and deeper reverse-pinch validation still need manual verification.
 - ROI + qMRI integration refinements: floodfill not yet supported on qMRI panes; per-pane stats are re-fetched on each ROI draw but not updated on slice scroll
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: arrayview
-Version: 0.31.2
+Version: 0.32.0
 Summary: Fast multi-dimensional array viewer
 Project-URL: Home, https://github.com/oscarvanderheide/arrayview
 Project-URL: Source, https://github.com/oscarvanderheide/arrayview
@@ -51,7 +51,10 @@ Curious? Give it a try with
 uvx arrayview your_array.npy
 ```
 
+Press `v` for the three-plane ortho view. `Shift+3` replaces the current slice,
+or all three ortho panes, with interactive 3D cutaway renders.
+
 
 Check the [docs](https://oscarvanderheide.github.io/arrayview/) to learn more. 
 
-**Warning**: Arrayview is still under active development. Things may break or change without warning.
+**Warning**: Arrayview is still under active development. Things may break or change without warning.

{arrayview-0.31.2 → arrayview-0.32.0}/README.md

@@ -15,7 +15,10 @@ Curious? Give it a try with
 uvx arrayview your_array.npy
 ```
 
+Press `v` for the three-plane ortho view. `Shift+3` replaces the current slice,
+or all three ortho panes, with interactive 3D cutaway renders.
+
 
 Check the [docs](https://oscarvanderheide.github.io/arrayview/) to learn more. 
 
-**Warning**: Arrayview is still under active development. Things may break or change without warning.
+**Warning**: Arrayview is still under active development. Things may break or change without warning.

{arrayview-0.31.2 → arrayview-0.32.0}/docs/index.md

@@ -30,6 +30,8 @@ MATLAB and Julia setup: [MATLAB and Julia](foreign-hosts.md).
 
 Remote and tunnel setup: [Remote](remote.md).
 
+Stacked patient collections and masks: [Stack and Overlay Collections](stack-overlays.md).
+
 ## Formats
 
 `.npy` `.npz` `.nii` `.nii.gz` `.zarr` `.pt` `.h5` `.tif` `.mat`

{arrayview-0.31.2 → arrayview-0.32.0}/docs/loading.md

@@ -54,6 +54,8 @@ Key parameters:
 | `name` | str | Label shown in the viewer tab |
 | `port` | int | Server port (default 8123 for Python API, 8000 for CLI) |
 | `window` | str \| None | How to open the viewer (see below) |
+| `height` | int | Default inline notebook height in pixels |
+| `mode_heights` | dict | Inline height overrides, e.g. `{"ortho": 360, "qmri": 480}` |
 | `rgb` | bool | Treat last/first axis as RGB/RGBA channels |
 | `overlay` | array or list | Arrays composited as overlays |
 
@@ -67,6 +69,9 @@ Key parameters:
 | `"vscode"` | VS Code tab |
 | `"inline"` | Inline IFrame (Jupyter / VS Code notebook) |
 
+Inline ortho view automatically removes unused height. `mode_heights` is only
+needed to override the automatic size.
+
 ## File Picker
 
 `Cmd/Ctrl+O` or `P` opens the file picker.
@@ -85,7 +90,7 @@ 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"
+uvx arrayview volume.nii.gz --overlay "ground truth=mask_gt.nii.gz" --overlay "prediction=mask_pred.nii.gz"
 ```
 
 An unnamed overlay uses the filename stem as its display name (`mask` above).
@@ -99,8 +104,7 @@ shows all overlays at once.
 
 ## Directory Pattern Collections
 
-Use `--stack` when reviewing many arrays. Passing a directory scans supported
-files recursively; passing patterns keeps the aligned channel/overlay workflow.
+Use `--stack` when reviewing many arrays.
 
 ```bash
 uvx arrayview --stack scans/
@@ -115,53 +119,14 @@ dense` requires matching shapes, while `--stack-policy ragged` forces collection
 semantics. `--load eager` is intended for small datasets that should be loaded
 up front.
 
-Positional patterns become a channel/modality axis:
-
-```bash
-uvx arrayview --stack "data/**/*_0000.nii.gz" "data/**/*_0001.nii.gz"
-```
-
-Overlays become named recursive patterns:
+Pattern collections, named overlays, multiple overlays, and `--overlay-dir`:
+[Stack and Overlay Collections](stack-overlays.md).
 
-```bash
-uvx arrayview --stack \
-  "data/**/*_0000.nii.gz" \
-  "data/**/*_0001.nii.gz" \
-  --overlay "gt=data/**/labels/**/*.nii.gz" \
-  --overlay "pred=data/**/pred/**/*.nii.gz"
-```
+## NIfTI Series
 
-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.
-
-```bash
-uvx arrayview --stack "data/**/*_0000.nii.gz" --overlay "gt=data/**/labels/*.nii.gz" --dry-run
-```
-
-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]+)"
-```
-
-## NIfTI Series (4D/5D from a directory)
-
-Stack a directory of NIfTI files into a single lazy 4D/5D array — only the
-viewed slice is loaded, so RAM stays bounded regardless of series size.
+Stack a directory of NIfTI files into a single lazy 4D/5D array. Patient files
+are loaded only when needed, and the memory cache stays bounded regardless of
+series size.
 
 ```bash
 uvx arrayview patients/
@@ -173,27 +138,32 @@ Discovers `.nii`/`.nii.gz` recursively, groups by immediate parent folder
 One file per patient → 4D `(*vol, P)`. The viewer opens with X/Y on screen,
 Z as primary scroll, patient index as a slider.
 
-Multiple files per patient (e.g. `t1`, `t2`, `flair`) → use `--select`:
+For multiple files per patient, use explicit `--stack` patterns:
 
 ```bash
-uvx arrayview patients/ --select '*t1*' --select '*t2*' --select '*flair*'
+uvx arrayview --stack \
+  "patients/*/*t1*.nii.gz" \
+  "patients/*/*t2*.nii.gz" \
+  "patients/*/*flair*.nii.gz"
 ```
 
-Each `--select` pattern picks one file per patient (fnmatch on basename).
-Produces 5D `(*vol, P, M)` with modality as the last axis. Every patient
-must match exactly one file per pattern.
+More examples: [Stack and Overlay Collections](stack-overlays.md).
 
-Python API:
+Patient folders with no NIfTI files (e.g. only `.dcm`) raise an error —
+convert DICOM to NIfTI first (e.g. `dcm2niix`).
 
-```python
-from arrayview import view_dir
+### First image from compressed patients
 
-view_dir("patients/")
-view_dir("patients/", select=["*t1*", "*t2*", "*flair*"])
-```
+For a normal 3D `.nii.gz` patient, ArrayView shows the requested axial slice as
+soon as that slice has been unpacked. It keeps unpacking the rest of the same
+file in the background and saves the completed volume in the existing memory
+cache. The file is not unpacked a second time.
 
-Patient folders with no NIfTI files (e.g. only `.dcm`) raise an error —
-convert DICOM to NIfTI first (e.g. `dcm2niix`).
+This shortens the visible wait, but it does not make gzip random-access. A slice
+near the middle still requires reading roughly the first half of the file.
+Side views, 4D files, and unusual orientations fall back to loading the complete
+volume first so their data remains correct. Moving quickly between patients
+stops outdated background work instead of building a long loading queue.
 
 ## Zarr
 

arrayview-0.32.0/docs/stack-overlays.md

@@ -0,0 +1,129 @@
+# Stack and Overlay Collections
+
+Review many arrays with aligned image and mask patterns.
+
+## Patient Stack
+
+```bash
+uvx arrayview --stack "data/*/T1w.nii.gz"
+```
+
+`*` matches one path segment. `**` matches recursively:
+
+```bash
+uvx arrayview --stack "data/**/*.nii.gz"
+```
+
+ArrayView sorts matches and adds a collection index dimension. Use `--dry-run`
+to inspect pairings without opening the viewer:
+
+```bash
+uvx arrayview --stack "data/*/T1w.nii.gz" --dry-run
+```
+
+## MR Contrasts
+
+```bash
+uvx arrayview --stack \
+  "data/*/T1w.nii.gz" \
+  "data/*/T2w.nii.gz" \
+  "data/*/FLAIR.nii.gz"
+```
+
+Each positional pattern becomes a contrast dimension. The first `T1w`, first
+`T2w`, and first `FLAIR` belong to patient 1; the second match from each pattern
+belongs to patient 2.
+
+For ambiguous layouts, define the patient key:
+
+```bash
+uvx arrayview --stack "data/**/*.nii.gz" \
+  --case-regex "(?P<case>sub-[0-9]+)"
+```
+
+## Ragged Shapes
+
+```bash
+uvx arrayview --stack "data/*/T1w.nii.gz" --stack-policy ragged
+```
+
+`--stack-policy auto` uses a dense stack when shapes match and ragged mode when
+they do not. `--stack-policy dense` requires matching shapes.
+
+## One Overlay
+
+```bash
+uvx arrayview --stack "data/*/T1w.nii.gz" \
+  --overlay "lesion=data/*/masks/lesion.nii.gz"
+```
+
+Use `name=pattern` to control the overlay label. Without `name=`, the filename
+stem is used.
+
+## Multiple Overlays
+
+```bash
+uvx arrayview --stack "data/*/T1w.nii.gz" \
+  --overlay "gt=data/*/masks/gt.nii.gz" \
+  --overlay "pred=data/*/masks/pred.nii.gz"
+```
+
+Overlays are paired to cases by sorted match order unless `--case-regex` is
+provided.
+
+## Overlay Directories
+
+```bash
+uvx arrayview --stack "data/*/T1w.nii.gz" \
+  --overlay-dir "data/*/masks"
+```
+
+`--overlay-dir` creates one overlay role per mask filename inside each matched
+directory. Missing masks are shown as empty overlays.
+
+Repeat it to combine mask folders:
+
+```bash
+uvx arrayview --stack "data/*/T1w.nii.gz" \
+  --overlay-dir "data/*/manual_masks" \
+  --overlay-dir "data/*/model_masks"
+```
+
+## Complete Example
+
+```text
+data/
+  sub-001/
+    anat/T1w.nii.gz
+    anat/T2w.nii.gz
+    masks/lesion.nii.gz
+    masks/edema.nii.gz
+  sub-002/
+    anat/T1w.nii.gz
+    anat/T2w.nii.gz
+    masks/lesion.nii.gz
+```
+
+```bash
+uvx arrayview --stack \
+  "data/*/anat/T1w.nii.gz" \
+  "data/*/anat/T2w.nii.gz" \
+  --overlay-dir "data/*/masks" \
+  --stack-policy auto \
+  --dry-run
+```
+
+Remove `--dry-run` to open the viewer.
+
+## Compressed NIfTI Performance
+
+`.nii.gz` files are lazy through nibabel, but gzip compression limits random
+slice access. Large compressed collections can feel slower when scrolling across
+many patients or contrasts.
+
+For repeated review, prefer uncompressed `.nii`, chunked `.zarr`, or a local
+fast disk cache. Use `--load eager` only for small collections that fit in RAM:
+
+```bash
+uvx arrayview --stack "data/*/T1w.nii.gz" --load eager
+```

{arrayview-0.31.2 → arrayview-0.32.0}/mkdocs.yml

@@ -24,6 +24,7 @@ extra_css:
 nav:
   - Home: index.md
   - Loading Arrays: loading.md
+  - Stack and Overlays: stack-overlays.md
   - Viewing: viewing.md
   - Comparing: comparing.md
   - Display: display.md

{arrayview-0.31.2 → arrayview-0.32.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "arrayview"
-version = "0.31.2"
+version = "0.32.0"
 description = "Fast multi-dimensional array viewer"
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.12"

{arrayview-0.31.2 → arrayview-0.32.0}/src/arrayview/__init__.py

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