anyplotlib 0.1.0__py3-none-any.whl

anyplotlib/sphinx_anywidget/static/anywidget_overlay.css

@@ -0,0 +1,100 @@
+/*
+ * anywidget_overlay.css
+ * =====================
+ * Styles for the per-figure interaction badges injected by AnywidgetScraper
+ * and the .. anywidget-figure:: RST directive.
+ *
+ * Badge structure (rendered by _scraper._iframe_html):
+ *
+ *   <div class="awi-fig-wrap" data-awi-fig="FIGID">
+ *     <iframe data-awi-fig="FIGID" ...></iframe>
+ *     <div class="awi-badge" data-awi-badge="FIGID">
+ *       <button class="awi-badge-icon awi-activate-btn">⚡</button>  <!-- interactive only -->
+ *     </div>
+ *   </div>
+ */
+
+/* ── figure wrapper ──────────────────────────────────────────────────────── */
+.awi-fig-wrap {
+  position: relative;  /* Badge positions relative to this */
+}
+
+/* ── badge container ─────────────────────────────────────────────────────── */
+.awi-badge {
+  position:    absolute;
+  top:         8px;
+  right:       8px;
+  display:     flex;
+  align-items: center;
+  gap:         8px;
+  z-index:     10;
+  pointer-events: none;
+}
+
+/* ── after activation: no change needed — stays top-right ───────────────── */
+
+/* ── shared icon style ───────────────────────────────────────────────────── */
+.awi-badge-icon {
+  display:      flex;
+  align-items:  center;
+  justify-content: center;
+  width:        38px;
+  height:       38px;
+  border-radius: 50%;
+  font-size:    18px;
+  line-height:  1;
+  background:   rgba(30, 30, 46, 0.82);
+  backdrop-filter: blur(6px);
+  border:       1px solid rgba(255, 255, 255, 0.25);
+  color:        #fff;
+  box-shadow:   0 2px 8px rgba(0,0,0,0.5);
+  transition:   opacity 0.25s, background 0.2s, transform 0.15s;
+  opacity:      0.90;
+}
+
+/* ── ⚡ activation button ────────────────────────────────────────────────── */
+.awi-activate-btn {
+  cursor:         pointer;
+  pointer-events: auto;
+  padding:        0;
+  font-family:    inherit;
+  border-color:   rgba(98, 114, 164, 0.7);
+  background:     rgba(30, 30, 46, 0.80);
+}
+
+.awi-activate-btn:hover {
+  background: rgba(98, 114, 164, 0.85);
+  opacity:    1;
+  transform:  scale(1.12);
+}
+
+.awi-activate-btn:focus-visible {
+  outline: 2px solid #8be9fd;
+  outline-offset: 2px;
+}
+
+/* ── loading state (⏳) ──────────────────────────────────────────────────── */
+.awi-activate-btn[data-state="loading"] {
+  cursor:        default;
+  pointer-events: none;
+  background:    rgba(189, 147, 249, 0.85);
+}
+
+/* ── active / live state (✓) ─────────────────────────────────────────────── */
+.awi-activate-btn[data-state="active"] {
+  background:  rgba(80, 250, 123, 0.85);
+  color:       #1e1e2e;
+  cursor:      default;
+  pointer-events: none;
+  font-weight: 700;
+}
+
+/* ── error state (❌) ────────────────────────────────────────────────────── */
+.awi-activate-btn[data-state="error"] {
+  background:     rgba(255, 85, 85, 0.85);
+  cursor:         default;
+  pointer-events: none;
+}
+
+
+

anyplotlib/widgets/__init__.py

@@ -0,0 +1,18 @@
+"""anyplotlib.widgets — interactive overlay widget classes."""
+from anyplotlib.widgets._base import Widget
+from anyplotlib.widgets._widgets2d import (
+    RectangleWidget, CircleWidget, AnnularWidget,
+    CrosshairWidget, PolygonWidget, LabelWidget,
+)
+from anyplotlib.widgets._widgets1d import (
+    VLineWidget, HLineWidget, RangeWidget, PointWidget,
+)
+from anyplotlib.widgets._widgets3d import PlaneWidget
+
+__all__ = [
+    "Widget",
+    "RectangleWidget", "CircleWidget", "AnnularWidget",
+    "CrosshairWidget", "PolygonWidget", "LabelWidget",
+    "VLineWidget", "HLineWidget", "RangeWidget", "PointWidget",
+    "PlaneWidget",
+]

anyplotlib/widgets/_base.py

@@ -0,0 +1,218 @@
+"""
+widgets/_base.py
+================
+Base Widget class shared by all interactive overlay widgets.
+"""
+
+from __future__ import annotations
+import uuid as _uuid
+from typing import Any, Callable
+from anyplotlib.callbacks import CallbackRegistry, Event, _EventMixin
+
+
+class Widget(_EventMixin):
+    """Base class for all overlay widgets.
+
+    Provides attribute-based state access, callbacks for interaction events,
+    and automatic synchronization with the JavaScript renderer.
+
+    Parameters
+    ----------
+    wtype : str
+        Widget type (e.g., 'rectangle', 'circle', 'crosshair').
+    push_fn : Callable
+        Zero-arg callback to send position updates to the JavaScript renderer.
+    **kwargs : dict
+        Initial widget state (position, size, color, etc.).
+
+    Attributes
+    ----------
+    callbacks : CallbackRegistry
+        Event callback registry. Register handlers via
+        ``widget.add_event_handler(fn, "pointer_move")`` or as a decorator:
+        ``@widget.add_event_handler("pointer_move")``.
+
+        Common event types:
+
+        - ``"pointer_move"`` — fires on every drag frame
+        - ``"pointer_up"`` — fires once when drag settles
+        - ``"pointer_down"`` — fires on click/press event
+    """
+
+    def __init__(self, wtype: str, push_fn: Callable, **kwargs):
+        self._id: str = str(_uuid.uuid4())[:8]
+        self._type: str = wtype
+        self._data: dict = dict(kwargs)
+        self._data["id"] = self._id
+        self._data["type"] = wtype
+        self._push_fn: Callable = push_fn
+        self.callbacks: CallbackRegistry = CallbackRegistry()
+
+    # ── attribute read ────────────────────────────────────────────────
+
+    def __getattr__(self, key: str):
+        """Access widget properties as attributes (read-only)."""
+        if key.startswith("_"):
+            raise AttributeError(key)
+        try:
+            return self._data[key]
+        except KeyError:
+            raise AttributeError(
+                f"{type(self).__name__} has no attribute {key!r}. "
+                f"Available: {list(self._data)}"
+            ) from None
+
+    # ── attribute write — routes public assignments through set() ────
+
+    def __setattr__(self, key: str, value) -> None:
+        """Update widget properties via attribute assignment."""
+        # Private attrs and 'callbacks' bypass set()
+        if key.startswith("_") or key == "callbacks":
+            super().__setattr__(key, value)
+            return
+        # During __init__ _data may not exist yet
+        try:
+            object.__getattribute__(self, "_data")
+        except AttributeError:
+            super().__setattr__(key, value)
+            return
+        self.set(**{key: value})
+
+    # ── set / get ─────────────────────────────────────────────────────
+
+    def set(self, _push: bool = True, **kwargs) -> None:
+        """Update properties and send targeted update to JavaScript.
+
+        Parameters
+        ----------
+        _push : bool, optional
+            Whether to push update to renderer. Default True.
+            Set to False internally to avoid echo loops.
+        **kwargs : dict
+            Properties to update (e.g., x=100, y=50, radius=20).
+
+        Notes
+        -----
+        Updates are sent as targeted widget updates, not full panel re-renders.
+        This is more efficient for frequent updates during dragging.
+        """
+        self._data.update(kwargs)
+        if _push:
+            self._push_fn()
+        self.callbacks.fire(Event("pointer_move", source=self))
+
+    def get(self, key: str, default=None):
+        """Get a widget property by name.
+
+        Parameters
+        ----------
+        key : str
+            Property name.
+        default : optional
+            Default value if property not found.
+
+        Returns
+        -------
+        object
+            The property value.
+        """
+        return self._data.get(key, default)
+
+    def to_dict(self) -> dict:
+        """Return a dict copy of the widget state.
+
+        Returns
+        -------
+        dict
+            All widget properties including id and type.
+        """
+        return dict(self._data)
+
+    # ── visibility ────────────────────────────────────────────────────────
+
+    @property
+    def visible(self) -> bool:
+        """``True`` if the widget is rendered; ``False`` if hidden."""
+        return self._data.get("visible", True)
+
+    @visible.setter
+    def visible(self, value: bool) -> None:
+        self.show() if value else self.hide()
+
+    def show(self) -> None:
+        """Show the widget.  Does not fire ``pointer_move`` callbacks."""
+        self._data["visible"] = True
+        self._push_fn()
+
+    def hide(self) -> None:
+        """Hide the widget without removing it or its callbacks.
+
+        Call :meth:`show` to make it visible again.
+        Does not fire ``pointer_move`` callbacks.
+        """
+        self._data["visible"] = False
+        self._push_fn()
+
+    # ── JS → Python sync ──────────────────────────────────────────────
+
+    def _update_from_js(self, msg: dict, event_type: str = "pointer_move") -> bool:
+        """Apply incoming JS state without pushing back (avoids echo).
+
+        Updates widget ``_data`` with widget-specific state fields from msg,
+        then fires widget callbacks with a flat Event.
+
+        Parameters
+        ----------
+        msg : dict
+            Full raw event message from JS.
+        event_type : str
+            One of the pointer event types (``pointer_move``, ``pointer_up``,
+            ``pointer_down``).
+
+        Returns
+        -------
+        bool
+            True if any widget state changed.
+        """
+        _envelope = {
+            "source", "panel_id", "event_type", "widget_id",
+            "time_stamp", "modifiers", "button", "buttons",
+        }
+        changed = False
+        for k, v in msg.items():
+            if k in ("id", "type") or k in _envelope:
+                continue
+            if self._data.get(k) != v:
+                self._data[k] = v
+                changed = True
+
+        if changed or event_type in ("pointer_up", "pointer_down"):
+            event = Event(
+                event_type=event_type,
+                source=self,
+                time_stamp=msg.get("time_stamp", 0.0),
+                modifiers=msg.get("modifiers", []),
+                x=msg.get("x"),
+                y=msg.get("y"),
+                button=msg.get("button"),
+                buttons=msg.get("buttons", 0),
+                xdata=msg.get("xdata"),
+                ydata=msg.get("ydata"),
+            )
+            self.callbacks.fire(event)
+        return changed
+
+    # ── repr ──────────────────────────────────────────────────────────
+
+    def __repr__(self) -> str:
+        props = ", ".join(
+            f"{k}={v:.4g}" if isinstance(v, float) else f"{k}={v!r}"
+            for k, v in self._data.items()
+            if k not in ("id", "type", "color")
+        )
+        return f"{type(self).__name__}({props})"
+
+    @property
+    def id(self) -> str:
+        """Return the widget's unique identifier."""
+        return self._id

anyplotlib/widgets/_widgets1d.py

@@ -0,0 +1,109 @@
+"""
+widgets/_widgets1d.py
+=====================
+Interactive overlay widgets for 1-D line panels (Plot1D).
+"""
+
+from __future__ import annotations
+from anyplotlib.widgets._base import Widget
+
+
+class VLineWidget(Widget):
+    """Draggable vertical line overlay widget for 1-D plots.
+
+    Allows interactive selection of a single x-axis value. The line can be
+    dragged left/right to change the selected position.
+
+    Parameters
+    ----------
+    push_fn : Callable
+        Update callback.
+    x : float
+        Initial x-position in data coordinates.
+    color : str, optional
+        CSS colour for the line. Default ``"#00e5ff"``.
+    """
+    def __init__(self, push_fn, *, x, color="#00e5ff"):
+        super().__init__("vline", push_fn, x=float(x), color=color)
+
+
+class HLineWidget(Widget):
+    """Draggable horizontal line overlay widget for bar charts.
+
+    Allows interactive selection of a single y-axis value. The line can be
+    dragged up/down to change the selected value.
+
+    Parameters
+    ----------
+    push_fn : Callable
+        Update callback.
+    y : float
+        Initial y-position in data coordinates.
+    color : str, optional
+        CSS colour for the line. Default ``"#00e5ff"``.
+    """
+    def __init__(self, push_fn, *, y, color="#00e5ff"):
+        super().__init__("hline", push_fn, y=float(y), color=color)
+
+
+class RangeWidget(Widget):
+    """Draggable range selection widget.
+
+    Two display styles are available:
+
+    ``style='band'`` (default)
+        Two connected vertical lines with a translucent fill band.  Either
+        line can be dragged independently; the whole band can be dragged by
+        clicking inside it.
+
+    ``style='fwhm'``
+        Two circular handles joined by a dashed horizontal line drawn at
+        height *y* (the half-maximum level).  Only the x-positions of the
+        handles are draggable.  Use this to show/edit a FWHM interval on a
+        peak.
+
+    Parameters
+    ----------
+    push_fn : Callable
+        Update callback.
+    x0, x1 : float
+        Initial left and right positions in data coordinates.
+    color : str, optional
+        CSS colour.  Default ``"#00e5ff"``.
+    style : {'band', 'fwhm'}, optional
+        Visual style.  Default ``"band"``.
+    y : float, optional
+        Y-position (data coordinates) for the connecting line when
+        ``style='fwhm'``.  Ignored for ``style='band'``.  Default ``0.0``.
+    """
+    def __init__(self, push_fn, *, x0, x1, color="#00e5ff",
+                 style: str = "band", y: float = 0.0):
+        super().__init__("range", push_fn,
+                         x0=float(x0), x1=float(x1), color=color,
+                         style=str(style), y=float(y))
+
+
+class PointWidget(Widget):
+    """Draggable point (control point) overlay widget for 1-D plots.
+
+    A free-moving handle that can be dragged to any position within the
+    plot area.  Reports its data-space ``x`` and ``y`` coordinates back
+    to Python via the standard callback hooks.
+
+    Parameters
+    ----------
+    push_fn : Callable
+        Update callback.
+    x : float
+        Initial x position in data coordinates.
+    y : float
+        Initial y position in data coordinates (value axis).
+    color : str, optional
+        CSS colour for the handle.  Default ``"#00e5ff"``.
+    show_crosshair : bool, optional
+        If ``True`` (default), draw dashed crosshair guide lines through the
+        handle.  Set to ``False`` for a bare draggable dot with no guides.
+    """
+    def __init__(self, push_fn, *, x, y, color="#00e5ff", show_crosshair=True):
+        super().__init__("point", push_fn, x=float(x), y=float(y), color=color,
+                         show_crosshair=bool(show_crosshair))

anyplotlib/widgets/_widgets2d.py

@@ -0,0 +1,141 @@
+"""
+widgets/_widgets2d.py
+=====================
+Interactive overlay widgets for 2-D image panels (Plot2D / InsetAxes).
+"""
+
+from __future__ import annotations
+from anyplotlib.widgets._base import Widget
+
+
+class RectangleWidget(Widget):
+    """Draggable rectangle overlay widget for 2-D plots.
+
+    Parameters
+    ----------
+    push_fn : Callable
+        Update callback.
+    x, y : float
+        Top-left corner position in pixel/data coordinates.
+    w, h : float
+        Width and height in pixel/data coordinates.
+    color : str, optional
+        CSS colour for the rectangle outline. Default ``"#00e5ff"``.
+    """
+    def __init__(self, push_fn, *, x, y, w, h, color="#00e5ff"):
+        super().__init__("rectangle", push_fn,
+                         x=float(x), y=float(y),
+                         w=float(w), h=float(h), color=color)
+
+
+class CircleWidget(Widget):
+    """Draggable circle overlay widget for 2-D plots.
+
+    Parameters
+    ----------
+    push_fn : Callable
+        Update callback.
+    cx, cy : float
+        Center position in pixel/data coordinates.
+    r : float
+        Radius in pixel/data coordinates.
+    color : str, optional
+        CSS colour for the circle outline. Default ``"#00e5ff"``.
+    """
+    def __init__(self, push_fn, *, cx, cy, r, color="#00e5ff"):
+        super().__init__("circle", push_fn,
+                         cx=float(cx), cy=float(cy), r=float(r), color=color)
+
+
+class AnnularWidget(Widget):
+    """Draggable annular (ring) overlay widget for 2-D plots.
+
+    Parameters
+    ----------
+    push_fn : Callable
+        Update callback.
+    cx, cy : float
+        Center position in pixel/data coordinates.
+    r_outer, r_inner : float
+        Outer and inner radii in pixel/data coordinates.
+        Inner radius must be less than outer radius.
+    color : str, optional
+        CSS colour for the ring outline. Default ``"#00e5ff"``.
+
+    Raises
+    ------
+    ValueError
+        If r_inner >= r_outer.
+    """
+    def __init__(self, push_fn, *, cx, cy, r_outer, r_inner, color="#00e5ff"):
+        if r_inner >= r_outer:
+            raise ValueError("r_inner must be < r_outer")
+        super().__init__("annular", push_fn,
+                         cx=float(cx), cy=float(cy),
+                         r_outer=float(r_outer), r_inner=float(r_inner),
+                         color=color)
+
+
+class CrosshairWidget(Widget):
+    """Draggable crosshair overlay widget for 2-D plots.
+
+    Parameters
+    ----------
+    push_fn : Callable
+        Update callback.
+    cx, cy : float
+        Center position in pixel/data coordinates.
+    color : str, optional
+        CSS colour for the crosshair. Default ``"#00e5ff"``.
+    """
+    def __init__(self, push_fn, *, cx, cy, color="#00e5ff"):
+        super().__init__("crosshair", push_fn,
+                         cx=float(cx), cy=float(cy), color=color)
+
+
+class PolygonWidget(Widget):
+    """Draggable polygon overlay widget for 2-D plots.
+
+    Parameters
+    ----------
+    push_fn : Callable
+        Update callback.
+    vertices : list of tuple
+        Polygon vertices ``[(x0, y0), (x1, y1), ...]`` in pixel/data coordinates.
+        Must have at least 3 vertices.
+    color : str, optional
+        CSS colour for the polygon outline. Default ``"#00e5ff"``.
+
+    Raises
+    ------
+    ValueError
+        If fewer than 3 vertices provided.
+    """
+    def __init__(self, push_fn, *, vertices, color="#00e5ff"):
+        verts = [[float(x), float(y)] for x, y in vertices]
+        if len(verts) < 3:
+            raise ValueError("polygon needs >= 3 vertices")
+        super().__init__("polygon", push_fn, vertices=verts, color=color)
+
+
+class LabelWidget(Widget):
+    """Text label overlay widget for 2-D plots.
+
+    Parameters
+    ----------
+    push_fn : Callable
+        Update callback.
+    x, y : float
+        Label position in pixel/data coordinates.
+    text : str, optional
+        Label text. Default ``"Label"``.
+    fontsize : int, optional
+        Font size in points. Default 14.
+    color : str, optional
+        CSS colour for the text. Default ``"#00e5ff"``.
+    """
+    def __init__(self, push_fn, *, x, y, text="Label", fontsize=14,
+                 color="#00e5ff"):
+        super().__init__("label", push_fn,
+                         x=float(x), y=float(y),
+                         text=str(text), fontsize=int(fontsize), color=color)

anyplotlib/widgets/_widgets3d.py

@@ -0,0 +1,50 @@
+"""
+widgets/_widgets3d.py
+=====================
+Interactive overlay widgets for 3-D panels.
+"""
+
+from __future__ import annotations
+
+from typing import Callable
+
+from anyplotlib.widgets._base import Widget
+
+
+class PlaneWidget(Widget):
+    """A draggable axis-aligned plane in a 3-D panel.
+
+    Rendered as a translucent quad spanning the panel's bounds,
+    perpendicular to *axis* at *position*.  Drag it in the browser to slide
+    it along its normal — ideal as a slice selector for voxel volumes.
+    Voxels lying on a plane are rendered more opaque (see
+    :meth:`~anyplotlib.Axes.voxels`).
+
+    Parameters
+    ----------
+    axis : ``"x"`` | ``"y"`` | ``"z"``
+        The plane's normal axis.
+    position : float
+        Position along *axis* in data coordinates.
+    color : str, optional
+        CSS colour of the plane fill and border.
+    alpha : float, optional
+        Fill opacity (0–1).  Default 0.12.
+
+    Examples
+    --------
+    >>> pw = vol.add_widget("plane", axis="z", position=24)
+    >>> @pw.add_event_handler("pointer_move")
+    ... def on_drag(event):
+    ...     print("slice now at", pw.position)
+    >>> pw.set(position=10)        # move it from Python
+    """
+
+    def __init__(self, push_fn: Callable, axis: str = "z",
+                 position: float = 0.0, color: str = "#00e5ff",
+                 alpha: float = 0.12):
+        if axis not in ("x", "y", "z"):
+            raise ValueError(f"axis must be 'x', 'y', or 'z', got {axis!r}")
+        super().__init__("plane", push_fn,
+                         axis=axis, position=float(position),
+                         color=color, alpha=float(alpha))