pyviewarr 0.3.4__tar.gz → 0.4.0__tar.gz

{pyviewarr-0.3.4 → pyviewarr-0.4.0}/.gitignore

@@ -15,3 +15,6 @@ viewarr/pkg
 
 # playwright test artifacts
 test-results/
+tests/e2e/screenshots/
+# notebooks the e2e suite creates via Jupyter "New Notebook"
+Untitled*.ipynb

{pyviewarr-0.3.4 → pyviewarr-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: pyviewarr
-Version: 0.3.4
+Version: 0.4.0
 License-File: LICENSE
 Requires-Python: >=3.10
 Requires-Dist: anywidget<0.10,>=0.9

{pyviewarr-0.3.4 → pyviewarr-0.4.0}/src/pyviewarr/__init__.py

@@ -1,5 +1,6 @@
 import importlib.metadata
 import pathlib
+import warnings
 from IPython.display import display
 from dataclasses import asdict, dataclass
 from typing import Any, Callable, Dict, Literal, Optional, Tuple, TYPE_CHECKING, Union
@@ -310,18 +311,12 @@ class ViewArrWidget(anywidget.AnyWidget):
     _esm = pathlib.Path(__file__).parent / "static" / "widget.js"
     _css = pathlib.Path(__file__).parent / "static" / "widget.css"
 
-    # Binary image data (synced as DataView in JavaScript)
-    data = traitlets.Bytes(b"").tag(sync=True)
-
-    # Image dimensions
+    # Image dimensions of the currently shown slice (informational / introspection;
+    # the actual pixels are sent on demand over the custom message channel).
     image_width = traitlets.Int(0).tag(sync=True)
     image_height = traitlets.Int(0).tag(sync=True)
 
-    # Monotonic token that increments whenever image payload traits are updated.
-    # Frontend applies setImageData when it observes a new token value.
-    _image_update_token = traitlets.Int(0).tag(sync=True)
-
-    # Data type string for viewarr (e.g., "f32", "u16")
+    # Data type string for viewarr (e.g., "f32", "u16") of the current slice.
     dtype = traitlets.Unicode("f64").tag(sync=True)
 
     # Widget display dimensions (CSS pixels)
@@ -331,7 +326,8 @@ class ViewArrWidget(anywidget.AnyWidget):
     # Array shape (list of dimensions)
     shape = traitlets.List(traitlets.Int()).tag(sync=True)
 
-    # Current slice indices for leading axes (empty for 2D arrays)
+    # Current slice indices for leading axes (empty for 2D arrays). Informational:
+    # navigation is driven by the frontend via the "request_slice" message.
     current_slice_indices = traitlets.List(traitlets.Int()).tag(sync=True)
 
     # Optional initial viewer state object (mapped to JS state keys)
@@ -426,8 +422,11 @@ class ViewArrWidget(anywidget.AnyWidget):
         super().__init__(**kwargs)
         self._on_shift_click = shift_click_callback
         self._array = None
-        self.observe(self._on_slice_indices_changed, names=["current_slice_indices"])
         self.observe(self._on_shift_click_event, names=["_shift_click_event"])
+        # Slices are served on demand over a custom message channel rather than
+        # via synced traits, so every request produces a fresh slice (synced List
+        # traits would dedup an unchanged value and stall a play-mode prefetch).
+        self.on_msg(self._handle_frontend_msg)
 
     def set_shift_click_callback(
         self, callback: Optional[ShiftClickCallback]
@@ -447,33 +446,84 @@ class ViewArrWidget(anywidget.AnyWidget):
         if isinstance(x, (int, float)) and isinstance(y, (int, float)):
             callback(float(x), float(y))
 
-    def _on_slice_indices_changed(self, change):
-        """Update the displayed slice when slice indices change."""
-        self._update_slice()
-
-    def _update_slice(self):
-        """Compute the current 2D slice and update traits."""
-        if self._array is None:
+    def _handle_frontend_msg(self, _widget, content, _buffers):
+        """Handle a custom message from the frontend (e.g. a slice request)."""
+        if not isinstance(content, dict):
             return
-
+        if content.get("type") == "request_slice":
+            try:
+                indices = [int(i) for i in content.get("indices", [])]
+            except (TypeError, ValueError):
+                return
+            # Every request must get an answer. The viewer only has one slice
+            # request in flight at a time, so a request that goes unanswered --
+            # because the array is gone, the indices are stale, or reading the
+            # slice raised -- would leave its scrubber dead for the rest of the
+            # session. Report the failure instead of letting it escape here.
+            try:
+                self._send_slice(indices)
+            except Exception as exc:  # noqa: BLE001 - must not wedge the viewer
+                self._send_slice_error(indices, exc)
+
+    def _compute_slice(self, indices):
+        """Return the 2D slice at ``indices`` as a contiguous little-endian array."""
         arr = self._array
-        indices = self.current_slice_indices
-
-        # Slice the array: leading axes use indices, last two are full slices
         if len(indices) > 0:
             slice_obj = tuple(indices) + (slice(None), slice(None))
             slice_arr = arr[slice_obj]
         else:
             slice_arr = arr
-
-        # Ensure slice is contiguous and little-endian
         slice_arr = np.ascontiguousarray(slice_arr)
-        slice_arr = slice_arr.astype(slice_arr.dtype.newbyteorder("<"))
+        return slice_arr.astype(slice_arr.dtype.newbyteorder("<"))
 
-        self.dtype = _numpy_dtype_to_viewarr(slice_arr.dtype)
+    def _refresh_slice_state(self, indices):
+        """Compute the slice at ``indices`` and update the informational traits."""
+        slice_arr = self._compute_slice(indices)
+        self.current_slice_indices = list(indices)
         self.image_height, self.image_width = slice_arr.shape
-        self.data = slice_arr.tobytes()
-        self._image_update_token += 1
+        self.dtype = _numpy_dtype_to_viewarr(slice_arr.dtype)
+        return slice_arr
+
+    def _send_slice(self, indices):
+        """Serve a slice to the frontend over the custom message channel.
+
+        Always produces a slice for the requested indices (no dedup), so a
+        play-mode prefetch that re-requests the slice the kernel already holds
+        still completes.
+        """
+        if self._array is None:
+            raise RuntimeError("no array is set on this viewer")
+        slice_arr = self._refresh_slice_state(indices)
+        self.send(
+            {
+                "type": "slice",
+                "indices": list(indices),
+                "width": int(self.image_width),
+                "height": int(self.image_height),
+                "dtype": self.dtype,
+            },
+            buffers=[slice_arr.tobytes()],
+        )
+
+    def _send_slice_error(self, indices, exc):
+        """Tell the frontend a slice request could not be served.
+
+        The frontend hands this to the viewer so it stops waiting on the reply
+        and the slider keeps working; without it one failed read disables
+        slice navigation until the widget is recreated.
+        """
+        warnings.warn(
+            f"pyviewarr could not serve slice {list(indices)}: {exc}",
+            RuntimeWarning,
+            stacklevel=2,
+        )
+        self.send(
+            {
+                "type": "slice_error",
+                "indices": list(indices),
+                "message": f"{type(exc).__name__}: {exc}",
+            }
+        )
 
     def set_array(self, arr: np.ndarray) -> None:
         """Set the array data to display.
@@ -493,12 +543,11 @@ class ViewArrWidget(anywidget.AnyWidget):
         # Set shape
         self.shape = list(arr.shape)
 
-        # Initialize slice indices for leading axes
+        # Initialize on the first slice. We only refresh the informational traits
+        # here; the frontend pulls the actual pixels on demand (on viewer-ready
+        # and whenever the shape changes) via the "request_slice" message.
         num_leading_axes = arr.ndim - 2
-        self.current_slice_indices = [0] * num_leading_axes
-
-        # Update the displayed slice
-        self._update_slice()
+        self._refresh_slice_state([0] * num_leading_axes)
 
     def get_current_slice(self) -> np.ndarray:
         """Get the current 2D slice being displayed.

pyviewarr-0.4.0/src/pyviewarr/static/widget.css

@@ -0,0 +1 @@
+.pyviewarr{display:inline-block;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none}.pyviewarr-container{background-color:transparent;border:1px solid var(--jp-border-color1, var(--vscode-panel-border, #333));overflow:hidden}.pyviewarr-container:focus-within{border-color:var(--jp-brand-color1, var(--vscode-focusBorder, #2196f3));box-shadow:inset 0 0 0 1px var(--jp-brand-color1, var(--vscode-focusBorder, #2196f3))}.pyviewarr-container canvas:focus{outline:none}