arrayview 0.11.0__tar.gz → 0.12.1__tar.gz

{arrayview-0.11.0 → arrayview-0.12.1}/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,13 @@ 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.
+
+## Contributing
+
+Before creating a PR or making user-facing changes, read `CONTRIBUTING.md`. It defines the design
+language, keybinding conventions, overlay/popup patterns, and testing requirements. All PRs that
+touch the viewer must follow it.
 
 ## Execution
 
@@ -32,9 +42,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.1/CONTRIBUTING.md

@@ -0,0 +1,93 @@
+# Contributing to arrayview
+
+Thanks for your interest. This guide keeps things consistent as more people
+contribute.
+
+## Proposing changes
+
+For anything user-facing (new shortcut, overlay, layout change), **open an
+issue first**. Include:
+
+- What it does, in one sentence
+- Which key triggers it (if any)
+- Which modes it affects (Normal, Multi-view, Compare, Diff, Registration, qMRI)
+- A rough sketch or description of how it looks
+
+Bug fixes and internal refactors can go straight to a PR.
+
+## Design principles
+
+1. **Array fills the screen.** Minimize chrome. UI elements stay hidden or
+   dimmed until the user hovers or presses a key, then fade back out.
+
+2. **Monospace only.** All text uses the system monospace stack
+   (`'SF Mono', ui-monospace, 'Cascadia Code', 'JetBrains Mono', monospace`).
+   Never use sans-serif.
+
+3. **Colors via CSS custom properties.** Use `var(--surface)`, `var(--text)`,
+   `var(--active-dim)`, etc. Never hardcode hex values. The viewer ships four
+   themes (dark, light, solarized, nord) and all must work.
+
+4. **Yellow for active state.** `--active-dim` (#f5c842 in dark theme) marks
+   the currently active element. Don't introduce new accent colors.
+
+5. **All six modes.** Every visual feature must be tested across Normal,
+   Multi-view (V/v), Compare (B/P), Diff (X), Registration (R), and qMRI (q).
+   If your feature only applies to some modes, add explicit mode guards.
+
+## Keyboard shortcuts
+
+- Check the existing shortcut table (press `?` in the viewer) before picking a
+  key. Conflicts will be caught in review but save yourself the round-trip.
+- Single lowercase letters are scarce. Prefer Shift+key or a modifier for new
+  features.
+- If a shortcut only makes sense in certain modes, guard it:
+  ```js
+  if (currentMode !== 'compare') return;
+  ```
+- Document the new shortcut in the help overlay (`#help-overlay` in
+  `_viewer.html`).
+
+## Popup menus and overlays
+
+Several proposals involve popup/context menus. To keep them visually
+consistent:
+
+- Background: `var(--surface)`, border: `1px solid var(--border)`,
+  border-radius: `var(--radius-lg)`.
+- Dismiss on **Escape** and on clicking outside the popup.
+- No permanent visibility -- show on trigger, hide when done.
+- Keep text small (12-13px) and monospace.
+- Use `var(--active-dim)` for the selected/hovered item, `var(--text)` for
+  normal items, `var(--muted)` for secondary info.
+- Animate in with a short opacity+scale transition, not an instant pop.
+
+Look at `#uni-picker-box` in `_viewer.html` for a reference implementation.
+
+## Testing checklist
+
+Before submitting a PR:
+
+- [ ] `uv run pytest tests/test_api.py -x` passes
+- [ ] `uv run python tests/visual_smoke.py` passes
+- [ ] If you added UI, update `tests/visual_smoke.py` to cover it
+- [ ] Manually verify in all affected modes (at minimum: Normal + one
+      multi-pane mode)
+- [ ] New shortcuts are documented in the help overlay
+
+## Dev setup
+
+```bash
+git clone <repo-url>
+cd arrayview
+uv sync
+uv run arrayview tests/  # launch with test data
+```
+
+## Style notes
+
+- The frontend lives in a single file: `src/arrayview/_viewer.html`.
+  HTML, CSS, and JS are all in there. Keep it that way.
+- Python backend uses `uv` for package management.
+- Commit messages follow conventional commits (`feat:`, `fix:`, `refactor:`,
+  etc.).

arrayview-0.12.1/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.4
+Name: arrayview
+Version: 0.12.1
+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.1/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.11.0 → arrayview-0.12.1}/pyproject.toml

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

arrayview-0.12.1/scripts/release.sh

@@ -0,0 +1,138 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# ---------------------------------------------------------------------------
+# release.sh — bump version, commit, tag, push, create GitHub release
+# ---------------------------------------------------------------------------
+
+BUMP="minor"
+DRY_RUN=true
+NO_AI=false
+
+usage() {
+    cat <<EOF
+Usage: $(basename "$0") [OPTIONS]
+
+Options:
+  --bump {major,minor,patch}   Version bump type (default: minor)
+  --execute                    Actually run (default is dry-run)
+  --no-ai                      Skip AI release notes, use GitHub's --generate-notes
+  -h, --help                   Show this help
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --bump)   BUMP="$2"; shift 2 ;;
+        --execute) DRY_RUN=false; shift ;;
+        --no-ai)  NO_AI=true; shift ;;
+        -h|--help) usage; exit 0 ;;
+        *) echo "Unknown option: $1"; usage; exit 1 ;;
+    esac
+done
+
+if [[ ! "$BUMP" =~ ^(major|minor|patch)$ ]]; then
+    echo "Error: --bump must be major, minor, or patch (got '$BUMP')"
+    exit 1
+fi
+
+# --- Guard: clean working tree on main ---
+branch=$(git rev-parse --abbrev-ref HEAD)
+if [[ "$branch" != "main" ]]; then
+    echo "Error: must be on main (currently on '$branch')"
+    exit 1
+fi
+
+if ! git diff --quiet || ! git diff --cached --quiet; then
+    echo "Error: working tree is dirty — commit or stash first"
+    exit 1
+fi
+
+# --- Bump version ---
+uv version --bump "$BUMP"
+VERSION=$(uv version --short)
+TAG="v${VERSION}"
+
+echo "Version bumped to $VERSION (tag: $TAG)"
+
+uv lock --quiet
+
+run() {
+    echo "+ $*"
+    if [[ "$DRY_RUN" == true ]]; then
+        return
+    fi
+    "$@"
+}
+
+# --- Generate release notes ---
+CLAUDE_BIN="${CLAUDE_BIN:-/Users/oscar/.local/bin/claude}"
+PREV_TAG=$(git describe --tags --abbrev=0 HEAD 2>/dev/null || echo "")
+NOTES=""
+
+if [[ -n "$PREV_TAG" ]]; then
+    COMMITS=$(git log "${PREV_TAG}..HEAD" --oneline)
+else
+    COMMITS=$(git log --oneline -20)
+fi
+
+if [[ "$NO_AI" == false ]] && command -v "$CLAUDE_BIN" &>/dev/null; then
+    echo "Generating release notes with Claude..."
+    NOTES=$("$CLAUDE_BIN" -p "You are writing release notes for arrayview $TAG (a Python array/image viewer).
+
+Here are the commits since the last release ($PREV_TAG):
+
+$COMMITS
+
+Write concise, user-friendly release notes in this exact format:
+
+## What's new in $TAG
+
+- **Feature name**: one-sentence description
+
+Rules:
+- 5-10 bullet points max — group related commits into one bullet
+- Write for end-users, not developers (no commit hashes, no file names)
+- Use past tense (\"added\", \"fixed\", \"improved\")
+- Skip pure refactors/docs unless they affect user experience
+- Bold the feature name, keep the description to one sentence" 2>/dev/null) || true
+fi
+
+if [[ -z "$NOTES" ]]; then
+    if [[ "$NO_AI" == false ]]; then
+        echo "AI notes unavailable, falling back to --generate-notes"
+    fi
+fi
+
+if [[ "$DRY_RUN" == true && -n "$NOTES" ]]; then
+    echo ""
+    echo "--- Release notes preview ---"
+    echo "$NOTES"
+    echo "-----------------------------"
+    echo ""
+fi
+
+# --- Commit, tag, push, release ---
+run git add pyproject.toml uv.lock
+run git commit -m "release: $TAG"
+run git push origin main
+run git tag "$TAG"
+run git push origin "$TAG"
+
+if [[ -n "$NOTES" ]]; then
+    run gh release create "$TAG" \
+        --title "$TAG" \
+        --notes "$NOTES" \
+        --prerelease
+else
+    run gh release create "$TAG" \
+        --title "$TAG" \
+        --generate-notes \
+        --prerelease
+fi
+
+if [[ "$DRY_RUN" == true ]]; then
+    echo ""
+    echo "(dry-run — re-run with --execute to apply)"
+    git checkout pyproject.toml uv.lock
+fi

{arrayview-0.11.0 → arrayview-0.12.1}/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.11.0 → arrayview-0.12.1}/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")

{arrayview-0.11.0 → arrayview-0.12.1}/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.11.0 → arrayview-0.12.1}/src/arrayview/_render.py

@@ -667,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]
@@ -690,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))