pyviewarr 0.3.2__tar.gz → 0.3.3__tar.gz

{pyviewarr-0.3.2 → pyviewarr-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyviewarr
-Version: 0.3.2
+Version: 0.3.3
 License-File: LICENSE
 Requires-Python: >=3.10
 Requires-Dist: anywidget<0.10,>=0.9
@@ -107,6 +107,9 @@ Use the left and right arrow buttons to rotate in 15º increments, or enter a nu
 
 By default, rotation is about the image center, but you can set a pivot point by Cmd/Ctrl-Shift-clicking the desired point.
 
+Shift-clicking on the image calls an optional Python callback with continuous data-space coordinates (`x`, `y` including fractional pixel position).
+Overlay help text is optional and only shown when you provide `overlay_message`.
+
 ### Matplotlib integration
 
 Once you've rotated and panned and stretched and zoomed you may want to save a plot, but the viewer doesn't handle plotting.
@@ -140,6 +143,36 @@ pyviewarr.show(x, vmin=-10, vmax=10)
 
 See [example](./preconfigured_state_example.ipynb).
 
+#### Marker coordinates API
+
+Use `widget.markers` to supply marker positions as continuous image coordinates.
+
+```python
+widget = pyviewarr.viewarr(x)
+widget.markers = [(10.5, 20.25), (100.0, 42.0)]
+```
+
+Markers are rendered as fixed-size plus signs in screen space, and follow pan/zoom/rotation transforms.
+
+#### Shift-click callback API
+
+Use `ViewerConfig.on_shift_click` to receive continuous data-space click coordinates:
+
+```python
+def on_shift_click(x: float, y: float) -> None:
+    print(f"Shift-click at x={x:.3f}, y={y:.3f}")
+
+cfg = pyviewarr.ViewerConfig(
+    on_shift_click=on_shift_click,
+    overlay_message="Shift-click to report coordinates",
+)
+widget = pyviewarr.viewarr(x, viewer_config=cfg)
+widget
+```
+
+For a demo that combines callbacks with marker updates, see
+[shift-click callback demo](./notebooks/shift_click_callback_demo.ipynb).
+
 #### Setting data
 
 If you retain a reference to the widget, you can set its contents from a later cell (if you want).
@@ -252,7 +285,27 @@ GitHub releases are automatically pushed to PyPI by the workflow in [`.github/wo
 
 ### Unreleased (since `v0.3.2`)
 
-- No unreleased changes yet.
+#### pyviewarr changes
+
+- Added `ViewerConfig.on_shift_click` Python callback to receive shift-click coordinates in data space (`x`, `y`) with fractional precision.
+- Refactored overlay text to generic `ViewerConfig.overlay_message` (not callback-specific).
+- Removed default overlay text; overlay is now hidden unless `overlay_message` is provided.
+- Added tests covering shift-click callback wiring and `ViewerConfig` JS serialization exclusions for Python-only fields.
+- Added a demonstration notebook: [`notebooks/shift_click_callback_demo.ipynb`](./notebooks/shift_click_callback_demo.ipynb).
+- Updated notebook callback logging example to use `ipywidgets.Output` for reliable async callback output display.
+- Updated usage docs with shift-click callback example and notebook link.
+- Updated bundled `viewarr` submodule to include shift-click callback and overlay layout improvements.
+- Updated bundled `viewarr` submodule to include diverging-mode colorbar limit textbox fixes.
+
+#### Included `viewarr` changes
+
+- Added shift-click callback events via `onClick(...)` with continuous (fractional) data-space coordinates.
+- Added generic overlay message APIs: `getOverlayMessage(...)` and `setOverlayMessage(...)`.
+- Added `overlayMessage` support to `setViewerState(...)`.
+- Renamed overlay API from shift-click-specific names to generic names (`getOverlayMessage`/`setOverlayMessage`, `overlayMessage` in state config).
+- Fixed diverging/symmetric colorbar limit editing/reporting behavior and `vmin` textbox refresh when switching back to non-symmetric modes.
+- Removed default overlay text; overlay only renders when message text is supplied.
+- Updated overlay placement to compute a live safe area between bottom overlays, avoiding overlap with hover coordinates and zoom controls while keeping the message centered in that gap.
 
 ### `v0.3.2`
 

{pyviewarr-0.3.2 → pyviewarr-0.3.3}/README.md

@@ -93,6 +93,9 @@ Use the left and right arrow buttons to rotate in 15º increments, or enter a nu
 
 By default, rotation is about the image center, but you can set a pivot point by Cmd/Ctrl-Shift-clicking the desired point.
 
+Shift-clicking on the image calls an optional Python callback with continuous data-space coordinates (`x`, `y` including fractional pixel position).
+Overlay help text is optional and only shown when you provide `overlay_message`.
+
 ### Matplotlib integration
 
 Once you've rotated and panned and stretched and zoomed you may want to save a plot, but the viewer doesn't handle plotting.
@@ -126,6 +129,36 @@ pyviewarr.show(x, vmin=-10, vmax=10)
 
 See [example](./preconfigured_state_example.ipynb).
 
+#### Marker coordinates API
+
+Use `widget.markers` to supply marker positions as continuous image coordinates.
+
+```python
+widget = pyviewarr.viewarr(x)
+widget.markers = [(10.5, 20.25), (100.0, 42.0)]
+```
+
+Markers are rendered as fixed-size plus signs in screen space, and follow pan/zoom/rotation transforms.
+
+#### Shift-click callback API
+
+Use `ViewerConfig.on_shift_click` to receive continuous data-space click coordinates:
+
+```python
+def on_shift_click(x: float, y: float) -> None:
+    print(f"Shift-click at x={x:.3f}, y={y:.3f}")
+
+cfg = pyviewarr.ViewerConfig(
+    on_shift_click=on_shift_click,
+    overlay_message="Shift-click to report coordinates",
+)
+widget = pyviewarr.viewarr(x, viewer_config=cfg)
+widget
+```
+
+For a demo that combines callbacks with marker updates, see
+[shift-click callback demo](./notebooks/shift_click_callback_demo.ipynb).
+
 #### Setting data
 
 If you retain a reference to the widget, you can set its contents from a later cell (if you want).
@@ -238,7 +271,27 @@ GitHub releases are automatically pushed to PyPI by the workflow in [`.github/wo
 
 ### Unreleased (since `v0.3.2`)
 
-- No unreleased changes yet.
+#### pyviewarr changes
+
+- Added `ViewerConfig.on_shift_click` Python callback to receive shift-click coordinates in data space (`x`, `y`) with fractional precision.
+- Refactored overlay text to generic `ViewerConfig.overlay_message` (not callback-specific).
+- Removed default overlay text; overlay is now hidden unless `overlay_message` is provided.
+- Added tests covering shift-click callback wiring and `ViewerConfig` JS serialization exclusions for Python-only fields.
+- Added a demonstration notebook: [`notebooks/shift_click_callback_demo.ipynb`](./notebooks/shift_click_callback_demo.ipynb).
+- Updated notebook callback logging example to use `ipywidgets.Output` for reliable async callback output display.
+- Updated usage docs with shift-click callback example and notebook link.
+- Updated bundled `viewarr` submodule to include shift-click callback and overlay layout improvements.
+- Updated bundled `viewarr` submodule to include diverging-mode colorbar limit textbox fixes.
+
+#### Included `viewarr` changes
+
+- Added shift-click callback events via `onClick(...)` with continuous (fractional) data-space coordinates.
+- Added generic overlay message APIs: `getOverlayMessage(...)` and `setOverlayMessage(...)`.
+- Added `overlayMessage` support to `setViewerState(...)`.
+- Renamed overlay API from shift-click-specific names to generic names (`getOverlayMessage`/`setOverlayMessage`, `overlayMessage` in state config).
+- Fixed diverging/symmetric colorbar limit editing/reporting behavior and `vmin` textbox refresh when switching back to non-symmetric modes.
+- Removed default overlay text; overlay only renders when message text is supplied.
+- Updated overlay placement to compute a live safe area between bottom overlays, avoiding overlap with hover coordinates and zoom controls while keeping the message centered in that gap.
 
 ### `v0.3.2`
 

{pyviewarr-0.3.2 → pyviewarr-0.3.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pyviewarr"
-version = "0.3.2"
+version = "0.3.3"
 dependencies = ["anywidget>=0.9,<0.10", "numpy>=2.0,<3"]
 readme = "README.md"
 requires-python = ">=3.10"

{pyviewarr-0.3.2 → pyviewarr-0.3.3}/src/pyviewarr/__init__.py

@@ -2,7 +2,7 @@ import importlib.metadata
 import pathlib
 from IPython.display import display
 from dataclasses import asdict, dataclass
-from typing import Any, Dict, Literal, Optional, Tuple, TYPE_CHECKING, Union
+from typing import Any, Callable, Dict, Literal, Optional, Tuple, TYPE_CHECKING, Union
 
 import anywidget
 import numpy as np
@@ -47,6 +47,9 @@ _CMAP_CANONICAL_NAMES = {
     "rdylbu": "RdYlBu",
 }
 
+ShiftClickCallback = Callable[[float, float], None]
+MarkerPoint = Tuple[float, float]
+
 
 def _numpy_dtype_to_viewarr(dtype: np.dtype) -> str:
     """Convert numpy dtype to viewarr type string."""
@@ -262,10 +265,19 @@ class ViewerConfig:
     rotation: Optional[float] = None
     pivot: Optional[Tuple[float, float]] = None
     show_pivot_marker: Optional[bool] = None
+    markers: Optional[list[MarkerPoint]] = None
+    on_shift_click: Optional[ShiftClickCallback] = None
+    overlay_message: Optional[str] = None
 
     def to_js_dict(self) -> Dict[str, Any]:
         """Convert config to the JS object shape expected by the frontend."""
         raw = asdict(self)
+        raw.pop("on_shift_click", None)
+        raw.pop("overlay_message", None)
+        if raw.get("markers") is not None:
+            raw["markers"] = [
+                (float(point[0]), float(point[1])) for point in raw["markers"]
+            ]
         if raw.get("cmap") is not None:
             cmap = str(raw["cmap"]).strip()
             raw["cmap"] = _CMAP_CANONICAL_NAMES.get(cmap.lower(), cmap)
@@ -324,6 +336,10 @@ class ViewArrWidget(anywidget.AnyWidget):
 
     # Optional initial viewer state object (mapped to JS state keys)
     viewer_config = traitlets.Dict(default_value={}).tag(sync=True)
+    # Optional overlay message shown at bottom-center of the viewer
+    overlay_message = traitlets.Unicode("").tag(sync=True)
+    # Latest shift-click event from frontend: {"x": float, "y": float, "token": int}
+    _shift_click_event = traitlets.Dict(default_value={}).tag(sync=True)
 
     # =========================================================================
     # Viewer state properties (bidirectional sync with frontend)
@@ -373,6 +389,10 @@ class ViewArrWidget(anywidget.AnyWidget):
 
     # Whether to show the pivot marker
     show_pivot_marker = traitlets.Bool(False).tag(sync=True)
+    # Marker list as continuous image coordinates: [(x, y), ...]
+    markers = traitlets.List(
+        traitlets.Tuple(traitlets.Float(), traitlets.Float()), default_value=[]
+    ).tag(sync=True)
 
     # Internal flag to prevent feedback loops during sync
     _sync_from_viewer = traitlets.Bool(False).tag(sync=True)
@@ -382,14 +402,50 @@ class ViewArrWidget(anywidget.AnyWidget):
         viewer_config: Optional[Union[ViewerConfig, Dict[str, Any]]] = None,
         **kwargs,
     ):
+        shift_click_callback = None
         if viewer_config is not None:
             if isinstance(viewer_config, ViewerConfig):
+                shift_click_callback = viewer_config.on_shift_click
+                if viewer_config.overlay_message is not None:
+                    kwargs["overlay_message"] = viewer_config.overlay_message
+                if viewer_config.markers is not None:
+                    kwargs["markers"] = [
+                        (float(x), float(y)) for (x, y) in viewer_config.markers
+                    ]
                 kwargs["viewer_config"] = viewer_config.to_js_dict()
             else:
-                kwargs["viewer_config"] = ViewerConfig(**dict(viewer_config)).to_js_dict()
+                config_dict = dict(viewer_config)
+                shift_click_callback = config_dict.pop("on_shift_click", None)
+                overlay_message = config_dict.pop("overlay_message", None)
+                markers = config_dict.get("markers")
+                if overlay_message is not None:
+                    kwargs["overlay_message"] = overlay_message
+                if markers is not None:
+                    kwargs["markers"] = [(float(x), float(y)) for (x, y) in markers]
+                kwargs["viewer_config"] = ViewerConfig(**config_dict).to_js_dict()
         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"])
+
+    def set_shift_click_callback(
+        self, callback: Optional[ShiftClickCallback]
+    ) -> None:
+        """Set or clear the Python callback invoked on shift-click events."""
+        self._on_shift_click = callback
+
+    def _on_shift_click_event(self, change):
+        callback = self._on_shift_click
+        if callback is None:
+            return
+        event = change.get("new", {})
+        if not isinstance(event, dict):
+            return
+        x = event.get("x")
+        y = event.get("y")
+        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."""
@@ -497,6 +553,9 @@ class ViewArrWidget(anywidget.AnyWidget):
             rotation=self.rotation,
             pivot=self.pivot,
             show_pivot_marker=self.show_pivot_marker,
+            markers=self.markers,
+            on_shift_click=self._on_shift_click,
+            overlay_message=self.overlay_message,
         )
 
     def plot_to_matplotlib(