arrayview 0.43.3__tar.gz → 0.44.0__tar.gz

{arrayview-0.43.3 → arrayview-0.44.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: arrayview
-Version: 0.43.3
+Version: 0.44.0
 Summary: Fast multi-dimensional array viewer
 Project-URL: Home, https://github.com/oscarvanderheide/arrayview
 Project-URL: Source, https://github.com/oscarvanderheide/arrayview

{arrayview-0.43.3 → arrayview-0.44.0}/pyproject.toml

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

{arrayview-0.43.3 → arrayview-0.44.0}/src/arrayview/_analysis.py

@@ -42,6 +42,11 @@ def _build_metadata(session) -> dict:
             # 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]
+            # NIfTI metadata identifies the first three axes as anatomical.
+            # Later axes may be echoes, parameters, or time points, so they
+            # must not change which anatomical plane opens first.
+            if getattr(session, "spatial_meta", None) is not None:
+                default_shape = default_shape[:3]
     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])]

{arrayview-0.43.3 → arrayview-0.44.0}/src/arrayview/_diff.py

@@ -158,7 +158,10 @@ def _compute_diff(
     b = _resize_normalized_like(b, a)
     if diff_mode == 1:
         raw = a - b
-        vmin, vmax = -1.0, 1.0
+        lo = float(np.nanpercentile(raw, 1))
+        hi = float(np.nanpercentile(raw, 99))
+        vmax = max(abs(lo), abs(hi)) or 1.0
+        vmin = -vmax
         colormap = "RdBu_r"
     elif diff_mode == 2:
         raw = np.abs(a - b)

{arrayview-0.43.3 → arrayview-0.44.0}/src/arrayview/_io.py

@@ -172,7 +172,9 @@ def _nifti_header_with_meta(filepath, *, native=False):
         (abs(norm_rot[i, j]) for i in range(3) for j in range(3) if i != j),
         default=0.0,
     )
-    canonical_shape = tuple(int(img.shape[int(axis)]) for axis in transform[:, 0])
+    canonical_shape = tuple(
+        int(img.shape[int(axis)]) for axis in transform[:, 0]
+    ) + tuple(int(size) for size in img.shape[3:])
     meta = {
         "affine": original_affine,
         "affine_canonical": affine_canonical,

{arrayview-0.43.3 → arrayview-0.44.0}/src/arrayview/_launch_plan.py

@@ -343,22 +343,32 @@ def plan_launch(
         )
 
     environment = facts.environment
+    in_jupyter_kernel = intent.invocation is Invocation.JUPYTER or facts.in_jupyter
     explicit_inline = window == "inline" or (
         intent.inline is True and intent.inline_explicit
     )
-    remote_jupyter = (
-        facts.is_vscode_remote
-        and facts.in_jupyter
-        and intent.inline is not False
-        and not explicit_inline
-    )
-    if remote_jupyter:
-        environment = Environment.VSCODE_REMOTE
-        reasons.append("remote_jupyter_uses_vscode")
-    elif intent.invocation is Invocation.JUPYTER or facts.in_jupyter:
-        environment = Environment.JUPYTER
+    # A VS Code notebook shows the array in the cell, not in a tab. Over a
+    # tunnel the cell's iframe additionally needs the port published, because
+    # its webview runs on the client and cannot reach this host's localhost —
+    # see _inline_url_for_vscode_tunnel and LAUNCH-MATRIX.md row 13. Do not
+    # revert this to the VS Code tab; a black cell means the publish failed,
+    # and the cell now says so.
+    default_inline_ok = in_jupyter_kernel
+    if in_jupyter_kernel:
+        if facts.is_vscode_remote and intent.inline is not False and not explicit_inline:
+            environment = Environment.VSCODE_REMOTE
+        else:
+            environment = Environment.JUPYTER
     elif intent.invocation is Invocation.JULIA or facts.in_julia:
-        environment = Environment.JULIA
+        # A Julia process embedded in a VS Code window (local, remote, or
+        # tunnel) can still target the VS Code tab — only a standalone Julia
+        # process needs the browser-default fallback below.
+        if facts.is_vscode_remote:
+            environment = Environment.VSCODE_REMOTE
+        elif facts.in_vscode_terminal:
+            environment = Environment.VSCODE_LOCAL
+        else:
+            environment = Environment.JULIA
     elif intent.invocation is Invocation.MATLAB and not facts.is_vscode_remote:
         environment = Environment.MATLAB
 
@@ -393,10 +403,10 @@ def plan_launch(
         owner = ServerOwner.EXISTING
         registration = Registration.HTTP_LOAD
         reasons.append("reuse_compatible_server")
-    elif environment is Environment.JULIA:
+    elif intent.invocation is Invocation.JULIA or facts.in_julia:
         owner = ServerOwner.SPAWNED_DAEMON
         registration = Registration.DAEMON_STARTUP
-        reasons.append(f"{environment.value}_requires_subprocess")
+        reasons.append("julia_requires_subprocess")
     elif intent.invocation in {Invocation.CLI, Invocation.VSCODE_EXPLORER}:
         owner = (
             ServerOwner.PERSISTENT
@@ -411,9 +421,10 @@ def plan_launch(
         reasons.append("python_process_owns_session")
 
     display, fallback, fallback_allowed = _display_policy(
-        window=None if remote_jupyter else window,
-        inline=False if remote_jupyter else intent.inline,
+        window=window,
+        inline=intent.inline,
         environment=environment,
+        in_jupyter=default_inline_ok,
         native_available=facts.native_backend is not None,
         in_vscode_tunnel=facts.in_vscode_tunnel,
         reasons=reasons,
@@ -439,6 +450,7 @@ def _display_policy(
     window: str | None,
     inline: bool | None,
     environment: Environment,
+    in_jupyter: bool,
     native_available: bool,
     in_vscode_tunnel: bool,
     reasons: list[str],
@@ -449,11 +461,7 @@ def _display_policy(
     if (
         window == "inline"
         or inline is True
-        or (
-            window is None
-            and inline is None
-            and environment is Environment.JUPYTER
-        )
+        or (window is None and inline is None and in_jupyter)
     ):
         reasons.append("jupyter_inline" if window is None else "explicit_inline")
         return Display.INLINE, None, False

{arrayview-0.43.3 → arrayview-0.44.0}/src/arrayview/_launcher.py

@@ -3031,6 +3031,11 @@ def _should_use_jupyter_proxy_inline() -> bool:
     if forced:
         return forced not in {"0", "false", "no", "off"}
 
+    # Whether the proxy route is *available*, not whether it will be used.
+    # Only the page can decide that — see _build_jupyter_inline_html. Sniffing
+    # the process tree here got it wrong for a Jupyter server started from a
+    # VS Code terminal and opened in an ordinary browser, which looks exactly
+    # like a VS Code notebook kernel from this side.
     global _JUPYTER_PROXY_INLINE_CACHE
     if _JUPYTER_PROXY_INLINE_CACHE is not None:
         return _JUPYTER_PROXY_INLINE_CACHE
@@ -3114,7 +3119,12 @@ def _build_jupyter_inline_html(
   const frame = host.querySelector('iframe');
   if (!frame) return;
   const directSrc = {json.dumps(viewer_url)};
-  const useProxy = {json.dumps(use_proxy)};
+  // The page knows where it is rendering and Python does not. A classic
+  // Jupyter Notebook/Lab page has an http(s) origin for the relative proxy
+  // path to resolve against; a VS Code notebook cell renders in a webview
+  // whose origin is not HTTP at all, so the same path resolves to nothing.
+  const proxyAvailable = {json.dumps(use_proxy)};
+  const useProxy = proxyAvailable && /^https?:$/.test(window.location.protocol);
   const defaultHeight = {height};
   const modeHeights = {_script_json(mode_heights)};
   const modeAliases = {{
@@ -3147,6 +3157,28 @@ def _build_jupyter_inline_html(
     window.removeEventListener('message', onMessage);
     removalObserver.disconnect();
   }};
+  // Nearest ancestor of the host that can actually scroll vertically (JupyterLab
+  // scrolls the notebook pane; classic notebook scrolls the window).
+  const scrollParentOf = (el) => {{
+    let node = el && el.parentElement ? el.parentElement : null;
+    while (node) {{
+      const overflowY = window.getComputedStyle(node).overflowY;
+      const scrollable = overflowY === 'auto' || overflowY === 'scroll' || overflowY === 'overlay';
+      if (scrollable && node.scrollHeight > node.clientHeight) return node;
+      node = node.parentElement;
+    }}
+    return null;
+  }};
+  // WheelEvent deltaMode -> pixel delta: 0 = pixels, 1 = lines (~16px),
+  // 2 = pages (use a large step).
+  const wheelPassthroughPx = (detail) => {{
+    const d = detail || {{}};
+    let deltaY = Number.isFinite(Number(d.deltaY)) ? Number(d.deltaY) : 0;
+    const deltaMode = Number.isFinite(Number(d.deltaMode)) ? Number(d.deltaMode) : 0;
+    if (deltaMode === 1) deltaY *= 16;
+    else if (deltaMode === 2) deltaY *= Math.max(1, window.innerHeight || 600);
+    return deltaY;
+  }};
   const onMessage = (event) => {{
     const msg = event && event.data;
     if (!msg || msg.source !== 'arrayview-viewer') return;
@@ -3158,6 +3190,13 @@ def _build_jupyter_inline_html(
       );
       return;
     }}
+    if (msg.phase === 'wheel-passthrough') {{
+      const deltaY = wheelPassthroughPx(msg.detail);
+      const scroller = scrollParentOf(host);
+      if (scroller) scroller.scrollBy({{ top: deltaY }});
+      else window.scrollBy({{ top: deltaY }});
+      return;
+    }}
   }};
   window.addEventListener('message', onMessage);
   const removalObserver = new MutationObserver(() => {{
@@ -3197,6 +3236,13 @@ def _make_jupyter_proxy_inline_html(
     height: int,
     mode_heights: dict[str, int] | None = None,
 ):
+    # The direct address is the fallback the page uses when its origin cannot
+    # resolve the relative proxy path — which is exactly what a VS Code
+    # notebook cell does — so over a tunnel it has to be one the client can
+    # reach, even though the proxy route is also on offer here.
+    viewer_url, reason = _inline_url_for_vscode_tunnel(viewer_url, port)
+    if reason:
+        return _inline_unreachable_html(reason)
     return _make_jupyter_inline_html(
         viewer_url,
         port,
@@ -3206,6 +3252,75 @@ def _make_jupyter_proxy_inline_html(
     )
 
 
+# One published route per (port, backend) is enough for a whole session: the
+# forward stays up, and re-asking costs a round trip through the extension.
+_INLINE_TUNNEL_ROUTES: dict[tuple[int, str | None], str] = {}
+
+
+def _inline_url_for_vscode_tunnel(
+    viewer_url: str, port: int
+) -> tuple[str, str | None]:
+    """Return ``(url, reason)`` for an inline viewer the notebook cell can load.
+
+    A cell's output renders in a webview on the VS Code client. Over a tunnel
+    that client has nothing on this host's ``localhost``, and it carries no
+    devtunnel cookie, so a private forward answers it with a sign-in redirect
+    and the cell stays black. Publishing the forward is the only address left.
+
+    The viewer tab does not come through here and keeps the private route:
+    VS Code fetches that page itself, on this side.
+    """
+    if not _in_vscode_tunnel():
+        return viewer_url, None
+    from arrayview import _session as _session_mod
+    from arrayview._vscode_signal import _public_tunnel_base
+
+    runtime = _session_mod.SERVER_RUNTIME
+    instance_id = getattr(runtime, "instance_id", None)
+    cache_key = (port, instance_id)
+    base = _INLINE_TUNNEL_ROUTES.get(cache_key)
+    reason = None
+    if base is None:
+        base, reason = _public_tunnel_base(port, instance_id)
+        if base:
+            _INLINE_TUNNEL_ROUTES[cache_key] = base
+    if not base:
+        return viewer_url, reason
+
+    parts = urllib.parse.urlsplit(viewer_url)
+    base_parts = urllib.parse.urlsplit(base)
+    return (
+        urllib.parse.urlunsplit(
+            (
+                base_parts.scheme,
+                base_parts.netloc,
+                parts.path,
+                parts.query,
+                parts.fragment,
+            )
+        ),
+        None,
+    )
+
+
+def _inline_unreachable_html(reason: str):
+    """Say why a cell cannot show the array, instead of rendering black."""
+    import html
+
+    from IPython.display import HTML
+
+    return HTML(
+        '<div style="padding:14px 16px;border-radius:6px;background:#2a1f1f;'
+        'border:1px solid #6b3a3a;color:#e6b8b8;font:13px/1.5 '
+        'ui-monospace,SFMono-Regular,Menlo,monospace">'
+        "<b>ArrayView cannot show this array in the cell.</b><br>"
+        f"{html.escape(reason)}<br>"
+        "<span style=\"color:#c99\">Open it in a tab instead with "
+        "<code>av.view(arr, window=&quot;vscode&quot;)</code>.</span>"
+        "</div>"
+    )
+
+
 def _make_resizable_jupyter_iframe(
     viewer_url: str,
     port: int,
@@ -3216,6 +3331,9 @@ def _make_resizable_jupyter_iframe(
 
     from IPython.display import IFrame
 
+    viewer_url, reason = _inline_url_for_vscode_tunnel(viewer_url, port)
+    if reason:
+        return _inline_unreachable_html(reason)
     iframe = IFrame(src=viewer_url, width="100%", height=height)
 
     def _repr_html_(self):

{arrayview-0.43.3 → arrayview-0.44.0}/src/arrayview/_routes_websocket.py

@@ -14,7 +14,6 @@ from arrayview._render import (
     LUTS,
     _prepare_display,
     _ensure_lut,
-    apply_colormap_rgba,
     extract_projection,
     extract_slice,
     render_mosaic,
@@ -237,6 +236,58 @@ def _render_rgba_from_data(data, colormap, vmin, vmax):
     return lut[(normalized * 255).astype(np.uint8)]
 
 
+def _render_qmri_rgba(
+    session,
+    dim_x,
+    dim_y,
+    idx_tuple,
+    colormap,
+    dr,
+    complex_mode,
+    log_scale,
+    qmri_role,
+    vmin_override=None,
+    vmax_override=None,
+):
+    """Render a qMRI parameter-map slice to RGBA and return (rgba, vmin, vmax).
+
+    Kept separate from the generic path so the slice read and the window
+    computation happen exactly once, and so multi-pane qMRI/ortho renders run in
+    the render thread pool instead of blocking the event loop serially. The
+    colour map is applied with the unadjusted window (matching the previous
+    synchronous path); the returned window is the qMRI-role-adjusted value sent
+    in the frame header.
+    """
+    raw = qmri_display_slice(session, dim_x, dim_y, list(idx_tuple), qmri_role)
+    data, vmin, vmax = _prepare_display(
+        session,
+        raw,
+        complex_mode,
+        dr,
+        log_scale,
+        vmin_override=vmin_override,
+        vmax_override=vmax_override,
+    )
+    if vmax > vmin:
+        normalized = np.clip((data - vmin) / (vmax - vmin), 0, 1)
+    else:
+        normalized = np.zeros_like(data)
+    _ensure_lut(colormap)
+    lut = LUTS.get(colormap, LUTS["gray"])
+    rgba = lut[(normalized * 255).astype(np.uint8)]
+    alpha_on = getattr(session, "alpha_level", 0) > 0
+    if alpha_on:
+        if vmax > vmin:
+            transparent = data < vmin
+        else:
+            transparent = data == np.float32(0)
+        if transparent.any():
+            rgba = rgba.copy()
+            rgba[transparent, 3] = 0
+    vmin, vmax = _qmri_adjust_vmin_vmax(vmin, vmax, qmri_role)
+    return rgba, vmin, vmax
+
+
 async def _notify_shells(sid, name, url=None, wait: bool = True) -> bool:
     """Push a new-tab message to all connected webview shell windows."""
     if wait:
@@ -566,19 +617,23 @@ def register_websocket_routes(app) -> None:
                     )
                 else:
                     if qmri_role:
-                        raw = qmri_display_slice(
-                            session, dim_x, dim_y, list(idx_tuple), qmri_role
-                        )
-                        rgba = apply_colormap_rgba(
-                            session,
-                            raw,
-                            colormap,
-                            dr,
-                            complex_mode,
-                            log_scale,
-                            vmin_override=vmin_override,
-                            vmax_override=vmax_override,
+                        rgba, vmin, vmax = await _render(
+                            loop,
+                            lambda: _render_qmri_rgba(
+                                session,
+                                dim_x,
+                                dim_y,
+                                idx_tuple,
+                                colormap,
+                                dr,
+                                complex_mode,
+                                log_scale,
+                                qmri_role,
+                                vmin_override=vmin_override,
+                                vmax_override=vmax_override,
+                            ),
                         )
+                        h, w = rgba.shape[:2]
                     else:
                         rgba = await _render(
                             loop,
@@ -598,23 +653,17 @@ def register_websocket_routes(app) -> None:
                                 ),
                             ),
                         )
-                    h, w = rgba.shape[:2]
-                    raw = (
-                        qmri_display_slice(session, dim_x, dim_y, list(idx_tuple), qmri_role)
-                        if qmri_role
-                        else extract_slice(session, dim_x, dim_y, list(idx_tuple))
-                    )
-                    _, vmin, vmax = _prepare_display(
-                        session,
-                        raw,
-                        complex_mode,
-                        dr,
-                        log_scale,
-                        vmin_override=vmin_override,
-                        vmax_override=vmax_override,
-                    )
-                    if qmri_role:
-                        vmin, vmax = _qmri_adjust_vmin_vmax(vmin, vmax, qmri_role)
+                        h, w = rgba.shape[:2]
+                        raw = extract_slice(session, dim_x, dim_y, list(idx_tuple))
+                        _, vmin, vmax = _prepare_display(
+                            session,
+                            raw,
+                            complex_mode,
+                            dr,
+                            log_scale,
+                            vmin_override=vmin_override,
+                            vmax_override=vmax_override,
+                        )
 
                     overlay_sid = msg.get("overlay_sid")
                     overlay_colors = msg.get("overlay_colors")

{arrayview-0.43.3 → arrayview-0.44.0}/src/arrayview/_session.py

@@ -505,44 +505,75 @@ def _startup_dims_for_data(data, shape=None) -> tuple[int, int] | None:
     return _viewer_start_dims_for_shape(target_shape)
 
 
+def _nifti_proxy_nbytes(data) -> int:
+    """Estimate the in-RAM size of a nibabel ArrayProxy."""
+    try:
+        return int(np.prod(data.shape)) * np.dtype(data.dtype).itemsize
+    except Exception:
+        return 0
+
+
 def upgrade_memmap_in_background(session) -> bool:
-    """Read a memmap-backed session into RAM behind the viewer.
+    """Read a lazily-backed session array into RAM behind the viewer.
 
-    ``load_data`` hands back a memmap only when the first frame is cheap to
+    ``load_data`` hands back a lazy source — an ``np.memmap`` for .npy, or a
+    nibabel ArrayProxy for uncompressed .nii — when the first frame is cheap to
     fault in, which buys an immediate picture but leaves later orientations
-    paying scattered reads.  The sequential read still has to happen, so run it
-    off the hot path and swap the array in when it lands.
+    (ortho panes, qMRI planes) paying scattered reads.  The sequential read
+    still has to happen, so run it off the hot path and swap the array in when
+    it lands.
 
     Rebinding ``session.data`` is atomic under the GIL and the values are
-    identical, so a render already holding the memmap stays correct and the
+    identical, so a render already holding the lazy array stays correct and the
     slice caches stay valid.
     """
     data = getattr(session, "data", None)
     filepath = getattr(session, "filepath", None)
-    if not isinstance(data, np.memmap) or not filepath:
+    if data is None or not filepath:
         return False
-    if not str(filepath).endswith(".npy"):
+    filepath = str(filepath)
+
+    is_memmap = isinstance(data, np.memmap)
+    is_nifti_proxy = filepath.endswith(".nii") and not isinstance(data, np.ndarray)
+    if not (is_memmap or is_nifti_proxy):
         return False
+
     try:
         from ._io import npy_eager_limit
-
-        if os.path.getsize(filepath) >= npy_eager_limit():
-            return False  # does not fit in RAM — the map is the only option
-    except OSError:
+    except Exception:
         return False
 
+    if is_memmap:
+        if not filepath.endswith(".npy"):
+            return False
+        try:
+            nbytes = os.path.getsize(filepath)
+        except OSError:
+            return False
+    else:
+        nbytes = _nifti_proxy_nbytes(data)
+    if nbytes >= npy_eager_limit():
+        return False  # does not fit in RAM — the lazy source is the only option
+
     expected = data
     version = getattr(session, "data_version", 0)
 
     def _upgrade():
         try:
-            loaded = np.load(filepath)
+            if is_memmap:
+                loaded = np.load(filepath)
+            else:
+                from ._io import _nifti_display_array
+
+                loaded = _nifti_display_array(data)
         except Exception:
-            return  # keep serving from the map
+            return  # keep serving from the lazy source
         # A /reload or a released session must not be clobbered by a read that
         # started against the previous array.
         if session.data is expected and getattr(session, "data_version", 0) == version:
             session.data = loaded
+            if getattr(session, "original_volume", None) is expected:
+                session.original_volume = loaded
 
     threading.Thread(target=_upgrade, daemon=True).start()
     return True