anyplotlib 0.4.2__py3-none-any.whl → 0.6.0__py3-none-any.whl

anyplotlib/__init__.py

@@ -17,7 +17,7 @@ from anyplotlib import embed
 from anyplotlib.markers import MarkerRegistry, MarkerGroup
 from anyplotlib.widgets import (
     Widget, RectangleWidget, CircleWidget, AnnularWidget,
-    CrosshairWidget, PolygonWidget, LabelWidget, ArrowWidget,
+    CrosshairWidget, PolygonWidget, LabelWidget, ArrowWidget, BrushWidget,
     VLineWidget, HLineWidget, RangeWidget, PointWidget, PlaneWidget,
 )
 
@@ -46,6 +46,7 @@ __all__ = [
     "MarkerRegistry", "MarkerGroup",
     "Widget", "RectangleWidget", "CircleWidget", "AnnularWidget",
     "CrosshairWidget", "PolygonWidget", "LabelWidget", "ArrowWidget",
+    "BrushWidget",
     "VLineWidget", "HLineWidget", "RangeWidget", "PointWidget", "PlaneWidget",
     "show_help", "get_color_cycle",
     "embed",

anyplotlib/_base_plot.py

@@ -95,8 +95,13 @@ class _BasePlot(_EventMixin):
 
         Replaces the repeated _tp / _targeted_push closures in every
         add_*_widget method.
+
+        Also back-links the widget to this plot so :meth:`Widget.remove` can
+        find its owner.  Every ``add_*_widget`` routes through here, so this is
+        the one place that has to know.
         """
         plot_ref, wid_id = self, widget._id
+        widget._plot = self
         def _push():
             if plot_ref._fig is not None:
                 fields = {k: v for k, v in widget._data.items()
@@ -124,6 +129,207 @@ class _PanelMixin:
         self._state["overlay_widgets"] = [w.to_dict() for w in self._widgets.values()]
         self._fig._push(self._id)
 
+    # ── geometry / coordinate conversion ──────────────────────────────────
+    #
+    # These mirror the layout constants and letterbox math in figure_esm.js
+    # (the PAD_* block near the top, and _imgFitRect).  They are here so that
+    # callers doing display-space work — pixel-sized handles, hit-test
+    # tolerances, screenshot-driven tests — do not each have to re-derive the
+    # renderer's layout in their own code and then drift from it.
+
+    #: Plot-area padding in CSS px: (left, right, top, bottom).
+    #: Matches ``PAD_L``/``PAD_R``/``PAD_T``/``PAD_B`` in ``figure_esm.js``.
+    PLOT_PADDING = (58, 12, 12, 42)
+
+    def _panel_size(self) -> tuple[float, float]:
+        """(panel_width, panel_height) in CSS px, from the figure's layout."""
+        import json
+
+        if self._fig is None:
+            raise RuntimeError("panel is not attached to a figure")
+        try:
+            layout = json.loads(self._fig.layout_json)
+            spec = next(s for s in layout["panel_specs"] if s["id"] == self._id)
+        except (AttributeError, KeyError, StopIteration, ValueError) as exc:
+            raise RuntimeError(f"no layout entry for panel {self._id!r}") from exc
+        return float(spec["panel_width"]), float(spec["panel_height"])
+
+    def _pad_top(self) -> float:
+        """Title-strip height. Mirrors ``_padT`` in figure_esm.js."""
+        pad_t = float(self.PLOT_PADDING[2])
+        title = self._state.get("title")
+        if not title:
+            return pad_t
+        size = float(self._state.get("title_size") or 11)
+        has_tex = "$" in str(title)
+        if size <= 11 and not has_tex:
+            return pad_t
+        import math
+
+        return max(pad_t, math.ceil(size * 1.3) + (4 if has_tex else 2))
+
+    def plot_box(self) -> dict:
+        """Return the panel's plot area in CSS pixels.
+
+        Returns
+        -------
+        dict
+            ``{"x", "y", "width", "height"}`` — the drawable rectangle
+            relative to the panel's top-left corner.  On a 2-D image panel it
+            is the *letterboxed image* rather than the whole padded area,
+            because that is what image coordinates actually map onto.
+
+        Raises
+        ------
+        RuntimeError
+            If the panel is not attached to a figure, so it has no layout.
+
+        Notes
+        -----
+        Computed from the figure's own layout, so it is exact for the sizes
+        the renderer was given.  A browser resized without a re-layout will
+        disagree.  Zoom and pan are *not* folded in — this is the box, not
+        the visible data window; :meth:`data_to_display` accounts for them.
+        """
+        left, right, top, bottom = self.PLOT_PADDING
+        pw, ph = self._panel_size()
+        pad_t = self._pad_top()
+
+        # A 2-D panel drops the left/right/bottom gutters when it has no
+        # physical axes to label — the image then fills the panel width.
+        # 1-D panels always draw axes.  Mirrors `hasPhysAxis` in the JS.
+        iw = self._state.get("image_width")
+        ih = self._state.get("image_height")
+        is_image = bool(iw and ih)
+        has_axes = (not is_image) or bool(
+            self._state.get("has_axes") or self._state.get("is_mesh")
+        )
+
+        x = float(left) if has_axes else 0.0
+        y = float(pad_t)
+        width = max((pw - left - right) if has_axes else pw, 1.0)
+        height = max(ph - pad_t - (bottom if has_axes else 0.0), 1.0)
+
+        # The colorbar strip and its gap come out of the image width.
+        if self._state.get("show_colorbar") and not self._state.get("is_rgb"):
+            label = self._state.get("colorbar_label")
+            label_w = round((self._state.get("colorbar_label_size") or 10) + 8) \
+                if label else 0
+            pad = self._state.get("colorbar_pad")
+            gap = 6.0 if pad is None else max(0.0, float(pad))
+            width = max(width - (16 + label_w) - gap, 1.0)
+
+        if is_image:
+            # Images are drawn "contain" — see _imgFitRect.
+            scale = min(width / float(iw), height / float(ih))
+            fit_w, fit_h = float(iw) * scale, float(ih) * scale
+            x += (width - fit_w) / 2.0
+            y += (height - fit_h) / 2.0
+            width, height = fit_w, fit_h
+
+        return {"x": x, "y": y, "width": width, "height": height}
+
+    def _visible_image_window(self) -> tuple[float, float, float, float]:
+        """(src_x, src_y, vis_w, vis_h) of the visible image region, in image px.
+
+        Mirrors the zoom/pan window in ``_imgToCanvas2d``.
+        """
+        iw = float(self._state.get("image_width") or 1)
+        ih = float(self._state.get("image_height") or 1)
+        zoom = float(self._state.get("zoom") or 1.0)
+        cx = float(self._state.get("center_x", 0.5))
+        cy = float(self._state.get("center_y", 0.5))
+        if zoom < 1.0:
+            # Zoomed out: the whole image, drawn smaller and centred. The box
+            # shrinks rather than the source window growing.
+            return 0.0, 0.0, iw, ih
+        vis_w, vis_h = iw / zoom, ih / zoom
+        src_x = max(0.0, min(iw - vis_w, cx * iw - vis_w / 2.0))
+        src_y = max(0.0, min(ih - vis_h, cy * ih - vis_h / 2.0))
+        return src_x, src_y, vis_w, vis_h
+
+    def data_to_display(self, points):
+        """Convert data coordinates to CSS pixels within the panel.
+
+        Parameters
+        ----------
+        points : array-like
+            A single ``(x, y)`` pair or an ``(N, 2)`` sequence of them.
+
+            On a 1-D panel these are axis values.  On a 2-D panel they are
+            **image-pixel coordinates** — the same space marker ``offsets``
+            and widget positions use — where integer *i* means the *centre*
+            of pixel *i*, not its leading edge.
+
+        Returns
+        -------
+        numpy.ndarray
+            Same shape as *points*, in panel pixels with the origin at the
+            panel's top-left corner and y increasing downwards.  Zoom and pan
+            are accounted for.
+        """
+        import numpy as np
+
+        pts = np.atleast_2d(np.asarray(points, dtype=float))
+        if pts.shape[-1] != 2:
+            raise ValueError(f"points must have shape (N, 2); got {pts.shape}")
+        box = self.plot_box()
+
+        if self._state.get("image_width") and self._state.get("image_height"):
+            zoom = float(self._state.get("zoom") or 1.0)
+            src_x, src_y, vis_w, vis_h = self._visible_image_window()
+            w = box["width"] * (zoom if zoom < 1.0 else 1.0)
+            h = box["height"] * (zoom if zoom < 1.0 else 1.0)
+            x0 = box["x"] + (box["width"] - w) / 2.0
+            y0 = box["y"] + (box["height"] - h) / 2.0
+            px = x0 + (pts[:, 0] + 0.5 - src_x) / vis_w * w
+            py = y0 + (pts[:, 1] + 0.5 - src_y) / vis_h * h
+        else:
+            xlo, xhi = self.get_xlim()
+            ylo, yhi = self.get_ylim()
+            px = box["x"] + (pts[:, 0] - xlo) / ((xhi - xlo) or 1.0) * box["width"]
+            # Screen y grows downwards, data y upwards.
+            py = box["y"] + (
+                1.0 - (pts[:, 1] - ylo) / ((yhi - ylo) or 1.0)
+            ) * box["height"]
+
+        out = np.column_stack([px, py])
+        return out if np.ndim(points) == 2 else out[0]
+
+    def display_to_data(self, points):
+        """Convert CSS pixels within the panel to data coordinates.
+
+        The inverse of :meth:`data_to_display`; same argument shapes and the
+        same per-panel-kind coordinate meaning.
+        """
+        import numpy as np
+
+        pts = np.atleast_2d(np.asarray(points, dtype=float))
+        if pts.shape[-1] != 2:
+            raise ValueError(f"points must have shape (N, 2); got {pts.shape}")
+        box = self.plot_box()
+
+        if self._state.get("image_width") and self._state.get("image_height"):
+            zoom = float(self._state.get("zoom") or 1.0)
+            src_x, src_y, vis_w, vis_h = self._visible_image_window()
+            w = box["width"] * (zoom if zoom < 1.0 else 1.0)
+            h = box["height"] * (zoom if zoom < 1.0 else 1.0)
+            x0 = box["x"] + (box["width"] - w) / 2.0
+            y0 = box["y"] + (box["height"] - h) / 2.0
+            dx = (pts[:, 0] - x0) / (w or 1.0) * vis_w + src_x - 0.5
+            dy = (pts[:, 1] - y0) / (h or 1.0) * vis_h + src_y - 0.5
+        else:
+            xlo, xhi = self.get_xlim()
+            ylo, yhi = self.get_ylim()
+            dx = xlo + (pts[:, 0] - box["x"]) / (box["width"] or 1.0) \
+                * ((xhi - xlo) or 1.0)
+            dy = ylo + (
+                1.0 - (pts[:, 1] - box["y"]) / (box["height"] or 1.0)
+            ) * ((yhi - ylo) or 1.0)
+
+        out = np.column_stack([dx, dy])
+        return out if np.ndim(points) == 2 else out[0]
+
     def set_tick_label_size(self, size: float) -> None:
         """Set the font size of the tick (axis number) labels in CSS pixels.
 

anyplotlib/_repr_utils.py

@@ -35,7 +35,17 @@ MAX_NOTEBOOK_WIDTH = 860
 # ---------------------------------------------------------------------------
 
 def _widget_state(widget) -> dict:
-    """Return a {name: value} dict of every synced traitlet."""
+    """Return a {name: value} dict of every synced traitlet.
+
+    A widget that keeps state outside its traits between renders may define
+    ``_sync_for_export()`` to reconcile it first.  ``Figure`` uses this to fold
+    widget geometry — pushed to JS as targeted events that never touch the
+    panel traits — back in, so a snapshot captures widgets where they are
+    rather than where they were created.
+    """
+    sync = getattr(widget, "_sync_for_export", None)
+    if callable(sync):
+        sync()
     state: dict = {}
     for name, trait in widget.traits(sync=True).items():
         if name.startswith("_"):

anyplotlib/_utils.py

@@ -7,6 +7,7 @@ Shared low-level utilities used across plot subpackages.
 from __future__ import annotations
 
 import functools
+import pathlib
 
 import numpy as np
 
@@ -21,6 +22,12 @@ _LINESTYLE_ALIASES: dict[str, str] = {
     "dashdot":   "dashdot",
     "step-mid":  "step-mid",
     "steps-mid": "step-mid",
+    # "no connecting line" — draw the per-point markers only, so a matplotlib
+    # ``linestyle="None", marker="o"`` scatter ports over unchanged.
+    # matplotlib also spells this ``""`` and ``" "``; those stay errors here
+    # because an empty style string is far more often a typo than an intent.
+    "none":      "none",
+    "None":      "none",
 }
 
 
@@ -42,7 +49,9 @@ def _norm_linestyle(ls: str) -> str:
     Accepted values
     ---------------
     ``"solid"`` / ``"-"``,  ``"dashed"`` / ``"--"``,
-    ``"dotted"`` / ``":"``,  ``"dashdot"`` / ``"-."``.
+    ``"dotted"`` / ``":"``,  ``"dashdot"`` / ``"-."``,
+    ``"step-mid"`` / ``"steps-mid"``, and ``"none"`` / ``"None"`` / ``""`` /
+    ``" "`` for no connecting line (markers only).
 
     Raises
     ------
@@ -53,8 +62,8 @@ def _norm_linestyle(ls: str) -> str:
     if canonical is None:
         raise ValueError(
             f"Unknown linestyle {ls!r}. Expected one of: "
-            "'solid', 'dashed', 'dotted', 'dashdot', 'step-mid' (alias: 'steps-mid') "
-            "or shorthands '-', '--', ':', '-.'."
+            "'solid', 'dashed', 'dotted', 'dashdot', 'step-mid' (alias: 'steps-mid'), "
+            "'none' (markers only) or shorthands '-', '--', ':', '-.'."
         )
     return canonical
 
@@ -81,6 +90,91 @@ def _to_rgba_u8(data: np.ndarray) -> np.ndarray:
     return np.ascontiguousarray(data)
 
 
+def _encode_png(rgba: np.ndarray) -> bytes:
+    """Encode an (H, W, 4) uint8 RGBA array as PNG bytes.
+
+    Stdlib only (``zlib`` + ``struct``) — Pillow is deliberately not a
+    dependency.  Every scanline uses filter type 0 (None), which costs a
+    little compression ratio but keeps this to a handful of lines; for the
+    smooth/procedural imagery textures are made of, zlib still shrinks the
+    raw RGBA by an order of magnitude, which is what matters when the bytes
+    have to cross a notebook comm as a base-64 data URL.
+    """
+    import struct
+    import zlib
+
+    h, w = rgba.shape[:2]
+    # One leading filter byte (0 = None) per scanline, then the RGBA row.
+    raw = np.zeros((h, w * 4 + 1), dtype=np.uint8)
+    raw[:, 1:] = rgba.reshape(h, w * 4)
+
+    def _chunk(tag: bytes, data: bytes) -> bytes:
+        return (struct.pack(">I", len(data)) + tag + data
+                + struct.pack(">I", zlib.crc32(tag + data) & 0xFFFFFFFF))
+
+    return (b"\x89PNG\r\n\x1a\n"
+            + _chunk(b"IHDR", struct.pack(">IIBBBBB", w, h, 8, 6, 0, 0, 0))
+            + _chunk(b"IDAT", zlib.compress(raw.tobytes(), 6))
+            + _chunk(b"IEND", b""))
+
+
+#: ``(magic prefix, MIME type)`` for the raster formats every browser decodes.
+_IMAGE_MAGIC: tuple = (
+    (b"\x89PNG\r\n\x1a\n", "image/png"),
+    (b"\xff\xd8\xff",      "image/jpeg"),
+    (b"GIF87a",            "image/gif"),
+    (b"GIF89a",            "image/gif"),
+)
+
+
+def _sniff_image_mime(blob: bytes) -> "str | None":
+    """Return the MIME type of *blob* from its magic bytes, or ``None``."""
+    for magic, mime in _IMAGE_MAGIC:
+        if blob.startswith(magic):
+            return mime
+    if blob[:4] == b"RIFF" and blob[8:12] == b"WEBP":
+        return "image/webp"
+    return None
+
+
+def _image_to_data_url(image) -> str:
+    """Return a ``data:`` URL the browser can decode into a texture.
+
+    Accepts, in order of preference:
+
+    * an already-encoded image — ``bytes`` of a PNG/JPEG/GIF/WebP, or a
+      ``str``/``os.PathLike`` path to such a file — passed through verbatim,
+      so a photo stays JPEG-compressed instead of being re-encoded;
+    * a ``data:`` URL string, returned unchanged;
+    * an ``(H, W, 3|4)`` array (uint8, or float 0–1) — anything
+      :func:`_to_rgba_u8` accepts, which includes a PIL image (it exposes the
+      array interface) — encoded as PNG.
+    """
+    import base64
+    import os
+
+    if isinstance(image, (bytes, bytearray, memoryview)):
+        blob = bytes(image)
+        mime = _sniff_image_mime(blob)
+        if mime is None:
+            raise ValueError(
+                "texture bytes are not a recognised PNG/JPEG/GIF/WebP image")
+        return f"data:{mime};base64," + base64.b64encode(blob).decode("ascii")
+
+    if isinstance(image, (str, os.PathLike)):
+        if isinstance(image, str) and image.startswith("data:"):
+            return image
+        blob = pathlib.Path(image).read_bytes()
+        mime = _sniff_image_mime(blob)
+        if mime is None:
+            raise ValueError(
+                f"{os.fspath(image)!r} is not a PNG/JPEG/GIF/WebP image")
+        return f"data:{mime};base64," + base64.b64encode(blob).decode("ascii")
+
+    png = _encode_png(_to_rgba_u8(np.asarray(image)))
+    return "data:image/png;base64," + base64.b64encode(png).decode("ascii")
+
+
 def _normalize_image(data: np.ndarray, clim: "tuple | None" = None):
     """Normalise data to uint8, returning (img_u8, vmin, vmax) where vmin/vmax are
     the QUANTISATION endpoints the 8-bit codes span (the caller stores them as

anyplotlib/axes/_axes.py

@@ -116,7 +116,10 @@ class Axes:
                      colormap: str = "viridis",
                      x_label: str = "x", y_label: str = "y", z_label: str = "z",
                      azimuth: float = -60.0, elevation: float = 30.0,
-                     zoom: float = 1.0) -> "Plot3D":
+                     zoom: float = 1.0,
+                     bounds=None,
+                     texture=None,
+                     gpu: "str | bool" = "auto") -> "Plot3D":
         """Attach a 3-D surface to this axes cell.
 
         Parameters
@@ -128,6 +131,20 @@ class Axes:
         x_label, y_label, z_label : str, optional  Axis labels.
         azimuth, elevation : float, optional  Initial camera angles in degrees.
         zoom : float, optional  Initial zoom factor.
+        bounds : ((xmin, xmax), (ymin, ymax), (zmin, zmax)), optional
+            Fix the axes bounds instead of fitting them to the data.  Pass
+            ``((-1, 1),) * 3`` for a unit sphere so it projects as a true
+            circle rather than being stretched to fill the panel.
+        texture : array-like, bytes, or path, optional
+            Image to wrap around the surface — shorthand for
+            :meth:`~anyplotlib.Plot3D.set_texture`, which takes the mapping,
+            shading, and culling options.
+        gpu : ``"auto"`` | bool, optional
+            WebGPU acceleration policy for a *textured* surface (a
+            colormapped one always renders on Canvas2D).  ``"auto"`` (default)
+            uses the GPU when available above ~2k triangles; ``True`` always
+            attempts it; ``False`` forces Canvas2D.  Falls back silently when
+            WebGPU is unavailable — check :attr:`Plot3D.gpu_active`.
 
         Returns
         -------
@@ -135,7 +152,8 @@ class Axes:
         """
         plot = Plot3D("surface", X, Y, Z, colormap=colormap,
                       x_label=x_label, y_label=y_label, z_label=z_label,
-                      azimuth=azimuth, elevation=elevation, zoom=zoom)
+                      azimuth=azimuth, elevation=elevation, zoom=zoom,
+                      bounds=bounds, texture=texture, gpu=gpu)
         self._attach(plot)
         return plot
 
@@ -309,7 +327,9 @@ class Axes:
         linestyle : str, optional
             Dash pattern.  Accepted values: ``"solid"`` (``"-"``),
             ``"dashed"`` (``"--"``), ``"dotted"`` (``":"``),
-            ``"dashdot"`` (``"-."``) .  Default ``"solid"``.
+            ``"dashdot"`` (``"-."``), or ``"none"`` to draw no connecting
+            line at all — pair it with *marker* for a scatter.
+            Default ``"solid"``.
         ls : str, optional
             Short alias for *linestyle*.  Takes precedence if both are given.
         alpha : float, optional

anyplotlib/callbacks.py

@@ -99,6 +99,12 @@ class Event:
     image_height: int | None = None
     display_width: int | None = None    # panel device px (JS) → tile output resolution
     display_height: int | None = None
+    # Camera (Plot3D orbit) — the angles the drag just produced, in degrees.
+    # The JS has always sent these alongside `zoom`; without them a handler
+    # cannot react to an orbit, because a JS-side drag does not sync back into
+    # Plot3D._state.
+    azimuth: float | None = None
+    elevation: float | None = None
     # Key
     key: str | None = None
     last_widget_id: str | None = None

anyplotlib/figure/_figure.py

@@ -671,6 +671,8 @@ class Figure(anywidget.AnyWidget, _EventMixin):
                 image_height=msg.get("image_height"),
                 display_width=msg.get("display_width"),
                 display_height=msg.get("display_height"),
+                azimuth=msg.get("azimuth"),
+                elevation=msg.get("elevation"),
                 key=msg.get("key"),
                 last_widget_id=msg.get("last_widget_id"),
                 target=msg.get("target"),
@@ -786,12 +788,36 @@ class Figure(anywidget.AnyWidget, _EventMixin):
         return [dict(m) for m in self._figure_markers]
 
     def _push_widget(self, panel_id: str, widget_id: str, fields: dict) -> None:
-        """Send a targeted widget-position update to JS (no image data)."""
+        """Send a targeted widget-position update to JS (no image data).
+
+        This writes ``event_json`` only — deliberately, because re-serialising
+        a whole panel (image bytes included) on every drag frame is exactly
+        what this path exists to avoid.  The consequence is that
+        ``panel_<id>_json`` carries stale widget geometry between plot-level
+        pushes; :meth:`_sync_for_export` reconciles it before any snapshot.
+        """
         payload = {"source": "python", "panel_id": panel_id,
                    "widget_id": widget_id}
         payload.update(fields)
         self.event_json = json.dumps(payload)
 
+    def _sync_for_export(self) -> None:
+        """Refresh every panel trait so a snapshot sees current widget state.
+
+        Widget moves reach JS as targeted ``event_json`` updates that never
+        touch the panel traits (see :meth:`_push_widget`), so ``save_html`` /
+        ``to_html`` / ``figure_state`` would otherwise capture every widget at
+        the position it was *created* at rather than where it now is.  Python
+        holds the authoritative geometry — a JS-side drag writes back through
+        ``_dispatch_event`` — so re-pushing each panel is enough to reconcile.
+
+        Called from ``_repr_utils._widget_state``, the one chokepoint every
+        export path goes through.  The live Jupyter path deliberately keeps
+        using targeted pushes and does not pay this cost.
+        """
+        for panel_id in list(self._plots_map):
+            self._push(panel_id)
+
     def _push_panel_fields(self, panel_id: str, fields: dict) -> None:
         """Apply a small set of changed *fields* to a panel, then push once.