anyplotlib 0.2.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

anyplotlib/__init__.py

@@ -17,8 +17,8 @@ from anyplotlib import embed
 from anyplotlib.markers import MarkerRegistry, MarkerGroup
 from anyplotlib.widgets import (
     Widget, RectangleWidget, CircleWidget, AnnularWidget,
-    CrosshairWidget, PolygonWidget, LabelWidget,
-    VLineWidget, HLineWidget, RangeWidget, PlaneWidget,
+    CrosshairWidget, PolygonWidget, LabelWidget, ArrowWidget,
+    VLineWidget, HLineWidget, RangeWidget, PointWidget, PlaneWidget,
 )
 
 # ── Global help flag ──────────────────────────────────────────────────────
@@ -45,8 +45,8 @@ __all__ = [
     "CallbackRegistry", "Event",
     "MarkerRegistry", "MarkerGroup",
     "Widget", "RectangleWidget", "CircleWidget", "AnnularWidget",
-    "CrosshairWidget", "PolygonWidget", "LabelWidget",
-    "VLineWidget", "HLineWidget", "RangeWidget", "PlaneWidget",
+    "CrosshairWidget", "PolygonWidget", "LabelWidget", "ArrowWidget",
+    "VLineWidget", "HLineWidget", "RangeWidget", "PointWidget", "PlaneWidget",
     "show_help", "get_color_cycle",
     "embed",
     "__version__",

anyplotlib/_base_plot.py

@@ -179,6 +179,37 @@ class _PanelMixin:
         self._push()
 
 
+class _TextHandle:
+    """Handle for a single text annotation created by :meth:`add_text`.
+
+    Wraps the underlying single-text :class:`~anyplotlib.markers.MarkerGroup`
+    and exposes label-oriented mutators (``set_text`` / ``set_color`` /
+    ``remove``) so callers do not need to know it is backed by a texts
+    marker collection.
+    """
+
+    __slots__ = ("_group",)
+
+    def __init__(self, group):
+        self._group = group
+
+    def set_text(self, s: str) -> None:
+        """Replace the displayed string."""
+        self._group.set(texts=[s])
+
+    def set_color(self, color: str) -> None:
+        """Change the text colour."""
+        self._group.set(color=color)
+
+    def remove(self) -> None:
+        """Remove the annotation from its panel."""
+        self._group.remove()
+
+    def __repr__(self) -> str:  # pragma: no cover
+        texts = self._group._data.get("texts") or [""]
+        return f"_TextHandle(text={texts[0]!r})"
+
+
 class _MarkerMixin:
     """Mixin for panels that support static marker collections.
 
@@ -197,6 +228,44 @@ class _MarkerMixin:
     def _add_marker(self, mtype: str, name, **kwargs):
         return self.markers.add(mtype, name, **kwargs)
 
+    def add_text(self, x, y, s, name=None, *, color="#ff0000",
+                 fontsize=12, transform="data", **kwargs) -> "_TextHandle":
+        """Add a single text annotation at ``(x, y)``.
+
+        A convenience wrapper over :meth:`add_texts` for the common
+        single-label case (e.g. a navigation index or scale-bar label).
+        The returned handle exposes ``set_text``, ``set_color`` and
+        ``remove`` so callers can mutate the label after creation.
+
+        Parameters
+        ----------
+        x, y : float
+            Anchor position.  Interpreted in the coordinate system named
+            by ``transform`` (``"data"``, ``"axes"``, or ``"display"``).
+        s : str
+            The text to display.
+        name : str, optional
+            Registry key.  Auto-generated if omitted.
+        color : str, optional
+            Text colour.  Default ``"#ff0000"``.
+        fontsize : int, optional
+            Font size in pixels.  Default ``12``.
+        transform : str, optional
+            Coordinate system for ``(x, y)``.  Default ``"data"``.
+        **kwargs : dict
+            Forwarded to :meth:`add_texts` (e.g. ``clip_display``).
+
+        Returns
+        -------
+        _TextHandle
+            Handle wrapping the underlying single-text marker group.
+        """
+        group = self.add_texts(
+            offsets=[(x, y)], texts=[s], name=name,
+            color=color, fontsize=fontsize, transform=transform, **kwargs,
+        )
+        return _TextHandle(group)
+
     def remove_marker(self, marker_type: str, name: str) -> None:
         """Remove a named marker collection by type and name.
 

anyplotlib/_electron.py

@@ -32,9 +32,20 @@ _BINARY_TRANSPORT = os.environ.get("APL_BINARY_TRANSPORT") == "1"
 # transport on its _encode_pixels "\x00bin:<checksum>" token stays in the geom JSON
 # and the real bytes are never shipped, so the renderer can't decode it and the crisp
 # zoom tile never displays (you only ever see the downsampled overview base).
+#
+# Image LAYERS add DYNAMIC pixel keys ``layer_<id>_b64`` (one per layer) that also
+# ride the geom channel and must ship as binary — they can't be enumerated in a
+# fixed frozenset, so ``_is_binary_pixel_key`` matches them by name pattern.
 _BINARY_KEYS = frozenset({"image_b64", "overlay_mask_b64", "detail_b64"})
 
 
+def _is_binary_pixel_key(k: str) -> bool:
+    """True for a geom key whose value is raw image pixels worth shipping as a
+    PLOTBIN binary frame — the fixed base-image/mask/detail keys OR a dynamic
+    per-layer key ``layer_<id>_b64``."""
+    return k in _BINARY_KEYS or (k.startswith("layer_") and k.endswith("_b64"))
+
+
 def _route_change(fig_id: str, name: str, value) -> None:
     """Forward ONE trait change to the host — as a raw PLOTBIN binary frame for a
     large image pixel trait (when binary transport is enabled), else as a
@@ -61,13 +72,15 @@ def _route_change(fig_id: str, name: str, value) -> None:
                 geom = json.loads(value)
             except Exception:
                 geom = None
-            if isinstance(geom, dict) and any(k in geom for k in _BINARY_KEYS):
+            if isinstance(geom, dict) and any(
+                    _is_binary_pixel_key(k) for k in geom):
                 panel_id = name[len("panel_"):-len("_geom")]
                 fig = _figures.get(fig_id)
                 raw_tbl = getattr(fig, "_raw_pixels", None)
                 sent_binary = False
                 for k in list(geom.keys()):
-                    if k not in _BINARY_KEYS or not isinstance(geom[k], str) or not geom[k]:
+                    if (not _is_binary_pixel_key(k)
+                            or not isinstance(geom[k], str) or not geom[k]):
                         continue
                     raw = None
                     if geom[k].startswith("\x00bin:") and raw_tbl is not None:

anyplotlib/_repr_utils.py

@@ -144,6 +144,20 @@ function makeModel(state) {{
   const _data   = Object.assign({{}}, state);
   const _cbs    = {{}};
   const _anyCbs = [];
+  // Keys set() has touched while _fromParent (an inbound awi_state push) is
+  // in effect, awaiting the matching save_changes() flush. Mirrors the
+  // dirty-set pattern figure_esm.js's own createLocalModel() uses (see
+  // mount()): the _fromParent branch below defers listener firing from
+  // set() to save_changes() (see the comment there), but save_changes() was
+  // firing EVERY registered change:* callback instead of only the key(s)
+  // that changed. Concretely: a single set('event_json', ...) (the Python
+  // targeted-widget-update side channel, _push_widget) also re-fired every
+  // panel's change:panel_<id>_json listener, which re-parses that panel's
+  // (untouched, stale) trait and overwrites p.state wholesale — silently
+  // reverting the very widget edit event_json just applied, in the same
+  // synchronous cascade. Only the _fromParent path needs tracking — the
+  // local (!_fromParent) path already fires synchronously in set() itself.
+  const _parentDirty = new Set();
   return {{
     get(key)      {{ return _data[key]; }},
     set(key, val) {{
@@ -155,12 +169,32 @@ function makeModel(state) {{
         const ev = 'change:' + key;
         if (_cbs[ev]) for (const cb of [..._cbs[ev]]) try {{ cb({{ new: val }}); }} catch(_) {{}}
         for (const cb of [..._anyCbs]) try {{ cb(); }} catch(_) {{}}
+      }} else {{
+        _parentDirty.add(key);
       }}
     }},
     save_changes() {{
-      for (const [ev, cbs] of Object.entries(_cbs))
-        for (const cb of cbs) try {{ cb({{ new: _data[ev.slice(7)] }}); }} catch(_) {{}}
-      for (const cb of _anyCbs) try {{ cb(); }} catch(_) {{}}
+      if (_parentDirty.size) {{
+        // Fire only listeners for keys an inbound awi_state set() actually
+        // touched since the last flush (each at most once) — not the whole
+        // _cbs table. Snapshot + clear BEFORE invoking callbacks, since a
+        // callback may itself call set()/save_changes() (re-entrant-safe).
+        const keys = [..._parentDirty];
+        _parentDirty.clear();
+        for (const key of keys) {{
+          const ev = 'change:' + key;
+          if (_cbs[ev]) for (const cb of [..._cbs[ev]]) try {{ cb({{ new: _data[key] }}); }} catch(_) {{}}
+        }}
+        for (const cb of [..._anyCbs]) try {{ cb(); }} catch(_) {{}}
+      }} else {{
+        // Local (!_fromParent) path — unchanged: set() already fired
+        // synchronously per-key, so this refires the full table (matches the
+        // pre-existing local-set behaviour; harmless since _cbs entries are
+        // typically no-ops for a key that hasn't just changed).
+        for (const [ev, cbs] of Object.entries(_cbs))
+          for (const cb of cbs) try {{ cb({{ new: _data[ev.slice(7)] }}); }} catch(_) {{}}
+        for (const cb of _anyCbs) try {{ cb(); }} catch(_) {{}}
+      }}
       // Forward interaction events to the parent-page Pyodide instance.
       if (!_fromParent && FIG_ID && window.parent !== window && _eventJsonDirty) {{
         _eventJsonDirty = false;
@@ -193,10 +227,14 @@ const blobUrl = URL.createObjectURL(blob);
 const el      = document.getElementById("widget-root");
 const model   = makeModel(STATE);
 
+// render() returns an internal API ({{ panels, exportPNG, ... }}) that the PNG
+// export protocol below needs.  Held here so the message listener can reach it.
+let _aplRenderApi = null;
+
 import(blobUrl).then(mod => {{
   const renderFn = mod.default?.render ?? mod.render;
   if (typeof renderFn === "function") {{
-    renderFn({{ model, el }});
+    _aplRenderApi = renderFn({{ model, el }});
   }} else {{
     el.textContent = "ESM has no render() export";
   }}
@@ -251,6 +289,40 @@ window.addEventListener('message', (e) => {{
     return;
   }}
 }});
+
+// ── PNG export protocol ──────────────────────────────────────────────────────
+// Rides the same postMessage channel as the state updates above.  A parent page
+// (or the SpyDE report harvester) requests a composite PNG of the whole figure:
+//   → {{ type: 'anyplotlib_export_png', requestId, opts }}
+// and receives back, on event.source (targetOrigin '*'):
+//   ← {{ type: 'anyplotlib_export_png_result', requestId, dataUrl, width, height }}
+//   ← {{ type: 'anyplotlib_export_png_result', requestId, error }}   (on failure)
+// `opts` is forwarded verbatim to handle.exportPNG ({{ scale?, includeWidgets? }}).
+window.addEventListener('message', (e) => {{
+  if (!e.data || e.data.type !== 'anyplotlib_export_png') return;
+  const requestId = e.data.requestId;
+  const source = e.source;
+  const reply = (msg) => {{
+    try {{
+      if (source && typeof source.postMessage === 'function') {{
+        source.postMessage(Object.assign(
+          {{ type: 'anyplotlib_export_png_result', requestId }}, msg), '*');
+      }}
+    }} catch (_) {{}}
+  }};
+  try {{
+    if (!_aplRenderApi || typeof _aplRenderApi.exportPNG !== 'function') {{
+      reply({{ error: 'figure not ready (exportPNG unavailable)' }});
+      return;
+    }}
+    Promise.resolve(_aplRenderApi.exportPNG(e.data.opts || {{}}))
+      .then((res) => reply({{
+        dataUrl: res.dataUrl, width: res.width, height: res.height }}))
+      .catch((err) => reply({{ error: String(err && err.message || err) }}));
+  }} catch (err) {{
+    reply({{ error: String(err && err.message || err) }});
+  }}
+}});
 </script>
 </body>
 </html>

anyplotlib/axes/_axes.py

@@ -202,7 +202,7 @@ class Axes:
         selected slice pops out of the translucent volume.
 
         **Large volumes** With WebGPU (``gpu="auto"``, the default, active
-        above ~8k cubes when a GPU is present) hundreds of thousands of
+        above ~1k cubes when a GPU is present) hundreds of thousands of
         voxels render interactively via instancing.  On the Canvas2D
         fallback the budget is ~20k cubes (~3–6 µs each); a warning is
         emitted above that *only when* ``gpu=False``.  For volumes too large
@@ -230,7 +230,7 @@ class Axes:
             Fix the axes bounds instead of fitting them to the data.
         gpu : ``"auto"`` | bool, optional
             WebGPU acceleration policy.  ``"auto"`` (default) renders cubes
-            on the GPU when available and the set exceeds ~8k; ``True`` always
+            on the GPU when available and the set exceeds ~1k; ``True`` always
             attempts GPU; ``False`` forces Canvas2D.  Falls back silently when
             WebGPU is unavailable — see :attr:`Plot3D.gpu_active`.
 

anyplotlib/axes/_inset_axes.py

@@ -6,6 +6,7 @@ Floating overlay inset (not in the grid).
 
 from __future__ import annotations
 
+import math
 import uuid as _uuid
 
 from anyplotlib.axes._axes import Axes
@@ -48,7 +49,16 @@ class InsetAxes(Axes):
         Width and height as fractions of the figure dimensions (0–1).
     corner : str, optional
         One of ``"top-right"``, ``"top-left"``, ``"bottom-right"``,
-        ``"bottom-left"``.  Default ``"top-right"``.
+        ``"bottom-left"``.  Default ``"top-right"``.  Mutually exclusive with
+        *anchor* — pass exactly one.
+    anchor : (x_frac, y_frac), optional
+        Position of the inset's TOP-LEFT corner as fractions of the figure
+        size (0–1), measured from the figure's top-left.  When given, the
+        inset floats freely at that anchor instead of snapping to a corner
+        (``corner`` is then ignored / ``None``).  Minimize / maximize / restore
+        all still work: a minimized anchored inset collapses to its title bar
+        in place, a maximized one floats centred, and restore returns it to the
+        anchor.
     title : str, optional
         Text shown in the inset title bar.  Default ``""``.
 
@@ -58,23 +68,38 @@ class InsetAxes(Axes):
     >>> ax.imshow(data)
     >>> inset = fig.add_inset(0.3, 0.25, corner="top-right", title="Zoom")
     >>> inset.imshow(data[64:128, 64:128])
+    >>> # arbitrary placement:
+    >>> free = fig.add_inset(0.3, 0.25, anchor=(0.55, 0.1), title="Callout")
+    >>> free.imshow(data[64:128, 64:128])
     """
 
     def __init__(self, fig, w_frac: float, h_frac: float, *,
-                 corner: str = "top-right", title: str = ""):
-        if corner not in _VALID_CORNERS:
-            raise ValueError(
-                f"corner must be one of {_VALID_CORNERS!r}, got {corner!r}"
-            )
+                 corner: str = "top-right", anchor=None, title: str = ""):
+        if anchor is not None:
+            ax_, ay_ = anchor
+            self.anchor = (float(ax_), float(ay_))
+            # anchor placement supersedes corner; keep corner=None so both the
+            # layout math and the callout corner-pairing know it is free-floating.
+            self.corner = None
+        else:
+            if corner not in _VALID_CORNERS:
+                raise ValueError(
+                    f"corner must be one of {_VALID_CORNERS!r}, got {corner!r}"
+                )
+            self.anchor = None
+            self.corner = corner
         # Pass a dummy SubplotSpec so Axes.__init__ doesn't fail — InsetAxes
         # never occupies a grid cell, only overlays the figure.
         from anyplotlib.figure._gridspec import SubplotSpec
         super().__init__(fig, SubplotSpec(None, 0, 1, 0, 1))
         self.w_frac = w_frac
         self.h_frac = h_frac
-        self.corner = corner
         self.title  = title
         self._inset_state: str = "normal"
+        # Region indication (mark_inset-style callout) tied to this inset, or
+        # None.  Set via :meth:`indicate_region`, cleared via
+        # :meth:`clear_indication`.  Persisted in Figure.layout_json.
+        self._indication: dict | None = None
 
     # ── state API ─────────────────────────────────────────────────────────
 
@@ -104,6 +129,107 @@ class InsetAxes(Axes):
         self._inset_state = "normal"
         self._fig._push_layout()
 
+    # ── region indication (mark_inset-style callout) ──────────────────────
+
+    def indicate_region(self, parent_plot, region, *,
+                        color: str = "#ff9800",
+                        linestyle: str = "dashed",
+                        linewidth: float = 1.5) -> "InsetAxes":
+        """Draw a callout tying this inset to a region of *parent_plot*.
+
+        Renders — on the parent panel's overlay — a rectangle around *region*
+        (in the parent image's DATA coordinates) plus two leader lines joining
+        the rectangle's corners that face the inset to the inset's nearest
+        corners, the classic matplotlib ``mark_inset`` look.  The rectangle
+        tracks the parent's zoom / pan and the leaders follow the inset as it
+        moves or minimizes (leaders hide while the inset is minimized).
+
+        Calling ``indicate_region`` again REPLACES any previous indication for
+        this inset.  Remove it with :meth:`clear_indication`.
+
+        Parameters
+        ----------
+        parent_plot : Plot2D
+            The parent image plot the region lives on.  Must be a 2-D image
+            panel in the SAME figure as this inset (typically the panel the
+            inset overlays) — a plot registered on a different ``Figure``
+            raises ``ValueError``.
+        region : tuple of float
+            The source rectangle in the parent image's data coordinates, as
+            ``(x, y, w, h)``: top-left ``(x, y)`` plus width and height.  The
+            values follow the same convention as the parent's axes (pixel
+            indices for an uncalibrated image; physical units when the axes
+            are calibrated).
+            All four must be finite; ``w`` and ``h`` must be strictly
+            positive.  The rectangle MAY extend outside the parent's data
+            bounds (e.g. a region near an edge) — that is allowed by design
+            and simply clips visually; only degenerate/non-finite values are
+            rejected.
+        color : str, optional
+            Stroke colour of both the rectangle and the leader lines.
+            Default warm orange ``"#ff9800"``.
+        linestyle : str, optional
+            ``"dashed"`` (default), ``"solid"``, or ``"dotted"``.
+        linewidth : float, optional
+            Stroke width in CSS px.  Default ``1.5``.
+
+        Returns
+        -------
+        InsetAxes
+            ``self``, for chaining.
+
+        Raises
+        ------
+        ValueError
+            If ``parent_plot`` has no panel id, is not registered on this
+            inset's Figure, or ``region`` is not 4 finite numbers with
+            ``w > 0`` and ``h > 0``.
+        """
+        pid = getattr(parent_plot, "_id", None)
+        if pid is None:
+            raise ValueError("indicate_region: parent_plot has no panel id "
+                             "(attach it to the figure first)")
+        if self._fig._plots_map.get(pid) is not parent_plot:
+            raise ValueError(
+                "indicate_region: parent_plot is not registered on this "
+                "inset's Figure — pass a plot created on the same figure "
+                "as this inset (fig.add_inset / fig.subplots)")
+        try:
+            x, y, w, h = (float(v) for v in region)
+        except (TypeError, ValueError):
+            raise ValueError(
+                f"indicate_region: region must be 4 numbers (x, y, w, h), "
+                f"got {region!r}") from None
+        if not all(math.isfinite(v) for v in (x, y, w, h)):
+            raise ValueError(
+                f"indicate_region: region values must be finite, got "
+                f"(x={x}, y={y}, w={w}, h={h})")
+        if not (w > 0 and h > 0):
+            raise ValueError(
+                f"indicate_region: region width and height must be > 0, "
+                f"got (w={w}, h={h})")
+        self._indication = {
+            "parent_id": pid,
+            "region":    [x, y, w, h],
+            "color":     color,
+            "linestyle": linestyle,
+            "linewidth": float(linewidth),
+        }
+        self._fig._push_layout()
+        return self
+
+    def clear_indication(self) -> None:
+        """Remove any region indication attached to this inset (idempotent)."""
+        if self._indication is None:
+            return
+        self._indication = None
+        self._fig._push_layout()
+
+    @property
+    def indication(self) -> "dict | None":
+        """The current region-indication spec (``dict``) or ``None``."""
+        return self._indication
+
     # ── internal ──────────────────────────────────────────────────────────
 
     def _attach(self, plot) -> None:
@@ -119,8 +245,10 @@ class InsetAxes(Axes):
 
     def __repr__(self) -> str:
         kind = _plot_kind(self._plot) if self._plot else "empty"
+        pos = (f"anchor={self.anchor!r}" if self.anchor is not None
+               else f"corner={self.corner!r}")
         return (
-            f"InsetAxes(corner={self.corner!r}, "
+            f"InsetAxes({pos}, "
             f"size=({self.w_frac:.2f}, {self.h_frac:.2f}), "
             f"state={self._inset_state!r}, kind={kind!r})"
         )

anyplotlib/callbacks.py

@@ -90,6 +90,10 @@ class Event:
     # Key
     key: str | None = None
     last_widget_id: str | None = None
+    # Panel drag-swap (figure-level panel_swap events): the two panel dispatch
+    # ids the user dragged between.  Set only on panel_swap; None otherwise.
+    source_panel_id: str | None = None
+    target_panel_id: str | None = None
     # Propagation (not repr'd)
     stop_propagation: bool = field(default=False, repr=False)