anyplotlib 0.6.0__tar.gz → 0.7.1__tar.gz

{anyplotlib-0.6.0 → anyplotlib-0.7.1}/CHANGELOG.rst

@@ -10,6 +10,46 @@ Fragment files in ``upcoming_changes/`` are assembled into this file by
 
 .. towncrier release notes start
 
+0.7.1 (2026-08-02)
+==================
+
+Bug Fixes
+---------
+
+- Fixed ``save_html`` / ``to_html`` / ``figure_state`` dropping image pixels
+  under the Electron binary transport: the snapshot kept the ``"\x00bin:"``
+  change-tokens whose bytes only ever ride the live PLOTBIN channel, so an
+  overlay added with :meth:`~anyplotlib.Plot2D.add_layer` did not render in the
+  exported document. (`#52 <https://github.com/CSSFrancis/anyplotlib/pull/52>`_)
+
+
+Documentation
+-------------
+
+- Fixed the documentation build failing on
+  :class:`~anyplotlib.keys.KeyOverlay`, whose ``id`` and ``name`` were described
+  both in the class docstring and by the properties themselves — a duplicate
+  object description, which the build treats as an error. (`#53 <https://github.com/CSSFrancis/anyplotlib/pull/53>`_)
+
+
+0.7.0 (2026-07-31)
+==================
+
+New Features
+------------
+
+- Added :meth:`~anyplotlib.Plot2D.add_key` for pinning a floating image *key* over
+  a panel — an inverse pole figure triangle over an orientation map, a hue wheel
+  over a polarization field, a phase key over a segmentation.  A key is the scale
+  bar's sibling: it floats in screen space and neither pans nor zooms with the
+  data, it takes an RGBA image so a triangle or a disc needs no rectangular card
+  around it, and ``labels=`` annotates the picture itself (an IPF triangle's
+  corner indices) in fractions of the key image.  Optional ``bgcolor`` /
+  ``border`` / ``alpha`` give it a card when the data underneath is busy, and
+  ``hover_only=True`` reveals it only while the pointer is over the panel.
+  Available on every panel type, and included in PNG export.
+
+
 0.6.0 (2026-07-31)
 ==================
 

anyplotlib-0.7.1/Examples/PlotTypes/plot_key_overlays.py

@@ -0,0 +1,169 @@
+"""
+Floating keys — IPF triangles and colour wheels
+===============================================
+
+Some plots are coloured by a *direction*, not by a magnitude, and a colorbar
+cannot say what the colours mean.  An orientation map is coloured by which
+crystal axis points at you; a polarization map by which way the moment lies in
+the plane.  Both need a small picture as their legend: an inverse pole figure
+triangle, or a hue wheel.
+
+:meth:`~anyplotlib.Plot2D.add_key` pins that picture over the panel in *screen*
+space — it does not pan or zoom with the data, exactly like the scale bar it is
+modelled on.
+
+This is deliberately not :meth:`~anyplotlib.Figure.add_inset`, which is a
+draggable window with a title bar and its own canvas stack.  That is the right
+tool when the overlay is a live plot; a key is a static picture that should
+read as part of the figure.
+"""
+import numpy as np
+
+import anyplotlib as apl
+
+# %%
+# The IPF colour key
+# ------------------
+# The standard cubic stereographic triangle.  Each pixel's colour is its
+# barycentric distance to the three corners, which is the classic IPF key: a
+# grain pointing [1 0 0] at the detector reads red, [1 1 0] green, [1 1 1] blue.
+#
+# The triangle is built as an ``(H, W, 4)`` RGBA array, and **alpha 0 outside
+# the triangle** is what lets it sit on the map without a rectangular card
+# around it.
+
+KEY_N = 220
+
+
+def ipf_triangle(n=KEY_N):
+    """RGBA image of the 001–011–111 stereographic triangle."""
+    yy, xx = np.mgrid[0:n, 0:n]
+    u = xx / (n - 1)
+    v = 1.0 - yy / (n - 1)
+    inside = v <= u + 1e-9                       # lower-right half
+
+    # Barycentric-ish weights: distance to each corner, normalised.
+    d100 = np.hypot(u, v)                        # corner (0, 0)
+    d110 = np.hypot(u - 1.0, v)                  # corner (1, 0)
+    d111 = np.hypot(u - 1.0, v - 1.0)            # corner (1, 1)
+    far = np.maximum.reduce([d100, d110, d111])
+    rgb = np.stack([1 - d100 / far, 1 - d110 / far, 1 - d111 / far], -1)
+    rgb /= rgb.max(-1, keepdims=True) + 1e-9     # full saturation at the corners
+
+    img = np.zeros((n, n, 4), np.uint8)
+    img[..., :3] = np.clip(rgb, 0, 1) * 255
+    img[..., 3] = np.where(inside, 255, 0)
+    return img
+
+
+# %%
+# A synthetic orientation map
+# ---------------------------
+# Voronoi grains, each with a random orientation, coloured through the same key
+# so the map and its legend agree by construction.
+
+rng = np.random.default_rng(11)
+H, W, NGRAIN = 210, 280, 40
+
+cy, cx = rng.uniform(0, H, NGRAIN), rng.uniform(0, W, NGRAIN)
+yy, xx = np.mgrid[0:H, 0:W]
+grain = np.hypot(yy[..., None] - cy, xx[..., None] - cx).argmin(-1)
+
+# Each grain gets a point in the triangle, then reads its colour off the key.
+gu = rng.uniform(0, 1, NGRAIN)
+gv = rng.uniform(0, 1, NGRAIN) * gu              # keep it inside v <= u
+key_img = ipf_triangle()
+kx = np.clip((gu * (KEY_N - 1)).astype(int), 0, KEY_N - 1)
+ky = np.clip(((1 - gv) * (KEY_N - 1)).astype(int), 0, KEY_N - 1)
+grain_rgb = key_img[ky, kx, :3]
+ipf_map = grain_rgb[grain]                       # (H, W, 3) true colour
+
+# %%
+# Pinning the key
+# ---------------
+# ``labels`` draws text *inside* the picture, positioned as fractions of the
+# key image, so the corner indices stay on the corners at any ``size``.
+
+fig, ax = apl.subplots(1, 1, figsize=(520, 420))
+vmap = ax.imshow(ipf_map)
+vmap.set_title("orientation map")
+
+vmap.add_key(
+    key_img,
+    corner="bottom-right",
+    size=0.34,
+    # `align` keeps a label inside the key: centring text on a corner would
+    # hang half of it off the edge, where the panel clips it.
+    labels=[
+        {"x": 0.02, "y": 0.93, "text": "[1 0 0]", "align": "left"},
+        {"x": 0.98, "y": 0.93, "text": "[1 1 0]", "align": "right"},
+        {"x": 0.98, "y": 0.08, "text": "[1 1 1]", "align": "right"},
+    ],
+    name="ipf",
+)
+
+fig
+
+# %%
+# A colour wheel over a polarization map
+# --------------------------------------
+# Same mechanism, different legend.  Here the key gets a translucent card
+# (``bgcolor``) because the field underneath is saturated everywhere and a bare
+# wheel would fight with it.
+
+def hue_wheel(n=KEY_N):
+    """RGBA colour wheel: hue = in-plane angle, value = magnitude."""
+    yy, xx = np.mgrid[0:n, 0:n]
+    ang = (np.arctan2(-(yy - n / 2), xx - n / 2) + np.pi) / (2 * np.pi)
+    rad = np.hypot(yy - n / 2, xx - n / 2) / (n / 2)
+    h6 = ang * 6.0
+    chan = np.clip(
+        np.abs(((h6 + np.array([0, 4, 2])[:, None, None]) % 6) - 3) - 1, 0, 1)
+    img = np.zeros((n, n, 4), np.uint8)
+    img[..., :3] = chan.transpose(1, 2, 0) * 255 * np.clip(rad, 0, 1)[..., None]
+    img[..., 3] = np.where(rad <= 1.0, 255, 0)
+    return img
+
+
+# A vortex: the moment angle winds once around the centre.
+ang = np.arctan2(yy - H / 2, xx - W / 2)
+mag = np.clip(np.hypot(yy - H / 2, xx - W / 2) / (0.5 * min(H, W)), 0, 1)
+a6 = ((ang + np.pi) / (2 * np.pi)) * 6.0
+chan = np.clip(np.abs(((a6 + np.array([0, 4, 2])[:, None, None]) % 6) - 3) - 1, 0, 1)
+polar_map = (chan.transpose(1, 2, 0) * 255 * (0.3 + 0.7 * mag)[..., None]).astype(np.uint8)
+
+fig2, ax2 = apl.subplots(1, 1, figsize=(520, 420))
+vpol = ax2.imshow(polar_map)
+vpol.set_title("in-plane magnetic polarization")
+
+vpol.add_key(
+    hue_wheel(),
+    corner="top-right",
+    size=0.26,
+    bgcolor="rgba(0,0,0,0.45)",     # legible over a busy field
+    border="#ffffff",
+    label="moment direction",
+    labels=[
+        (0.5, 0.06, "N"), (0.94, 0.5, "E"),
+        (0.5, 0.94, "S"), (0.06, 0.5, "W"),
+    ],
+    name="wheel",
+)
+
+fig2
+
+# %%
+# Keeping it out of the way
+# -------------------------
+# ``hover_only=True`` shows the key only while the pointer is over the panel —
+# a reading aid that does not sit on the data while you study it.  PNG export
+# renders the panel as though the pointer were there, so an exported figure
+# still carries the key.
+#
+# Everything is live: :meth:`~anyplotlib.KeyOverlay.set` restyles a key without
+# re-sending the picture, and :meth:`~anyplotlib.KeyOverlay.set_image` swaps
+# the picture without disturbing the placement::
+#
+#     key = vmap.get_key("ipf")
+#     key.set(size=0.4, corner="top-left")
+#     key.visible = False

{anyplotlib-0.6.0 → anyplotlib-0.7.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: anyplotlib
-Version: 0.6.0
+Version: 0.7.1
 Summary: A plotting library using python, javascript and anywidget for performant in browser plotting.
 Project-URL: Homepage, https://cssfrancis.github.io/anyplotlib/
 Project-URL: Repository, https://github.com/CSSFrancis/anyplotlib

{anyplotlib-0.6.0 → anyplotlib-0.7.1}/anyplotlib/FIGURE_ESM.md

@@ -1,6 +1,6 @@
 # FIGURE_ESM.md — Navigator for `figure_esm.js`
 
-`figure_esm.js` is **~9,300 lines** and one big closure. Everything lives inside
+`figure_esm.js` is **~9,470 lines** and one big closure. Everything lives inside
 `function render({ model, el })` so that all helpers share the same scope
 (`theme`, `PAD_*`, `panels` Map, etc.).  This document is a section map so you
 can jump straight to the relevant code without reading the whole file.
@@ -55,23 +55,24 @@ Rule 5 – Text never clips.  Optional gutters earn real layout space:
 | **2D gutter geometry**: `_cbWidth` / `_cbGap` / `_padT` / `_titlePx` | 301 / 313 / 323 / 333 |
 | **Layout engine** `applyLayout` | 774 |
 | `_buildCanvasStack` | 857 |
-| `_createPanelDOM` | 989 |
-| `_createInsetDOM` / `_applyAllInsetStates` | 1118 / 1500 |
-| `_resizePanelDOM` | 2213 |
-| **2D drawing**: `_imgFitRect` | 2372 |
-| `draw2d` | 2680 |
-| `drawScaleBar2d` / `drawColorbar2d` | 2875 / 2961 |
-| `_drawAxes2d` (ticks, labels, title) | 3016 |
-| `drawOverlay2d` / `drawMarkers2d` | 3169 / 3333 |
-| **Image layers**: `_layerBytes` / `_layerBitmap` / `_drawLayers2d` | 2500 / 2524 / 2585 |
+| `_createPanelDOM` | 999 |
+| `_createInsetDOM` / `_applyAllInsetStates` | 1129 / 1512 |
+| `_resizePanelDOM` | 2225 |
+| **2D drawing**: `_imgFitRect` | 2384 |
+| `draw2d` | 2692 |
+| `drawScaleBar2d` / `drawColorbar2d` | 2887 / 3125 |
+| **Floating keys**: `_keyEnsure` / `_keyRect` / `drawKeys` | 2986 / 3009 / 3022 |
+| `_drawAxes2d` (ticks, labels, title) | 3180 |
+| `drawOverlay2d` / `drawMarkers2d` | 3333 / 3497 |
+| **Image layers**: `_layerBytes` / `_layerBitmap` / `_drawLayers2d` | 2512 / 2536 / 2597 |
 | Binary-bytes splice: `_spliceBinaryBytes` / `_registerBinaryPixelListeners` | 730 / 761 |
-| **3D drawing**: `draw3d` | 5072 |
-| Event emission `_emitEvent` | 5909 |
-| 3D event handlers `_attachEvents3d` | 5961 |
-| **1D drawing**: `draw1d` | 6182 |
-| `_drawLine` (1D series + markers) | 6335 |
-| `drawOverlay1d` / `drawMarkers1d` | 6628 / 6712 |
-| Marker hit-test `_markerHitTest2d` | 6980 |
+| **3D drawing**: `draw3d` | 5236 |
+| Event emission `_emitEvent` | 6073 |
+| 3D event handlers `_attachEvents3d` | 6125 |
+| **1D drawing**: `draw1d` | 6346 |
+| `_drawLine` (1D series + markers) | 6499 |
+| `drawOverlay1d` / `drawMarkers1d` | 6792 / 6876 |
+| Marker hit-test `_markerHitTest2d` | 7144 |
 
 > **`raster` marker (1D/PlotXY)** — `drawMarkers1d` has a `type==='raster'`
 > branch that blits a single RGBA image across data-coord `extent` (the fast
@@ -80,16 +81,16 @@ Rule 5 – Text never clips.  Optional gutters earn real layout space:
 > redraws never re-transmit them; the decoded `OffscreenCanvas` is cached on
 > the marker set (`ms._rasterBmp`/`_rasterKey`). The shared `clip_path` block
 > clips it to a curved sector.
-| Panel event dispatch `_attachPanelEvents` | 7237 |
-| 2D events `_attachEvents2d` | 7261 |
-| 1D events `_attachEvents1d` | 7645 |
-| 2D widget drag `_ovHitTest2d` / `_doDrag2d` | 7917 / 8190 |
-| **Brush strokes**: `_brushLiveBegin` / `_brushCommit` / `_brushErase` / `_brushPaintAt` | 8103 / 8117 / 8146 / 8181 |
-| 1D widget drag `_canvasXToFrac1d` … / snapping `_snapVal` | 8313 / 8386 |
-| Shared-axis propagation `_getShareGroups` | 8457 |
-| Figure resize `_applyFigResizeDOM` | 8521 |
-| **Bar chart**: `_barGeom` / `drawBar` / `_attachEventsBar` | 8712 / 8775 / 9151 |
-| Generic redraw `_redrawPanel` | 9341 |
+| Panel event dispatch `_attachPanelEvents` | 7401 |
+| 2D events `_attachEvents2d` | 7443 |
+| 1D events `_attachEvents1d` | 7827 |
+| 2D widget drag `_ovHitTest2d` / `_doDrag2d` | 8099 / 8372 |
+| **Brush strokes**: `_brushLiveBegin` / `_brushCommit` / `_brushErase` / `_brushPaintAt` | 8285 / 8299 / 8328 / 8363 |
+| 1D widget drag `_canvasXToFrac1d` … / snapping `_snapVal` | 8495 / 8568 |
+| Shared-axis propagation `_getShareGroups` | 8639 |
+| Figure resize `_applyFigResizeDOM` | 8703 |
+| **Bar chart**: `_barGeom` / `drawBar` / `_attachEventsBar` | 8894 / 8957 / 9333 |
+| Generic redraw `_redrawPanel` | 9523 |
 
 > **`brush` widget (2-D)** — the one widget whose drag is *modal*, and the one
 > that must NOT write the model per tick. `_ovHitTest2d` takes an extra `mods`

{anyplotlib-0.6.0 → anyplotlib-0.7.1}/anyplotlib/__init__.py

@@ -15,6 +15,7 @@ from anyplotlib.plotxy import PlotXY
 from anyplotlib.callbacks import CallbackRegistry, Event
 from anyplotlib import embed
 from anyplotlib.markers import MarkerRegistry, MarkerGroup
+from anyplotlib.keys import KeyOverlay
 from anyplotlib.widgets import (
     Widget, RectangleWidget, CircleWidget, AnnularWidget,
     CrosshairWidget, PolygonWidget, LabelWidget, ArrowWidget, BrushWidget,
@@ -43,7 +44,7 @@ __all__ = [
     "Axes", "InsetAxes", "Plot1D", "Plot2D", "PlotMesh", "Plot3D", "PlotBar",
     "Line1D",
     "CallbackRegistry", "Event",
-    "MarkerRegistry", "MarkerGroup",
+    "MarkerRegistry", "MarkerGroup", "KeyOverlay",
     "Widget", "RectangleWidget", "CircleWidget", "AnnularWidget",
     "CrosshairWidget", "PolygonWidget", "LabelWidget", "ArrowWidget",
     "BrushWidget",

{anyplotlib-0.6.0 → anyplotlib-0.7.1}/anyplotlib/_base_plot.py

@@ -76,6 +76,172 @@ class _BasePlot(_EventMixin):
         self._state["axis_visible"] = True
         self._push()
 
+    # ------------------------------------------------------------------
+    # Floating image keys (see anyplotlib/keys.py)
+    # ------------------------------------------------------------------
+    def add_key(self, image, *, corner: str = "top-right", anchor=None,
+                size: float = 0.22, margin: float = 10.0,
+                bgcolor=None, border=None, border_width: float = 1.0,
+                radius: float = 4.0, alpha: float = 1.0,
+                hover_only: bool = False, visible: bool = True,
+                label=None, label_size: float = 10.0, label_color=None,
+                labels=None, name=None) -> "KeyOverlay":
+        """Pin a floating image key over this panel.
+
+        A key is a small picture that floats in screen space over the plot
+        area — it does not pan or zoom with the data.  Use it for a colour
+        legend a colorbar cannot express: an inverse pole figure triangle over
+        an orientation map, a hue wheel over a polarization field, a phase key
+        over a segmentation::
+
+            key = plot.add_key(ipf_triangle, corner="bottom-right", size=0.28)
+            wheel = plot.add_key(hue_wheel, corner="top-left",
+                                 bgcolor="none", hover_only=True)
+
+        This is the lightweight sibling of :meth:`Figure.add_inset`.  An inset
+        is a draggable window with a title bar and its own canvas stack — the
+        right tool when the overlay is a live plot.  A key is a static picture
+        with no chrome unless you ask for it, so it reads as part of the
+        figure rather than as a floating panel.
+
+        Parameters
+        ----------
+        image : array-like, bytes, or path
+            An ``(H, W, 3|4)`` colour array (uint8, or float 0–1), the raw
+            bytes of a PNG/JPEG/GIF/WebP, or a path to such a file.  An RGBA
+            array is the usual choice: alpha 0 outside the shape lets a
+            triangle or a disc sit on the image without a rectangular card
+            around it.
+        corner : str, optional
+            ``"top-right"`` (default), ``"top-left"``, ``"bottom-right"`` or
+            ``"bottom-left"``.  Ignored when *anchor* is given.
+        anchor : (x_frac, y_frac), optional
+            Free placement: the key's centre as a fraction of the plot area,
+            from its top-left.  Overrides *corner*.
+        size : float, optional
+            Width as a fraction of the plot area's **shorter** side, so a key
+            keeps its proportions when the panel is resized.  Default 0.22.
+            Height follows the image's aspect ratio.
+        margin : float, optional
+            Gap in CSS px between the key and the plot-area edge, for corner
+            placement.  Default 10.
+        bgcolor : str, optional
+            CSS colour painted behind the image — e.g. ``"rgba(0,0,0,0.45)"``
+            for a legible card over busy data.  Default ``None`` (fully
+            transparent); ``"none"`` means the same thing.
+        border : str, optional
+            CSS colour for a hairline around the card.  Default ``None``.
+        border_width : float, optional
+            Border stroke width in px.  Default 1.
+        radius : float, optional
+            Corner radius of the card in px.  Default 4.
+        alpha : float, optional
+            Opacity of the whole key, 0–1.  Default 1.
+        hover_only : bool, optional
+            Show the key only while the pointer is over the panel.  Default
+            ``False``.  Useful for a reading aid you do not want sitting over
+            the data all the time.  PNG export renders the panel as though the
+            pointer were over it, so a hover-only key **is** included in an
+            exported figure — what you save is what you see while reading.
+        visible : bool, optional
+            Draw the key at all.  Default ``True``.
+        label : str, optional
+            Caption drawn under the image, mini-TeX enabled like axis labels.
+        label_size : float, optional
+            Caption size in px.  Default 10.
+        label_color : str, optional
+            Caption colour.  Default ``None`` (the theme's tick-label colour).
+        labels : list, optional
+            Text drawn *inside* the key, for annotating the picture itself —
+            an IPF triangle's corner indices, a wheel's compass points.  Each
+            entry is ``(x, y, text)`` or a dict with those keys plus optional
+            ``size`` / ``color`` / ``align``.  ``x`` and ``y`` are fractions of
+            the key image, so the text follows the picture when the key is
+            resized.  Mini-TeX works here as in any label::
+
+                tri.add_key(ipf, labels=[
+                    (0.02, 0.97, "[1 0 0]"),
+                    (0.98, 0.97, "[1 1 0]"),
+                    (0.98, 0.03, "[1 1 1]"),
+                ])
+        name : str, optional
+            Handle for :meth:`get_key`.  Defaults to the generated id.
+
+        Returns
+        -------
+        KeyOverlay
+
+        See Also
+        --------
+        remove_key, list_keys, get_key
+        anyplotlib.Figure.add_inset : a full floating axes, for live plots.
+        """
+        from anyplotlib._utils import _image_to_data_url
+        from anyplotlib.keys import KeyOverlay, _validate
+
+        fields = _validate(dict(
+            corner=corner, anchor=anchor, size=size, margin=margin,
+            bgcolor=bgcolor, border=border, border_width=border_width,
+            radius=radius, alpha=alpha, hover_only=hover_only,
+            visible=visible, label=label, label_size=label_size,
+            label_color=label_color, labels=labels))
+        key = KeyOverlay(self, _image_to_data_url(image), name=name, **fields)
+        if any(k.name == key.name for k in self._key_map.values()):
+            raise ValueError(f"a key named {key.name!r} already exists on this "
+                             "panel; pass a different name=")
+        self._key_map[key.id] = key
+        self._push_keys()
+        return key
+
+    @property
+    def _key_map(self) -> dict:
+        """Lazily-created ``{id: KeyOverlay}`` — panels predate this feature."""
+        if getattr(self, "_keys_dict", None) is None:
+            self._keys_dict = {}
+        return self._keys_dict
+
+    def _push_keys(self) -> None:
+        """Re-serialise the key list + image table, then push.
+
+        The pictures ride the geometry channel under ``key_images`` so that
+        restyling a key — or a hover toggle — never re-transmits them.
+        """
+        keys = list(self._key_map.values())
+        self._state["keys"] = [k.to_dict() for k in keys]
+        self._state["key_images"] = {k.id: k.image_url for k in keys}
+        self._push()
+
+    def get_key(self, name):
+        """Return the key with this *name* (or id).
+
+        Raises
+        ------
+        KeyError
+            If no key matches.
+        """
+        for k in self._key_map.values():
+            if k.name == name or k.id == name:
+                return k
+        raise KeyError(f"no key named {name!r}")
+
+    def remove_key(self, key) -> None:
+        """Remove a key, by object, name, or id."""
+        from anyplotlib.keys import KeyOverlay
+        kid = key.id if isinstance(key, KeyOverlay) else self.get_key(key).id
+        if kid not in self._key_map:
+            raise KeyError(kid)
+        del self._key_map[kid]
+        self._push_keys()
+
+    def list_keys(self) -> list:
+        """Every key on this panel, in creation order."""
+        return list(self._key_map.values())
+
+    def clear_keys(self) -> None:
+        """Remove every key from this panel."""
+        self._key_map.clear()
+        self._push_keys()
+
     @contextmanager
     def _python_view_push(self):
         """Context manager for view setters that must signal _view_from_python.

{anyplotlib-0.6.0 → anyplotlib-0.7.1}/anyplotlib/figure/_figure.py

@@ -300,7 +300,7 @@ class Figure(anywidget.AnyWidget, _EventMixin):
         self._push(pid)
         self._push_layout()
 
-    def _push(self, panel_id: str) -> None:
+    def _push(self, panel_id: str, *, resolve_pixels: bool = False) -> None:
         """Serialise one panel and write to its trait.
 
         Inside a :meth:`batch` block, pushes are coalesced: each panel is
@@ -309,6 +309,14 @@ class Figure(anywidget.AnyWidget, _EventMixin):
         many per-frame pushes of a linked-view update (set_data + set_title +
         widget moves on the same panel) into one serialise/transfer per panel
         — the dominant cost over a Pyodide comm boundary.
+
+        Parameters
+        ----------
+        resolve_pixels : bool, optional
+            Force pixel change-tokens to be materialised to inline base64 even
+            when the binary transport is live.  Set by :meth:`_sync_for_export`
+            because a snapshot has no PLOTBIN channel to carry the bytes; see
+            the token discussion below.
         """
         plot = self._plots_map.get(panel_id)
         if plot is None:
@@ -329,7 +337,15 @@ class Figure(anywidget.AnyWidget, _EventMixin):
         # save_html / Jupyter figure with no binary channel — materialise the
         # real base64 inline so the pixels actually travel. ``_binary_wire``
         # matches the producer's gate (``Plot2D._encode_pixels``).
-        if geom_keys and not _binary_wire() and hasattr(plot, "resolve_pixel_tokens"):
+        #
+        # ``resolve_pixels`` overrides that gate for an EXPORT. A snapshot is by
+        # definition off-wire: whatever PLOTBIN would have delivered never
+        # arrives, so a token left in the state is a dangling reference and the
+        # pixels are simply lost. The gate reads a process-global env var, which
+        # is on in a host app even while THIS push is serialising a snapshot —
+        # so the export has to say so explicitly.
+        if (geom_keys and (resolve_pixels or not _binary_wire())
+                and hasattr(plot, "resolve_pixel_tokens")):
             plot.resolve_pixel_tokens(state)
         if geom_keys and self.has_trait(gname):
             # Split heavy geometry into its own channel.  Detect change by
@@ -814,9 +830,17 @@ class Figure(anywidget.AnyWidget, _EventMixin):
         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.
+
+        The re-push passes ``resolve_pixels=True``: this rewrites the panel
+        traits, and under a live binary transport an ordinary push leaves pixel
+        change-tokens in place for PLOTBIN to fill in.  A snapshot has no
+        PLOTBIN, so those tokens would be dangling — and because the re-push
+        rewrites ``panel_<id>_json`` unconditionally it would also undo any
+        materialisation the caller did beforehand.  An export always ships real
+        pixels.
         """
         for panel_id in list(self._plots_map):
-            self._push(panel_id)
+            self._push(panel_id, resolve_pixels=True)
 
     def _push_panel_fields(self, panel_id: str, fields: dict) -> None:
         """Apply a small set of changed *fields* to a panel, then push once.