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

anyplotlib/_utils.py

@@ -192,6 +192,44 @@ def _build_colormap_lut(name: str) -> list:
     return [[v, v, v] for v in range(256)]
 
 
+def _parse_hex_color(color: str) -> tuple:
+    """Parse a ``#rgb`` / ``#rrggbb`` hex string → ``(r, g, b)`` ints (0–255).
+
+    Raises ``ValueError`` for anything else — tint colours are user API input
+    and a silent fallback would just render the wrong colour.
+    """
+    if not isinstance(color, str):
+        raise ValueError(f"expected a hex colour string, got {color!r}")
+    h = color.strip().lstrip("#")
+    try:
+        if len(h) == 3:
+            return tuple(int(c * 2, 16) for c in h)
+        if len(h) == 6:
+            return (int(h[0:2], 16), int(h[2:4], 16), int(h[4:6], 16))
+    except ValueError:
+        pass
+    raise ValueError(
+        f"invalid hex colour {color!r} — expected '#rgb' or '#rrggbb'")
+
+
+@functools.lru_cache(maxsize=64)
+def _build_tint_lut(color: str) -> list:
+    """Return a 256-entry ``[[r, g, b, a], ...]`` clear→colour TINT LUT.
+
+    RGB is the parsed *color* at every entry; alpha ramps linearly 0 → 255, so
+    a layer using this LUT is fully transparent at low intensity and the
+    opaque tint colour at high intensity (a solid-colour intensity ramp, the
+    overlay look, vs a named colormap's opaque colour gradient).
+
+    CACHED like :func:`_build_colormap_lut` and treated as read-only by
+    callers (they JSON-serialise it); do NOT mutate the returned list.  The
+    4th (alpha) channel is honoured by the JS layer compositor
+    (``_layerBitmap`` reads ``cmapData[i][3] ?? 255``).
+    """
+    r, g, b = _parse_hex_color(color)
+    return [[r, g, b, a] for a in range(256)]
+
+
 def _resample_mesh(data: np.ndarray, x_edges, y_edges) -> np.ndarray:
     """Resample a mesh to a regular pixel grid via nearest-neighbour lookup.
 

anyplotlib/axes/_inset_axes.py

@@ -96,9 +96,10 @@ class InsetAxes(Axes):
         self.h_frac = h_frac
         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.
+        # Region/point indication (mark_inset-style callout) tied to this
+        # inset, or None.  Set via :meth:`indicate_region` /
+        # :meth:`indicate_point`, cleared via :meth:`clear_indication`.
+        # Persisted in Figure.layout_json.
         self._indication: dict | None = None
 
     # ── state API ─────────────────────────────────────────────────────────
@@ -129,6 +130,76 @@ class InsetAxes(Axes):
         self._inset_state = "normal"
         self._fig._push_layout()
 
+    def set_geometry(self, *, anchor=None, w_frac: float | None = None,
+                     h_frac: float | None = None) -> "InsetAxes":
+        """Move and/or resize the inset in figure-fraction coordinates.
+
+        This is the Python-side counterpart to the interactive drag / resize
+        of an inset in the renderer's edit mode: the ``inset_geometry_change``
+        event dispatches here so the authoritative Python state converges with
+        what the user did on screen.  It is also callable directly to place or
+        size an inset programmatically.
+
+        Passing *anchor* switches the inset to free (anchor) placement and
+        drops any corner snapping (``corner`` becomes ``None``), mirroring the
+        renderer's corner-to-anchor conversion on drag start.
+
+        Parameters
+        ----------
+        anchor : (x_frac, y_frac), optional
+            New position of the inset's TOP-LEFT corner as fractions of the
+            figure size (0–1), measured from the figure's top-left.  Each
+            component is clamped into ``[0, 1]``.  When given, ``corner`` is
+            set to ``None`` (free placement).  When omitted, the current
+            placement (corner or existing anchor) is left unchanged.
+        w_frac, h_frac : float, optional
+            New width / height as fractions of the figure size.  Each is
+            clamped into ``(0, 1]`` (must be positive, at most the full
+            figure).  When omitted, the corresponding dimension is unchanged.
+
+        Returns
+        -------
+        InsetAxes
+            ``self``, for chaining.
+
+        Raises
+        ------
+        ValueError
+            If *anchor* is not a pair of finite numbers, or ``w_frac`` /
+            ``h_frac`` is not a finite number.
+        """
+        if anchor is not None:
+            try:
+                ax_, ay_ = (float(v) for v in anchor)
+            except (TypeError, ValueError):
+                raise ValueError(
+                    f"set_geometry: anchor must be 2 numbers (x_frac, y_frac), "
+                    f"got {anchor!r}") from None
+            if not all(math.isfinite(v) for v in (ax_, ay_)):
+                raise ValueError(
+                    f"set_geometry: anchor values must be finite, got "
+                    f"({ax_}, {ay_})")
+            ax_ = min(1.0, max(0.0, ax_))
+            ay_ = min(1.0, max(0.0, ay_))
+            self.anchor = (ax_, ay_)
+            # Anchor placement supersedes corner (matches __init__ / the JS
+            # corner→anchor conversion on drag start).
+            self.corner = None
+        if w_frac is not None:
+            w = float(w_frac)
+            if not math.isfinite(w):
+                raise ValueError(
+                    f"set_geometry: w_frac must be finite, got {w_frac!r}")
+            self.w_frac = min(1.0, max(1e-6, w))
+        if h_frac is not None:
+            h = float(h_frac)
+            if not math.isfinite(h):
+                raise ValueError(
+                    f"set_geometry: h_frac must be finite, got {h_frac!r}")
+            self.h_frac = min(1.0, max(1e-6, h))
+        self._fig._push_layout()
+        return self
+
     # ── region indication (mark_inset-style callout) ──────────────────────
 
     def indicate_region(self, parent_plot, region, *,
@@ -218,8 +289,94 @@ class InsetAxes(Axes):
         self._fig._push_layout()
         return self
 
+    def indicate_point(self, parent_plot, point, *,
+                       color: str = "#ff9800",
+                       linestyle: str = "dashed",
+                       linewidth: float = 1.5,
+                       marker_size: float = 5.0) -> "InsetAxes":
+        """Draw a callout tying this inset to a single POINT of *parent_plot*.
+
+        The point sibling of :meth:`indicate_region`: renders a small circular
+        marker (with a centre cross) at *point* — in the parent image's DATA
+        coordinates — plus ONE leader line joining the marker to the inset's
+        nearest corner.  The marker tracks the parent's zoom / pan and the
+        leader follows the inset as it moves (the leader hides while the inset
+        is minimized), exactly like the region callout.
+
+        Calling ``indicate_point`` (or ``indicate_region``) again REPLACES any
+        previous indication for this inset — an inset carries at most one.
+        Remove it with :meth:`clear_indication`.
+
+        Parameters
+        ----------
+        parent_plot : Plot2D
+            The parent image plot the point lives on.  Must be a 2-D image
+            panel registered on the SAME figure as this inset.
+        point : tuple of float
+            The source point in the parent image's data coordinates, as
+            ``(x, y)`` — same convention as :meth:`indicate_region`'s region
+            origin.  Both values must be finite; a point outside the parent's
+            data bounds is allowed (it simply clips visually).
+        color : str, optional
+            Stroke colour of the marker and the leader line.  Default warm
+            orange ``"#ff9800"``.
+        linestyle : str, optional
+            Leader style — ``"dashed"`` (default), ``"solid"``, or
+            ``"dotted"``.  The marker itself is always drawn solid.
+        linewidth : float, optional
+            Stroke width in CSS px.  Default ``1.5``.
+        marker_size : float, optional
+            Marker circle radius in CSS px.  Default ``5.0``.  Must be > 0.
+
+        Returns
+        -------
+        InsetAxes
+            ``self``, for chaining.
+
+        Raises
+        ------
+        ValueError
+            If ``parent_plot`` has no panel id, is not registered on this
+            inset's Figure, ``point`` is not 2 finite numbers, or
+            ``marker_size`` is not > 0.
+        """
+        pid = getattr(parent_plot, "_id", None)
+        if pid is None:
+            raise ValueError("indicate_point: 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_point: 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 = (float(v) for v in point)
+        except (TypeError, ValueError):
+            raise ValueError(
+                f"indicate_point: point must be 2 numbers (x, y), "
+                f"got {point!r}") from None
+        if not all(math.isfinite(v) for v in (x, y)):
+            raise ValueError(
+                f"indicate_point: point values must be finite, got "
+                f"(x={x}, y={y})")
+        ms = float(marker_size)
+        if not (math.isfinite(ms) and ms > 0):
+            raise ValueError(
+                f"indicate_point: marker_size must be > 0, got {marker_size!r}")
+        self._indication = {
+            "parent_id":   pid,
+            "point":       [x, y],
+            "color":       color,
+            "linestyle":   linestyle,
+            "linewidth":   float(linewidth),
+            "marker_size": ms,
+        }
+        self._fig._push_layout()
+        return self
+
     def clear_indication(self) -> None:
-        """Remove any region indication attached to this inset (idempotent)."""
+        """Remove any region/point indication attached to this inset
+        (idempotent)."""
         if self._indication is None:
             return
         self._indication = None
@@ -227,7 +384,8 @@ class InsetAxes(Axes):
 
     @property
     def indication(self) -> "dict | None":
-        """The current region-indication spec (``dict``) or ``None``."""
+        """The current indication spec (``dict`` with either a ``region`` or a
+        ``point`` key) or ``None``."""
         return self._indication
 
     # ── internal ──────────────────────────────────────────────────────────

anyplotlib/callbacks.py

@@ -24,7 +24,10 @@ from typing import Any, Callable
 VALID_EVENT_TYPES = frozenset({
     "pointer_down", "pointer_up", "pointer_move", "pointer_settled",
     "pointer_enter", "pointer_leave", "double_click", "wheel",
-    "key_down", "key_up", "close", "view_changed", "*",
+    "key_down", "key_up", "close", "view_changed",
+    # Figure-level inset drag / resize (JS → Python), so a host can persist the
+    # inset's new geometry.  Fired through the figure's CallbackRegistry.
+    "inset_geometry_change", "*",
 })
 
 
@@ -43,6 +46,7 @@ class Event:
         ray            — Plot3D only: {"origin": [...], "direction": [...]}
         line_id        — Plot1D only: set when pointer is over a line
         dwell_ms       — pointer_settled only: actual dwell time
+        target         — double_click only: hit chrome element, or None for plot-area (title/x_label/x_ticks/y_label/y_ticks/colorbar_label/legend)
 
     PlotBar extra fields (pointer_down only):
         bar_index, value, x_label, group_index
@@ -54,6 +58,14 @@ class Event:
         key            — key name e.g. "q", "Enter", "ArrowLeft"
         last_widget_id — id of the last widget the user clicked, or None
 
+    Panel-swap fields (figure-level panel_swap events):
+        source_panel_id, target_panel_id — the two panel ids dragged between
+
+    Inset drag/resize fields (figure-level inset_geometry_change events):
+        inset_id       — the inset panel id
+        anchor         — new top-left position [fx, fy] in figure fractions
+        w_frac, h_frac — new size in figure fractions
+
     Propagation:
         stop_propagation — set True inside a handler to halt remaining handlers
     """
@@ -94,6 +106,18 @@ class Event:
     # ids the user dragged between.  Set only on panel_swap; None otherwise.
     source_panel_id: str | None = None
     target_panel_id: str | None = None
+    # Inset drag / resize (figure-level inset_geometry_change events): the
+    # inset panel id plus its new geometry in figure fractions.  Set only on
+    # inset_geometry_change; None otherwise.
+    inset_id: str | None = None
+    anchor: list | None = None
+    w_frac: float | None = None
+    h_frac: float | None = None
+    # Tagged double-click hit-target (double_click events): identifies WHICH
+    # text/chrome element was double-clicked — one of 'title', 'x_label',
+    # 'x_ticks', 'y_label', 'y_ticks', 'colorbar_label', 'legend'.  None for a
+    # plain plot-area double_click (back-compatible) and every other event.
+    target: str | None = None
     # Propagation (not repr'd)
     stop_propagation: bool = field(default=False, repr=False)
 
@@ -101,7 +125,7 @@ class Event:
         src = type(self.source).__name__ if self.source is not None else "None"
         parts = [f"event_type={self.event_type!r}", f"source={src}"]
         for fname in ("x", "y", "xdata", "ydata", "button", "key",
-                      "line_id", "bar_index", "dwell_ms"):
+                      "line_id", "bar_index", "dwell_ms", "target"):
             v = getattr(self, fname)
             if v is not None:
                 parts.append(f"{fname}={v!r}")

anyplotlib/figure/_figure.py

@@ -596,6 +596,23 @@ class Figure(anywidget.AnyWidget, _EventMixin):
                     self._push_layout()
             return
 
+        # Inset drag / resize: the JS ships the inset's final geometry on
+        # pointer_up (anchor top-left fraction + size fractions).  Apply it to
+        # the InsetAxes via set_geometry so the authoritative Python state
+        # converges (the event fires once, on release, so re-pushing layout is
+        # an idempotent echo), then fire the figure-level callbacks with the
+        # geometry so a host can persist it.  Mirrors inset_state_change above.
+        if event_type == "inset_geometry_change":
+            inset_ax = self._insets_map.get(panel_id)
+            if inset_ax is not None:
+                anchor = msg.get("anchor")
+                w_frac = msg.get("w_frac")
+                h_frac = msg.get("h_frac")
+                inset_ax.set_geometry(anchor=anchor, w_frac=w_frac,
+                                      h_frac=h_frac)
+            self._fire_figure_event(event_type, msg)
+            return
+
         plot = self._plots_map.get(panel_id)
         if plot is None:
             if event_type == "view_changed":
@@ -656,6 +673,7 @@ class Figure(anywidget.AnyWidget, _EventMixin):
                 display_height=msg.get("display_height"),
                 key=msg.get("key"),
                 last_widget_id=msg.get("last_widget_id"),
+                target=msg.get("target"),
             )
             plot.callbacks.fire(event)
 
@@ -683,6 +701,17 @@ class Figure(anywidget.AnyWidget, _EventMixin):
             last_widget_id=msg.get("marker_id"),
             source_panel_id=msg.get("source_panel_id"),
             target_panel_id=msg.get("target_panel_id"),
+            # Inset drag / resize geometry — populated only for the
+            # inset_geometry_change event; None for every other figure-level
+            # event (figure_background click, figure-marker drag, panel_swap).
+            inset_id=(msg.get("panel_id")
+                      if event_type == "inset_geometry_change" else None),
+            anchor=(msg.get("anchor")
+                    if event_type == "inset_geometry_change" else None),
+            w_frac=(msg.get("w_frac")
+                    if event_type == "inset_geometry_change" else None),
+            h_frac=(msg.get("h_frac")
+                    if event_type == "inset_geometry_change" else None),
         )
         self.callbacks.fire(event)