arrayview 0.10.1__tar.gz → 0.12.0__tar.gz

{arrayview-0.10.1 → arrayview-0.12.0}/AGENTS.md

@@ -2,6 +2,9 @@ Read `src/arrayview/ARCHITECTURE.md` for codebase orientation.
 
 # ArrayView
 
+I haven't written or read a single line of code in src so when you ask me questions/input,
+keep it simple with some simple examples.
+
 ## Skills
 
 Load the relevant skill before touching the corresponding area.
@@ -24,6 +27,7 @@ Load the relevant skill before touching the corresponding area.
 - For visual/animation features, propose 2-3 options BEFORE implementing
 - UI visibility changes go through reconcilers (`_reconcileUI`/`_reconcileLayout`/`_reconcileCompareState`/`_reconcileCbVisibility`), not inline `style.display` or `classList` toggles in mode functions
 - All colorbar state (animation, window/level, hover, drag) flows through `primaryCb` ColorBar instance — never read/write legacy globals. Multiview colorbars sync via `primaryCb`.
+- Keybinds flow through the command registry (`commands` / `keybinds` in `_viewer.html`), not inline keydown branches. The help overlay auto-generates from command `title` fields — do not hand-edit it.
 
 ## Execution
 
@@ -32,9 +36,11 @@ Always use **subagent-driven development** for implementation. Commit completed
 ## Testing
 
 ```bash
-uv run pytest tests/test_api.py -v       # HTTP API
-uv run pytest tests/test_browser.py -v   # Playwright
-uv run python tests/visual_smoke.py      # screenshots
+uv run pytest tests/test_api.py -v                    # HTTP API
+uv run pytest tests/test_browser.py -v                # Playwright
+uv run pytest tests/test_mode_roundtrip.py -v         # mode state round-trip
+uv run pytest tests/test_command_reachability.py -v   # command when-clause matrix
+uv run python tests/visual_smoke.py                   # screenshots
 ```
 
 After any UI change, use `/ui-consistency-audit` to verify across all modes.

arrayview-0.12.0/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.4
+Name: arrayview
+Version: 0.12.0
+Summary: Fast multi-dimensional array viewer
+Project-URL: Home, https://github.com/oscarvanderheide/arrayview
+Project-URL: Source, https://github.com/oscarvanderheide/arrayview
+Author-email: Oscar <oscarvanderheide@example.com>
+License: MIT
+License-File: LICENSE
+Keywords: array,mri,npy,viewer,visualization
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.12
+Requires-Dist: fastapi>=0.129.0
+Requires-Dist: h5py>=3.0
+Requires-Dist: matplotlib>=3.9.0
+Requires-Dist: nibabel>=5.3.3
+Requires-Dist: numpy>=2.4.2
+Requires-Dist: pillow>=12.1.1
+Requires-Dist: pyqt5>=5.15; sys_platform == 'linux'
+Requires-Dist: pyqtwebengine>=5.15; sys_platform == 'linux'
+Requires-Dist: python-multipart>=0.0.22
+Requires-Dist: pywebview>=6.1
+Requires-Dist: qmricolors>=0.1.2
+Requires-Dist: qtpy>=2.0; sys_platform == 'linux'
+Requires-Dist: scipy>=1.10
+Requires-Dist: tifffile>=2023.1.1
+Requires-Dist: uvicorn>=0.41.0
+Requires-Dist: websockets>=14.0
+Requires-Dist: zarr>=2.17
+Description-Content-Type: text/markdown
+
+# <img src="docs/logo.png" height="36"> arrayview
+
+This is what looking at arrays should feel like.
+
+Load up `.npy`, `.nii`, `.h5`, `.mat` and friends. Works locally, in Jupyter, over SSH and VS Code tunnels. Press `?` once you're in.
+
+## CLI
+
+```bash
+uvx arrayview your_array.npy
+```
+
+## Python
+
+```bash
+uv add arrayview
+```
+
+```python
+from arrayview import view
+view(arr)
+```
+
+[docs →](https://oscarvanderheide.github.io/arrayview/)
+

arrayview-0.12.0/README.md

@@ -0,0 +1,25 @@
+# <img src="docs/logo.png" height="36"> arrayview
+
+This is what looking at arrays should feel like.
+
+Load up `.npy`, `.nii`, `.h5`, `.mat` and friends. Works locally, in Jupyter, over SSH and VS Code tunnels. Press `?` once you're in.
+
+## CLI
+
+```bash
+uvx arrayview your_array.npy
+```
+
+## Python
+
+```bash
+uv add arrayview
+```
+
+```python
+from arrayview import view
+view(arr)
+```
+
+[docs →](https://oscarvanderheide.github.io/arrayview/)
+

{arrayview-0.10.1 → arrayview-0.12.0}/pyproject.toml

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

{arrayview-0.10.1 → arrayview-0.12.0}/src/arrayview/ARCHITECTURE.md

@@ -52,7 +52,7 @@ Detection logic lives in `_platform.py`. Display opening logic lives in `_launch
 | `_stdio_server.py` | 791 | Stdio transport for VS Code direct webview — JSON stdin, binary stdout |
 | `_torch.py` | 217 | PyTorch integration: `view_batch()`, `TrainingMonitor` (lazy torch import) |
 | `_vscode.py` | 1014 | VS Code extension install/management, signal-file IPC, shared-memory IPC, browser opening |
-| `_viewer.html` | 14480 | **The entire frontend** — CSS + JS in a single file, all viewing modes |
+| `_viewer.html` | 15600 | **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 |
 
 ## Frontend (_viewer.html)
@@ -89,7 +89,7 @@ The frontend is a single self-contained HTML file (~15k lines). No build step, n
 | Rendering Pipeline | `updateView()`, play/animate, screenshot capture |
 | ROI and Selection Modes | Rectangle/ellipse ROI drawing, statistics computation |
 | nnInteractive Segmentation | Click-to-segment UI, mask overlay, undo stack |
-| Keyboard Shortcuts | All hotkey bindings — single master switch/case block |
+| Keyboard Shortcuts | Command registry (`commands` / `keybinds` / `makeContext` / `evalWhen` / `dispatchCommand`) + `/`-triggered command palette. Keydown handler is a thin dispatcher prefix |
 | Mode Transitions | Compare/multiview/qMRI enter/exit, crosshair animation |
 | Scroll, Zoom, and Pan | Mouse wheel slice scroll, pinch zoom, scroll-to-zoom |
 | Immersive Mode, Cross-Fade, and Visual Effects | Zen mode, fullscreen (K), animated transitions |
@@ -136,6 +136,9 @@ Pill-shaped badges below the canvas showing active visualization transforms. **C
 ### Dynamic Islands
 Floating UI panels that appear/disappear based on context: ROI statistics, segmentation controls, colorbar hover, dimension sliders. Must be tested across all viewing modes (normal, immersive, multiview, compare).
 
+### Command Registry
+All keybinds flow through a VS Code-style command registry in `_viewer.html`. Three tables: `commands` (id → `{title, when, run}`), `keybinds` (key+modifiers → command id), and `makeContext(state)` (mode/state flag bag). `dispatchCommand(e)` is wired as a prefix to the keydown handler; on a match it evaluates `when` against the context and runs the command, otherwise falls through. The help overlay is auto-generated from command `title` fields — never hand-edit it. A `/`-triggered command palette fuzzy-searches all commands. Cross-mode enablement is guarded by `tests/test_command_reachability.py`.
+
 ### Reconcilers
 Functions in the "UI Validation and Reconciliation" section (~line 13666) that enforce consistent UI state. When mode changes happen, reconcilers update visibility of containers, colorbars, dynamic islands, and compare sub-mode UI. There are four:
 1. **Unified UI reconciler** — master state enforcer
@@ -156,6 +159,9 @@ A dedicated daemon thread (`_session.py`) runs all CPU-heavy rendering off the a
 ### Dynamic Islands
 Must verify island positioning and visibility across normal, immersive, multiview, and compare modes. Islands use absolute/fixed positioning that breaks if parent containers change.
 
+### Keybind Changes
+Keybinds live in the `commands` + `keybinds` tables, not in the keydown handler. Adding or changing a keybind means editing those tables and (if needed) extending `makeContext` / `evalWhen`. The help overlay regenerates itself from command `title` fields — do not edit overlay HTML directly.
+
 ### Layout Debugging
 When debugging layout issues: identify the root cause (which scale function, which reconciler, which CSS rule) before applying fixes. Symptoms in one mode often originate from shared code affecting all modes.
 

{arrayview-0.10.1 → arrayview-0.12.0}/src/arrayview/_config.py

@@ -41,6 +41,21 @@ def get_viewer_colormaps() -> list[str] | None:
     return None
 
 
+_VALID_THEMES = {"dark", "light", "solarized", "nord"}
+
+
+def get_viewer_theme() -> str | None:
+    """Return user-configured default theme name, or None if not configured."""
+    cfg = load_config()
+    viewer_cfg = cfg.get("viewer", {})
+    if not isinstance(viewer_cfg, dict):
+        return None
+    theme = viewer_cfg.get("theme")
+    if isinstance(theme, str) and theme.strip().lower() in _VALID_THEMES:
+        return theme.strip().lower()
+    return None
+
+
 def get_nninteractive_url() -> str | None:
     """Return configured nnInteractive server URL, or None.
 

{arrayview-0.10.1 → arrayview-0.12.0}/src/arrayview/_io.py

@@ -124,6 +124,71 @@ def _select_npz_array(npz, filepath):
         print(f"  Please enter a number between 1 and {len(entries)}.")
 
 
+def _load_nifti_with_meta(filepath):
+    """Load a NIfTI file, canonical-reorient, return (array, meta).
+
+    meta is a dict with keys:
+      affine            : original 4x4 affine (RAS+ mm)
+      affine_canonical  : 4x4 affine after as_closest_canonical
+      voxel_sizes       : tuple (sx, sy, sz) in mm, post-reorient
+      axis_labels       : tuple of 3 strs from {"R","L","A","P","S","I"}
+                          — positive direction of each canonical axis
+      is_oblique        : bool — True if rotation part has off-diagonal magnitude > 1e-3
+                          after normalizing voxel sizes
+    """
+    nib = _nib()
+    img = nib.load(filepath)
+    original_affine = np.asarray(img.affine, dtype=np.float64)
+    canon = nib.as_closest_canonical(img)
+    affine_canonical = np.asarray(canon.affine, dtype=np.float64)
+
+    # NOTE: reorient requires materializing axis permutes/flips. .nii.gz is
+    # already eager (gzip not seekable), so this is free; .nii loses mmap as a
+    # necessary cost to apply the reorient.
+    arr = np.asarray(canon.dataobj)
+
+    rot = affine_canonical[:3, :3]
+    voxel_sizes = tuple(float(np.linalg.norm(rot[:, i])) for i in range(3))
+
+    # Direction of each canonical axis (sign of diagonal after normalizing)
+    norm_rot = np.zeros((3, 3))
+    for i in range(3):
+        if voxel_sizes[i] > 0:
+            norm_rot[:, i] = rot[:, i] / voxel_sizes[i]
+    pos_labels = ("R", "A", "S")
+    neg_labels = ("L", "P", "I")
+    axis_labels = tuple(
+        pos_labels[i] if norm_rot[i, i] >= 0 else neg_labels[i] for i in range(3)
+    )
+
+    # Oblique = off-diagonal of normalized rotation has |val| > tol
+    off_diag_max = 0.0
+    for i in range(3):
+        for j in range(3):
+            if i != j:
+                off_diag_max = max(off_diag_max, abs(norm_rot[i, j]))
+    is_oblique = bool(off_diag_max > 1e-3)
+
+    meta = {
+        "affine": original_affine,
+        "affine_canonical": affine_canonical,
+        "voxel_sizes": voxel_sizes,
+        "axis_labels": axis_labels,
+        "is_oblique": is_oblique,
+    }
+    return arr, meta
+
+
+def load_data_with_meta(filepath):
+    """Like load_data but also returns spatial metadata for NIfTI files.
+
+    Returns (array, meta_or_None). meta is None for non-NIfTI formats.
+    """
+    if filepath.endswith(".nii") or filepath.endswith(".nii.gz"):
+        return _load_nifti_with_meta(filepath)
+    return load_data(filepath), None
+
+
 def load_data(filepath):
     if filepath.endswith(".npy"):
         return np.load(filepath, mmap_mode="r")
@@ -133,7 +198,13 @@ def load_data(filepath):
         if len(keys) == 1:
             return npz[keys[0]]
         return _select_npz_array(npz, filepath)
-    elif filepath.endswith(".nii") or filepath.endswith(".nii.gz"):
+    elif filepath.endswith(".nii.gz"):
+        # Gzip streams aren't seekable, so nibabel's lazy dataobj decompresses
+        # large portions of the file on every arbitrary slice access. Materialize
+        # the volume up front so subsequent slicing is cheap.
+        return np.asarray(_nib().load(filepath).dataobj)
+    elif filepath.endswith(".nii"):
+        # Uncompressed NIfTI is memory-mapped via dataobj — slicing is cheap.
         return _nib().load(filepath).dataobj
     elif filepath.endswith(".zarr") or filepath.endswith(".zarr.zip"):
         import zarr

{arrayview-0.10.1 → arrayview-0.12.0}/src/arrayview/_launcher.py

@@ -1654,10 +1654,10 @@ def _serve_daemon(
     ).start()
 
     def _load():
-        from arrayview._io import load_data
+        from arrayview._io import load_data, load_data_with_meta
 
         try:
-            data = load_data(filepath)
+            data, spatial_meta = load_data_with_meta(filepath)
             if cleanup:
                 try:
                     os.unlink(filepath)
@@ -1667,6 +1667,9 @@ def _serve_daemon(
                 data, filepath=None if cleanup else filepath, name=name
             )
             session.sid = sid
+            session.spatial_meta = spatial_meta
+            if spatial_meta is not None:
+                session.original_volume = data
             if rgb:
                 from arrayview._render import _setup_rgb
 

{arrayview-0.10.1 → arrayview-0.12.0}/src/arrayview/_render.py

@@ -111,7 +111,10 @@ def _compute_vmin_vmax(session, data, dr=0, complex_mode=0):
 
 
 def extract_slice(session, dim_x, dim_y, idx_list):
-    key = (dim_x, dim_y, tuple(idx_list))
+    # Mask out indices along the displayed dims — they're slice(None) in the
+    # slicer below, so the extracted data doesn't depend on them.
+    key_idx = tuple(None if i in (dim_x, dim_y) else idx_list[i] for i in range(len(idx_list)))
+    key = (dim_x, dim_y, key_idx)
     if key in session.raw_cache:
         session.raw_cache.move_to_end(key)
         return session.raw_cache[key]
@@ -154,7 +157,12 @@ def extract_projection(session, dim_x, dim_y, idx_list, proj_dim, proj_mode):
 
     proj_mode: 1=max, 2=min, 3=mean, 4=std, 5=sos (sum of squares)
     """
-    key = ("proj", dim_x, dim_y, tuple(idx_list), proj_dim, proj_mode)
+    # Mask out indices along the displayed/projected dims — they're slice(None).
+    key_idx = tuple(
+        None if i in (dim_x, dim_y, proj_dim) else idx_list[i]
+        for i in range(len(idx_list))
+    )
+    key = ("proj", dim_x, dim_y, key_idx, proj_dim, proj_mode)
     if key in session.raw_cache:
         session.raw_cache.move_to_end(key)
         return session.raw_cache[key]
@@ -659,10 +667,12 @@ def render_mosaic(
     complex_mode=0,
     log_scale=False,
     mosaic_cols=None,
+    vmin_override=None,
+    vmax_override=None,
 ):
     idx_norm = list(idx_tuple)
     idx_norm[dim_z] = 0
-    key = (dim_x, dim_y, dim_z, tuple(idx_norm), colormap, dr, complex_mode, log_scale, mosaic_cols)
+    key = (dim_x, dim_y, dim_z, tuple(idx_norm), colormap, dr, complex_mode, log_scale, mosaic_cols, vmin_override, vmax_override)
     if key in session.mosaic_cache:
         session.mosaic_cache.move_to_end(key)
         return session.mosaic_cache[key]
@@ -682,7 +692,9 @@ def render_mosaic(
         frames = [np.log1p(np.abs(f)).astype(np.float32) for f in frames]
     all_data = np.stack(frames)
 
-    if complex_mode == 1 and np.iscomplexobj(session.data):
+    if vmin_override is not None and vmax_override is not None:
+        vmin, vmax = float(vmin_override), float(vmax_override)
+    elif complex_mode == 1 and np.iscomplexobj(session.data):
         vmin, vmax = -float(np.pi), float(np.pi)
     else:
         vmin = float(np.percentile(all_data, 1))