shape-plotters 0.1.0__tar.gz → 0.2.0__tar.gz

{shape_plotters-0.1.0 → shape_plotters-0.2.0}/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 Notable changes to shape-plotters. Versions follow semantic versioning.
 
+## 0.2.0
+
+Interactive performance. Measured in a real window on the development PC
+(matplotlib 3.11): a drag step drops from about 110 ms to 33-46 ms, a click
+on a slider from about 300 ms to about 105 ms.
+
+### Changed
+
+- **Slider drags are blitted.** While a slider is dragged, only the curves,
+  the stats text and that slider are redrawn; ticks, legends and the other
+  widgets come from a cached background. The axes hold still during the drag
+  and refit on release; if the shape outgrows the view, the view jumps out
+  once to a looser fit. During a drag the curves draw on top of legends.
+  Everything outside a drag, including saved PNGs, is drawn exactly as before.
+- **A click costs one redraw instead of three.** Every mouse press used to
+  trigger two extra full redraws, one per Z/N text box.
+
 ## 0.1.0
 
 First release.

{shape_plotters-0.1.0 → shape_plotters-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: shape-plotters
-Version: 0.1.0
+Version: 0.2.0
 Summary: Interactive matplotlib plotters for axially symmetric nuclear shapes (beta, FoS)
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/AleksanderAugustyn/shape-plotters
@@ -53,6 +53,10 @@ boxes (R₀ = 1.16 A^(1/3) fm), Reset, and Save (300 dpi PNG named after the
 parameters, written to the current directory). Red dotted marks on the FoS
 sliders are practical limits.
 
+While a slider is dragged the axes hold still, so the shape visibly changes
+instead of the axes rescaling around it; they refit when the mouse is
+released. If the shape outgrows the view mid-drag, the view jumps out once.
+
 ## Requirements
 
 - Linux x86-64. The parameterization libraries ship manylinux wheels only;

{shape_plotters-0.1.0 → shape_plotters-0.2.0}/README.md

@@ -33,6 +33,10 @@ boxes (R₀ = 1.16 A^(1/3) fm), Reset, and Save (300 dpi PNG named after the
 parameters, written to the current directory). Red dotted marks on the FoS
 sliders are practical limits.
 
+While a slider is dragged the axes hold still, so the shape visibly changes
+instead of the axes rescaling around it; they refit when the mouse is
+released. If the shape outgrows the view mid-drag, the view jumps out once.
+
 ## Requirements
 
 - Linux x86-64. The parameterization libraries ship manylinux wheels only;

shape_plotters-0.2.0/shape_plotters/core/blit.py

@@ -0,0 +1,103 @@
+"""Background cache for blitted slider drags.
+
+During a drag only a few artists change: the data lines, the stats text and
+the dragged slider. DragBlitter keeps a copy of everything else (the static
+layer) and composes each frame from that copy plus the dynamic artists,
+instead of redrawing the whole figure.
+
+It knows pixels, not shapes. What counts as a change to the static layer
+(view limits, titles, legends) is the engine's policy; the engine reports it
+through invalidate().
+"""
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from matplotlib.artist import Artist
+from matplotlib.axes import Axes
+from matplotlib.figure import Figure
+
+
+class DragBlitter:
+    """Owns the static background and the ``animated`` flags for one drag.
+
+    Parameters
+    ----------
+    fig : Figure
+        The figure to compose frames on. Its canvas must support blitting.
+    dynamic : Sequence[Artist]
+        Artists that change on every frame of a drag.
+    """
+
+    def __init__(self, fig: Figure, dynamic: Sequence[Artist]) -> None:
+        self._fig = fig
+        self._dynamic = tuple(dynamic)
+        self._slider_ax: Axes | None = None
+        self._background = None
+        fig.canvas.mpl_connect("draw_event", self._on_draw)
+        # A window resize only schedules its redraw; a motion event handled
+        # before it must not blit the old-size background.
+        fig.canvas.mpl_connect("resize_event", lambda _event: self.invalidate())
+
+    @property
+    def active(self) -> bool:
+        """True between begin() and end()."""
+        return self._slider_ax is not None
+
+    @property
+    def ready(self) -> bool:
+        """True when a background matching the current static layer is held."""
+        return self._background is not None
+
+    def begin(self, slider_ax: Axes) -> None:
+        """Enter drag mode; full draws now leave the dynamic layer to us.
+
+        The whole slider axes is animated, not its handle and value text
+        individually: no private Slider attributes, and the value text cannot
+        overprint the copy baked into the background.
+        """
+        self._slider_ax = slider_ax
+        self._background = None
+        for artist in (*self._dynamic, slider_ax):
+            artist.set_animated(True)
+
+    def end(self) -> None:
+        """Leave drag mode; the next full draw is an ordinary one."""
+        if self._slider_ax is None:
+            return
+        for artist in (*self._dynamic, self._slider_ax):
+            artist.set_animated(False)
+        self._slider_ax = None
+        self._background = None
+
+    def invalidate(self) -> None:
+        """The static layer changed; the next full draw recaptures it."""
+        self._background = None
+
+    def blit(self) -> None:
+        """Compose one frame: the saved background plus the dynamic layer."""
+        canvas = self._fig.canvas
+        canvas.restore_region(self._background)
+        self._draw_dynamic()
+        canvas.blit(self._fig.bbox)
+
+    def _on_draw(self, event) -> None:
+        # Runs at the end of every full draw. In drag mode that draw skipped
+        # the animated artists, so the canvas holds exactly the static layer.
+        if self._slider_ax is None:
+            return
+        if self._fig.canvas.is_saving():
+            # An export (savefig), not a screen draw. It already drew the
+            # animated artists, except whole animated axes: add the slider.
+            # It may also have re-rendered the canvas at another size or on
+            # another canvas class, so the held background is no longer valid.
+            self._slider_ax.draw(event.renderer)
+            self._background = None
+            return
+        self._background = self._fig.canvas.copy_from_bbox(self._fig.bbox)
+        self._draw_dynamic()
+
+    def _draw_dynamic(self) -> None:
+        for artist in self._dynamic:
+            self._fig.draw_artist(artist)
+        self._fig.draw_artist(self._slider_ax)

{shape_plotters-0.1.0 → shape_plotters-0.2.0}/shape_plotters/core/engine.py

@@ -8,14 +8,24 @@ Artists are created once at build; update() only mutates data, text, and
 visibility. v0.1 cleared and replotted every axes per slider event — legend
 and text layout made that the frame-time bottleneck (see
 docs/superpowers/specs/2026-07-03-engine-v0.2-performance-design.md).
+
+A full-figure redraw is still ~100 ms, almost all of it ticks, legends and
+widget axes that do not change. While a slider is dragged, update() therefore
+blits: the static layer comes from a cached background (blit.py) and only the
+dynamic artists and the dragged slider are drawn. Everything outside a drag
+takes the ordinary full-draw path, so a settled figure is pixel-identical to
+one that was never dragged (see
+docs/superpowers/specs/2026-10-03-engine-v0.3-blitting-design.md).
 """
 from __future__ import annotations
 
 import numpy as np
 import matplotlib.pyplot as plt
+from matplotlib.axes import Axes
 from matplotlib.widgets import Button, CheckButtons
 
 from shape_plotters.core import energy, fragments, quadrature
+from shape_plotters.core.blit import DragBlitter
 from shape_plotters.core.result import ShapeResult
 from shape_plotters.core.widgets import IntTextBox, SliderRow
 
@@ -33,6 +43,10 @@ UNITS_LABEL = "fm units"
 # R0 = 1.16 fm equals WMMM's geometric R0; see FORD.md / v0.2 handoff).
 SCISSION_BAND_FM = (1.2, 1.5)
 
+# Headroom of a mid-drag refit, as an autoscale margin: when a dragged shape
+# outgrows the held view, the view jumps out this far so the next frames fit.
+DRAG_MARGIN = 0.25
+
 
 class ShapePlotterApp:
     def __init__(self, render) -> None:
@@ -47,6 +61,12 @@ class ShapePlotterApp:
         self._build_figure()
         self._build_artists()
         self._build_widgets()
+        # Blitted slider drags; None where the canvas cannot blit.
+        self._blitter = (DragBlitter(self.fig, self._dynamic)
+                         if self.fig.canvas.supports_blit else None)
+        self._drag_pending = None   # slider whose press was drawn the ordinary way
+        self._dragged = None        # slider the blitter was begun on
+        self.fig.canvas.mpl_connect("button_release_event", self._on_release)
         self.update()
 
     # ---------- construction ----------
@@ -66,6 +86,8 @@ class ShapePlotterApp:
         self.ax_extra = self.fig.add_subplot(gs[2]) if self.render.has_extra_panel else None
         self.ax_stats = self.fig.add_subplot(gs[ncols])
         self.ax_stats.axis("off")
+        self._data_axes = tuple(
+            ax for ax in (self.ax_radius, self.ax_shape, self.ax_extra) if ax is not None)
 
     def _build_artists(self) -> None:
         # fm_units defaults to True; the unit toggle re-texts labels in place.
@@ -132,6 +154,16 @@ class ShapePlotterApp:
             0.0, 1.0, "", va="top", family="monospace", fontsize=12,
             transform=self.ax_stats.transAxes)
 
+        # Everything update() mutates per frame. The rest of the figure is the
+        # static layer that a blitted drag frame reuses.
+        dynamic = [self.r_line, self.dr_line, self.shape_upper, self.shape_lower,
+                   self.neck_line, self.zcm_point, self.rtheta_upper,
+                   self.rtheta_lower, self.rtheta_zcm, self.stats_text]
+        if self.ax_extra is not None:
+            dynamic += [self.extra_rho, self.extra_drho, self.zcm_extra]
+        self._dynamic = tuple(dynamic)
+        self._rest_margins = {ax: ax.margins() for ax in self._data_axes}
+
     def _build_widgets(self) -> None:
         self.rows: dict[str, SliderRow] = {}
         y = 0.06
@@ -229,6 +261,9 @@ class ShapePlotterApp:
             self.rows[spec.key].slider.set_val(spec.vinit)
 
     def _save(self, _event=None) -> None:
+        # A drag whose release never arrived must not leak its held view into
+        # the file: leave drag mode first.
+        self._on_release(None)
         params = {k: row.slider.val for k, row in self.rows.items()}
         fname = self.render.filename(self.z_box.value, self.n_box.value, params)
         self.fig.savefig(fname, dpi=300, bbox_inches="tight")
@@ -281,6 +316,8 @@ class ShapePlotterApp:
         return R0_FM * float(self.z_box.value + self.n_box.value) ** (1.0 / 3.0)
 
     def update(self, _val=None) -> None:
+        dragging = self._sync_drag_mode()
+        static_before = (self.ax_shape.get_title(), self.shape_legend.get_visible())
         params = {k: row.slider.val for k, row in self.rows.items()}
         result = self.render.compute(params, self.toggle_state)
         self.last_result = result
@@ -382,12 +419,97 @@ class ShapePlotterApp:
         self._energy_lines = []   # any shape/Z/N/unit change invalidates energies
         self._refresh_stats()
 
-        # visible_only: the hidden neck line keeps stale data by design.
-        for ax in (self.ax_radius, self.ax_shape, self.ax_extra):
-            if ax is not None:
+        static_changed = static_before != (
+            self.ax_shape.get_title(), self.shape_legend.get_visible())
+        self._present(dragging, static_changed)
+
+    # ---------- presenting a frame ----------
+
+    def _sync_drag_mode(self) -> bool:
+        """Match drag mode to the sliders; True while a drag is being blitted.
+
+        A click is not a drag: the first update of a press is drawn the
+        ordinary way and drag mode starts with the next one. A plain click
+        then costs one full draw, not a drag-mode draw plus the release refit.
+        """
+        if self._blitter is None:
+            return False
+        slider = next((row.slider for row in self.rows.values()
+                       if row.slider.drag_active), None)
+        if slider is None:
+            self._drag_pending = None
+            if self._blitter.active:      # the release event never arrived
+                self._end_drag()
+            return False
+        if self._blitter.active:
+            if slider is self._dragged:
+                return True
+            # A stale drag after a lost release, and another slider pressed:
+            # blitting on would keep the new slider frozen in the background.
+            self._end_drag()
+        if self._drag_pending is not slider:
+            self._drag_pending = slider
+            return False
+        self._dragged = slider
+        self._blitter.begin(slider.ax)
+        return True
+
+    def _present(self, dragging: bool, static_changed: bool) -> None:
+        """Put the mutated artists on screen: a full draw, or a blitted drag frame.
+
+        static_changed says whether this update touched the static layer (the
+        cross-section title or the overlay legend); such a frame cannot blit.
+        """
+        if not dragging:
+            # visible_only: the hidden neck line keeps stale data by design.
+            for ax in self._data_axes:
                 ax.relim(visible_only=True)
                 ax.autoscale_view()
-        self.fig.canvas.draw_idle()
+            self.fig.canvas.draw_idle()
+            return
+        # Dragging: the view holds still, because rescaling changes the tick
+        # labels and with them the cached background.
+        for ax in self._data_axes:
+            ax.relim(visible_only=True)
+        if not all(self._view_holds(ax) for ax in self._data_axes):
+            for ax in self._data_axes:
+                ax.set_xmargin(DRAG_MARGIN)
+                ax.set_ymargin(DRAG_MARGIN)
+                ax.autoscale_view()
+            static_changed = True
+        if static_changed or not self._blitter.ready:
+            # Until that draw has run, later motion events land here again and
+            # re-request it (coalesced) instead of blitting a stale background.
+            self._blitter.invalidate()
+            self.fig.canvas.draw_idle()
+        else:
+            self._blitter.blit()
+
+    @staticmethod
+    def _view_holds(ax: Axes) -> bool:
+        """True when the data limits lie inside the view on every autoscaled axis."""
+        data, view = ax.dataLim, ax.viewLim
+        x0, x1 = sorted(view.intervalx)
+        y0, y1 = sorted(view.intervaly)
+        holds_x = not ax.get_autoscalex_on() or (x0 <= data.x0 and data.x1 <= x1)
+        holds_y = not ax.get_autoscaley_on() or (y0 <= data.y0 and data.y1 <= y1)
+        return holds_x and holds_y
+
+    def _end_drag(self) -> None:
+        """Leave drag mode and restore the tight view the non-drag path draws."""
+        self._blitter.end()
+        for ax in self._data_axes:
+            xmargin, ymargin = self._rest_margins[ax]
+            ax.set_xmargin(xmargin)
+            ax.set_ymargin(ymargin)
+            ax.relim(visible_only=True)
+            ax.autoscale_view()
+
+    def _on_release(self, _event) -> None:
+        self._drag_pending = None
+        if self._blitter is not None and self._blitter.active:
+            self._end_drag()
+            self.fig.canvas.draw_idle()
 
     def _apply_validity(self, ok: bool) -> None:
         # Color/alpha churn only on the valid<->invalid flip, not per frame.

{shape_plotters-0.1.0 → shape_plotters-0.2.0}/shape_plotters/core/widgets.py

@@ -52,6 +52,13 @@ class IntTextBox:
             # keeping the intended stop-typing-on-resize behavior.
             fig.canvas.mpl_disconnect(self.box._cids[-1])
             fig.canvas.mpl_connect("resize_event", lambda _e: self.box.stop_typing())
+        # TextBox.stop_typing() redraws the whole figure on every mouse press
+        # outside the box, typing or not. With the Z and N boxes that is two
+        # full redraws per click anywhere in the figure, so only stop when
+        # the box is actually being typed in.
+        stop_typing = self.box.stop_typing
+        self.box.stop_typing = (
+            lambda: stop_typing() if self.box.capturekeystrokes else None)
         self.value = int(initial)
         self._on_change = on_change
         self.box.on_submit(self._submit)

{shape_plotters-0.1.0 → shape_plotters-0.2.0}/shape_plotters.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: shape-plotters
-Version: 0.1.0
+Version: 0.2.0
 Summary: Interactive matplotlib plotters for axially symmetric nuclear shapes (beta, FoS)
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/AleksanderAugustyn/shape-plotters
@@ -53,6 +53,10 @@ boxes (R₀ = 1.16 A^(1/3) fm), Reset, and Save (300 dpi PNG named after the
 parameters, written to the current directory). Red dotted marks on the FoS
 sliders are practical limits.
 
+While a slider is dragged the axes hold still, so the shape visibly changes
+instead of the axes rescaling around it; they refit when the mouse is
+released. If the shape outgrows the view mid-drag, the view jumps out once.
+
 ## Requirements
 
 - Linux x86-64. The parameterization libraries ship manylinux wheels only;

{shape_plotters-0.1.0 → shape_plotters-0.2.0}/shape_plotters.egg-info/SOURCES.txt

@@ -16,6 +16,7 @@ shape_plotters.egg-info/requires.txt
 shape_plotters.egg-info/scm_file_list.json
 shape_plotters.egg-info/top_level.txt
 shape_plotters/core/__init__.py
+shape_plotters/core/blit.py
 shape_plotters/core/energy.py
 shape_plotters/core/engine.py
 shape_plotters/core/fragments.py
@@ -28,11 +29,14 @@ shape_plotters/renders/__init__.py
 shape_plotters/renders/beta.py
 shape_plotters/renders/fos.py
 tests/__init__.py
+tests/dragging.py
 tests/test_beta_render.py
+tests/test_blit.py
 tests/test_cli.py
 tests/test_energy.py
 tests/test_energy_local.py
 tests/test_engine.py
+tests/test_engine_drag.py
 tests/test_fos_render.py
 tests/test_fragments.py
 tests/test_neck.py

{shape_plotters-0.1.0 → shape_plotters-0.2.0}/shape_plotters.egg-info/scm_file_list.json

@@ -11,6 +11,7 @@
     "shape_plotters/__main__.py",
     "shape_plotters/cli.py",
     "shape_plotters/core/__init__.py",
+    "shape_plotters/core/blit.py",
     "shape_plotters/core/energy.py",
     "shape_plotters/core/engine.py",
     "shape_plotters/core/fragments.py",
@@ -23,11 +24,14 @@
     "shape_plotters/renders/beta.py",
     "shape_plotters/renders/fos.py",
     "tests/__init__.py",
+    "tests/dragging.py",
     "tests/test_beta_render.py",
+    "tests/test_blit.py",
     "tests/test_cli.py",
     "tests/test_energy.py",
     "tests/test_energy_local.py",
     "tests/test_engine.py",
+    "tests/test_engine_drag.py",
     "tests/test_fos_render.py",
     "tests/test_fragments.py",
     "tests/test_neck.py",

shape_plotters-0.2.0/tests/dragging.py

@@ -0,0 +1,82 @@
+"""Simulated slider drags for tests: real MouseEvents on the slider axes.
+
+Under Agg, draw_idle() draws immediately, so counting draw_event callbacks
+counts full-figure redraws.
+"""
+from __future__ import annotations
+
+import numpy as np
+from matplotlib.backend_bases import MouseEvent
+
+from shape_plotters.core.engine import ShapePlotterApp
+
+
+def steps(start: float, stop: float, step: float) -> list[float]:
+    """Inclusive slider values from start to stop, on the 0.01 slider grid."""
+    count = round((stop - start) / step)
+    return [round(start + i * step, 2) for i in range(count + 1)]
+
+
+def _mouse(app: ShapePlotterApp, name: str, key: str, value: float) -> None:
+    slider = app.rows[key].slider
+    x, y = slider.ax.transData.transform((value, 0.5))
+    canvas = app.fig.canvas
+    canvas.callbacks.process(name, MouseEvent(name, canvas, x, y, button=1))
+
+
+def press(app: ShapePlotterApp, key: str, value: float) -> None:
+    _mouse(app, "button_press_event", key, value)
+
+
+def move(app: ShapePlotterApp, key: str, value: float) -> None:
+    _mouse(app, "motion_notify_event", key, value)
+
+
+def release(app: ShapePlotterApp, key: str) -> None:
+    _mouse(app, "button_release_event", key, app.rows[key].slider.val)
+
+
+def begin_drag(app: ShapePlotterApp, key: str, values: list[float]) -> list[float]:
+    """Press and move until frames are being blitted; returns the unused values.
+
+    The press and the first motion are either drawn the ordinary way or start
+    drag mode, depending on whether the press itself moved the slider. After
+    two motions the background is captured either way.
+    """
+    press(app, key, values[0])
+    move(app, key, values[1])
+    move(app, key, values[2])
+    assert app._blitter.active and app._blitter.ready
+    return values[3:]
+
+
+def pixels(app: ShapePlotterApp) -> np.ndarray:
+    return np.asarray(app.fig.canvas.buffer_rgba()).copy()
+
+
+def count_draws(app: ShapePlotterApp) -> list[int]:
+    """A list that grows by one on every full-figure redraw from now on."""
+    draws: list[int] = []
+    app.fig.canvas.mpl_connect("draw_event", lambda _event: draws.append(1))
+    return draws
+
+
+def animated(app: ShapePlotterApp) -> list:
+    """Artists still flagged animated: must be empty outside a drag."""
+    candidates = (*app._dynamic, *(row.slider.ax for row in app.rows.values()))
+    return [artist for artist in candidates if artist.get_animated()]
+
+
+def data_inside_view(app: ShapePlotterApp) -> bool:
+    """True when every visible line on the data panels lies inside its axes limits."""
+    for ax in app._data_axes:
+        x0, x1 = sorted(ax.get_xlim())
+        y0, y1 = sorted(ax.get_ylim())
+        for line in ax.lines:
+            x = np.asarray(line.get_xdata(), dtype=float)
+            y = np.asarray(line.get_ydata(), dtype=float)
+            if not line.get_visible() or x.size == 0:
+                continue
+            if x.min() < x0 or x.max() > x1 or y.min() < y0 or y.max() > y1:
+                return False
+    return True

shape_plotters-0.2.0/tests/test_blit.py

@@ -0,0 +1,107 @@
+"""DragBlitter on a bare figure: background capture, frame composition, cleanup."""
+import io
+
+import matplotlib.pyplot as plt
+import numpy as np
+import pytest
+
+from shape_plotters.core.blit import DragBlitter
+
+
+def _pixels(fig) -> np.ndarray:
+    return np.asarray(fig.canvas.buffer_rgba()).copy()
+
+
+@pytest.fixture
+def scene():
+    """A plot axes with one dynamic line, and a small axes standing in for a slider."""
+    fig = plt.figure(figsize=(6, 4))
+    ax = fig.add_axes((0.1, 0.3, 0.8, 0.6))
+    (line,) = ax.plot([0.0, 1.0], [0.0, 1.0], lw=2)
+    ax.set_xlim(0.0, 1.0)
+    ax.set_ylim(-1.5, 1.5)
+    knob_ax = fig.add_axes((0.1, 0.1, 0.8, 0.05))
+    (knob,) = knob_ax.plot([0.2], [0.5], marker="o")
+    knob_ax.set_xlim(0.0, 1.0)
+    knob_ax.set_ylim(0.0, 1.0)
+    blitter = DragBlitter(fig, [line])
+    fig.canvas.draw()
+    yield fig, ax, line, knob_ax, knob, blitter
+    plt.close(fig)
+
+
+def test_blitted_frame_equals_full_redraw(scene) -> None:
+    fig, _ax, line, knob_ax, knob, blitter = scene
+    blitter.begin(knob_ax)
+    fig.canvas.draw()                        # captures the static background
+    before = _pixels(fig)
+    line.set_ydata([1.0, -1.0])              # the dynamic layer changes
+    knob.set_xdata([0.8])                    # and so does the dragged control
+    blitter.blit()
+    blitted = _pixels(fig)
+    fig.canvas.draw()
+    assert (blitted != before).any()         # the frame really changed
+    assert np.array_equal(blitted, _pixels(fig))
+
+
+def test_background_exists_only_after_a_draw_in_drag_mode(scene) -> None:
+    fig, _ax, _line, knob_ax, _knob, blitter = scene
+    assert not blitter.active and not blitter.ready   # the fixture's draw captured nothing
+    blitter.begin(knob_ax)
+    assert blitter.active and not blitter.ready
+    fig.canvas.draw()
+    assert blitter.ready
+    blitter.invalidate()
+    assert not blitter.ready
+    fig.canvas.draw()
+    assert blitter.ready
+
+
+def test_foreign_draw_mid_drag_recaptures_background(scene) -> None:
+    fig, ax, line, knob_ax, _knob, blitter = scene
+    blitter.begin(knob_ax)
+    fig.canvas.draw()
+    ax.set_title("static change")            # stands in for a resize or expose
+    fig.canvas.draw()                        # a full draw the blitter did not ask for
+    line.set_ydata([1.0, -1.0])
+    blitter.blit()
+    blitted = _pixels(fig)
+    fig.canvas.draw()
+    assert np.array_equal(blitted, _pixels(fig))   # the title is in the blitted frame
+
+
+def test_end_restores_ordinary_drawing(scene) -> None:
+    fig, _ax, line, knob_ax, _knob, blitter = scene
+    reference = _pixels(fig)                 # drawn before any drag
+    blitter.begin(knob_ax)
+    fig.canvas.draw()
+    blitter.end()
+    fig.canvas.draw()
+    assert not blitter.active and not blitter.ready
+    assert not line.get_animated() and not knob_ax.get_animated()
+    assert np.array_equal(_pixels(fig), reference)
+
+
+def test_export_mid_drag_is_complete_and_drops_the_background(scene) -> None:
+    # savefig can run while a drag is active (the toolbar's save key, or a
+    # Save click after a lost release). It is not a screen draw: it must not
+    # become the background, and the exported file must not miss anything.
+    fig, _ax, line, knob_ax, _knob, blitter = scene
+
+    def export(fmt: str) -> bytes:
+        buffer = io.BytesIO()
+        fig.savefig(buffer, format=fmt, dpi=100)
+        return buffer.getvalue()
+
+    reference = export("rgba")               # saved before any drag
+    blitter.begin(knob_ax)
+    fig.canvas.draw()
+    assert export("rgba") == reference       # line and slider axes present, each drawn once
+    export("pdf")                            # a canvas that cannot copy regions
+    assert not blitter.ready                 # the export replaced the canvas contents
+    fig.canvas.draw()
+    line.set_ydata([1.0, -1.0])
+    blitter.blit()
+    blitted = _pixels(fig)
+    fig.canvas.draw()
+    assert np.array_equal(blitted, _pixels(fig))

shape_plotters-0.2.0/tests/test_engine_drag.py

@@ -0,0 +1,291 @@
+"""Slider drags: blitted frames, the held view, and the return to ordinary drawing."""
+import io
+
+import matplotlib.pyplot as plt
+import numpy as np
+import pytest
+from matplotlib.backend_bases import ResizeEvent
+from matplotlib.backends.backend_agg import FigureCanvasAgg
+
+from shape_plotters.core.engine import ShapePlotterApp
+from shape_plotters.renders.beta import BetaRender
+from shape_plotters.renders.fos import FoSRender
+from tests.dragging import (animated, begin_drag, count_draws, data_inside_view, move,
+                            pixels, press, release, steps)
+
+# Drags that shrink the shape: the data never leaves the view and neither the
+# title nor the overlay legend changes, so every frame after the start can blit.
+SHRINKING = [
+    pytest.param(BetaRender, {"beta2": 1.0}, "beta2", (1.0, 0.85, -0.01), id="beta"),
+    pytest.param(FoSRender, {"c": 1.6, "a4": 0.3}, "a4", (0.3, 0.15, -0.01), id="fos"),
+]
+
+
+@pytest.fixture
+def make_app():
+    apps: list[ShapePlotterApp] = []
+
+    def make(render_cls, **presets: float) -> ShapePlotterApp:
+        app = ShapePlotterApp(render_cls())
+        for key, value in presets.items():
+            app.rows[key].slider.set_val(value)
+        app.fig.canvas.draw()
+        apps.append(app)
+        return app
+
+    yield make
+    for app in apps:
+        plt.close(app.fig)
+
+
+# ---------- a click is not a drag ----------
+
+def test_click_costs_one_full_draw_and_is_not_a_drag(make_app) -> None:
+    app = make_app(BetaRender)
+    draws = count_draws(app)
+    press(app, "beta2", 0.3)
+    release(app, "beta2")
+    assert len(draws) == 1
+    assert not app._blitter.active and animated(app) == []
+    reference = make_app(BetaRender, beta2=0.3)
+    assert np.array_equal(pixels(app), pixels(reference))
+
+
+# ---------- blitted frames ----------
+
+@pytest.mark.parametrize("render_cls, presets, key, span", SHRINKING)
+def test_drag_frames_are_blitted_not_redrawn(make_app, render_cls, presets, key, span) -> None:
+    app = make_app(render_cls, **presets)
+    rest = begin_drag(app, key, steps(*span))
+    draws = count_draws(app)
+    for value in rest:
+        move(app, key, value)
+    assert draws == []                                   # no full-figure redraw
+    assert app.rows[key].slider.val == pytest.approx(span[1])
+    assert np.array_equal(app.r_line.get_ydata(),
+                          app.last_result.radius * app._scale())
+
+
+@pytest.mark.parametrize("render_cls, presets, key, span", SHRINKING + [
+    # The neck line disappears on the way: a dynamic artist turning invisible.
+    pytest.param(BetaRender, {"beta2": 1.2}, "beta2", (1.2, 0.4, -0.04),
+                 id="beta-neck-vanishes"),
+])
+def test_every_blitted_frame_equals_a_full_redraw(
+        make_app, render_cls, presets, key, span) -> None:
+    app = make_app(render_cls, **presets)
+    for value in begin_drag(app, key, steps(*span)):
+        move(app, key, value)
+        blitted = pixels(app)
+        app.fig.canvas.draw()
+        assert np.array_equal(blitted, pixels(app)), f"frame at {key}={value}"
+
+
+def test_widgets_look_the_same_in_blitted_frames(make_app) -> None:
+    # Everything below the panels: the dragged slider (handle, fill, value
+    # text), the other sliders, buttons and the check marks, which CheckButtons
+    # draws through its own blit machinery. A blitted frame must show them
+    # exactly as the full redraw after the release does.
+    app = make_app(BetaRender, beta2=1.0)
+    for value in begin_drag(app, "beta2", steps(1.0, 0.9, -0.01)):
+        move(app, "beta2", value)
+    panels = (*app._data_axes, app.ax_stats)
+    widgets_top = max(ax.bbox.y1 for ax in app.fig.axes if ax not in panels)
+    height = pixels(app).shape[0]
+    widget_rows = slice(height - int(widgets_top), height)   # image rows run top to bottom
+    during = pixels(app)[widget_rows]
+    release(app, "beta2")
+    assert np.array_equal(during, pixels(app)[widget_rows])
+
+
+# ---------- leaving drag mode ----------
+
+@pytest.mark.parametrize("render_cls, presets, key, span", SHRINKING)
+def test_release_restores_ordinary_drawing(make_app, render_cls, presets, key, span) -> None:
+    app = make_app(render_cls, **presets)
+    for value in begin_drag(app, key, steps(*span)):
+        move(app, key, value)
+    release(app, key)
+    assert not app._blitter.active and animated(app) == []
+    reference = make_app(render_cls, **{**presets, key: span[1]})
+    assert np.array_equal(pixels(app), pixels(reference))
+
+
+def test_updates_outside_a_drag_never_enter_drag_mode(make_app) -> None:
+    app = make_app(BetaRender)
+    app.rows["beta2"].slider.set_val(0.4)       # programmatic
+    app.rows["beta2"]._nudge(+0.01)             # nudge button
+    app._on_check("fm units")                   # unit toggle
+    app._reset()                                # Reset button
+    assert not app._blitter.active and animated(app) == []
+
+
+# ---------- the held view ----------
+
+GROWING = [
+    pytest.param(BetaRender, "beta2", (0.0, 1.5, 0.01), id="beta"),
+    pytest.param(FoSRender, "c", (1.0, 2.5, 0.01), id="fos"),
+]
+
+
+@pytest.mark.parametrize("render_cls, key, span", GROWING)
+def test_growing_drag_refits_with_headroom(make_app, render_cls, key, span) -> None:
+    app = make_app(render_cls)
+    draws = count_draws(app)
+    values = steps(*span)
+    press(app, key, values[0])
+    for value in values[1:]:
+        move(app, key, value)
+        assert data_inside_view(app), f"shape clipped at {key}={value}"
+    # 150 steps of growth: a handful of refits, not one redraw per step.
+    assert 3 <= len(draws) <= 10
+    release(app, key)
+    reference = make_app(render_cls, **{key: span[1]})
+    assert ([ax.margins() for ax in app._data_axes]
+            == [ax.margins() for ax in reference._data_axes])
+    assert np.array_equal(pixels(app), pixels(reference))
+
+
+@pytest.mark.parametrize("presets, key, span", [
+    # The invalid-shape banner (the cross-section title) appears at beta4 = -1.2.
+    pytest.param({"beta4": -1.0}, "beta4", (-1.0, -1.3, -0.02), id="title"),
+    # The overlay legend hides at beta3 = 0 and comes back at 0.01.
+    pytest.param({"beta2": 0.5, "beta3": -0.05}, "beta3", (-0.05, 0.05, 0.01), id="legend"),
+])
+def test_static_change_mid_drag_reaches_the_frame(make_app, presets, key, span) -> None:
+    app = make_app(BetaRender, **presets)
+
+    def static_state() -> tuple[str, bool]:
+        return app.ax_shape.get_title(), app.shape_legend.get_visible()
+
+    seen = {static_state()}
+    for value in begin_drag(app, key, steps(*span)):
+        move(app, key, value)
+        seen.add(static_state())
+        frame = pixels(app)
+        app.fig.canvas.draw()
+        assert np.array_equal(frame, pixels(app)), f"stale static layer at {key}={value}"
+    assert len(seen) > 1      # the fixture really changed the title or the legend
+
+
+def test_drag_ending_on_an_invalid_shape_releases_cleanly(make_app) -> None:
+    app = make_app(BetaRender, beta4=-1.0)
+    for value in begin_drag(app, "beta4", steps(-1.0, -1.3, -0.02)):
+        move(app, "beta4", value)
+    assert not app.last_result.ok
+    release(app, "beta4")
+    reference = make_app(BetaRender, beta4=-1.3)
+    assert np.array_equal(pixels(app), pixels(reference))
+
+
+# ---------- robustness ----------
+
+def test_lost_release_ends_drag_mode_on_the_next_update(make_app) -> None:
+    app = make_app(BetaRender, beta2=1.0)
+    for value in begin_drag(app, "beta2", steps(1.0, 0.9, -0.01)):
+        move(app, "beta2", value)
+    app.rows["beta2"].slider.drag_active = False    # the release event never arrived
+    app.rows["beta3"].slider.set_val(0.1)           # any later update
+    assert not app._blitter.active and animated(app) == []
+    reference = make_app(BetaRender, beta2=0.9, beta3=0.1)
+    assert np.array_equal(pixels(app), pixels(reference))
+
+
+def test_drag_on_another_slider_after_a_lost_release_moves_that_slider(make_app) -> None:
+    # beta2's release never arrived, so it is still drag_active when beta3 is
+    # pressed. Drag mode must follow beta3: blitting with beta2's axes
+    # animated would leave beta3's handle frozen in the background.
+    app = make_app(BetaRender, beta2=1.0)
+    for value in begin_drag(app, "beta2", steps(1.0, 0.9, -0.01)):
+        move(app, "beta2", value)
+    values = steps(0.0, 0.1, 0.01)
+    press(app, "beta3", values[0])
+    for value in values[1:]:
+        move(app, "beta3", value)
+        frame = pixels(app)
+        app.fig.canvas.draw()
+        assert np.array_equal(frame, pixels(app)), f"frame at beta3={value}"
+
+
+def test_resize_mid_drag_never_blits_the_old_background(make_app) -> None:
+    # A Tk window resize changes the figure size and fires resize_event, but
+    # its redraw is only scheduled; a motion event can arrive first and must
+    # not blit the old-size background into the new-size canvas.
+    app = make_app(BetaRender, beta2=1.0)
+    rest = begin_drag(app, "beta2", steps(1.0, 0.9, -0.01))
+    width, height = app.fig.get_size_inches()
+    app.fig.set_size_inches(width * 1.2, height * 1.2, forward=False)
+    ResizeEvent("resize_event", app.fig.canvas)._process()
+    for value in rest:
+        move(app, "beta2", value)
+        frame = pixels(app)
+        app.fig.canvas.draw()
+        assert np.array_equal(frame, pixels(app)), f"frame at beta2={value}"
+
+
+def test_export_mid_drag_does_not_poison_later_frames(make_app) -> None:
+    app = make_app(BetaRender, beta2=1.0)
+    rest = begin_drag(app, "beta2", steps(1.0, 0.9, -0.01))
+    app.fig.savefig(io.BytesIO(), format="rgba", dpi=100)    # e.g. the toolbar's save key
+    for value in rest:
+        move(app, "beta2", value)
+        frame = pixels(app)
+        app.fig.canvas.draw()
+        assert np.array_equal(frame, pixels(app)), f"frame at beta2={value}"
+
+
+def test_save_button_in_a_stale_drag_saves_the_ordinary_figure(
+        make_app, tmp_path, monkeypatch) -> None:
+    monkeypatch.chdir(tmp_path)                      # _save() writes into the cwd
+    app = make_app(BetaRender, beta2=1.0)
+    for value in begin_drag(app, "beta2", steps(1.0, 0.9, -0.01)):
+        move(app, "beta2", value)
+    app.rows["beta2"].slider.drag_active = False     # the release event never arrived
+    app._save()
+    assert not app._blitter.active and animated(app) == []
+    (png,) = tmp_path.glob("*.png")
+    after_drag = png.read_bytes()
+    reference = make_app(BetaRender, beta2=0.9)
+    reference._save()                                # same parameters: same file name
+    assert after_drag == png.read_bytes()
+
+
+def test_canvas_without_blitting_redraws_every_frame(make_app, monkeypatch) -> None:
+    monkeypatch.setattr(FigureCanvasAgg, "supports_blit", False)
+    app = make_app(BetaRender, beta2=1.0)
+    assert app._blitter is None
+    draws = count_draws(app)
+    values = steps(1.0, 0.9, -0.01)
+    press(app, "beta2", values[0])                  # on the handle: no value change
+    for value in values[1:]:
+        move(app, "beta2", value)
+    assert len(draws) == len(values) - 1            # one full redraw per motion
+    release(app, "beta2")
+    assert animated(app) == []
+
+
+def test_dragging_past_the_slider_end_stops_at_the_limit(make_app) -> None:
+    app = make_app(BetaRender, beta2=3.9)
+    press(app, "beta2", 3.9)
+    for value in (3.95, 4.0, 4.3, 4.8):             # the last two are off the slider
+        move(app, "beta2", value)
+    assert app.rows["beta2"].slider.val == pytest.approx(4.0)
+    release(app, "beta2")
+    assert not app._blitter.active and animated(app) == []
+    reference = make_app(BetaRender, beta2=4.0)
+    assert np.array_equal(pixels(app), pixels(reference))
+
+
+def test_save_after_a_drag_matches_an_ordinary_save(make_app) -> None:
+    app = make_app(BetaRender, beta2=1.0)
+    for value in begin_drag(app, "beta2", steps(1.0, 0.9, -0.01)):
+        move(app, "beta2", value)
+    release(app, "beta2")
+    reference = make_app(BetaRender, beta2=0.9)
+
+    def saved(target: ShapePlotterApp) -> bytes:
+        buffer = io.BytesIO()
+        target.fig.savefig(buffer, format="rgba", dpi=100)
+        return buffer.getvalue()
+
+    assert saved(app) == saved(reference)

{shape_plotters-0.1.0 → shape_plotters-0.2.0}/tests/test_perf.py

@@ -1,6 +1,11 @@
 """Engine update-loop budgets under Agg (default ext4 venv — see venv caveat).
 
-Two tiers:
+Each test prints its figure; `python -m pytest tests/test_perf.py -s` is the
+one-command measurement on any machine. The budgets are calibrated for the
+development PC and may fail on a slower machine; the printed figures are
+still the measurement.
+
+Three tiers:
 
 - Artist mutation (draw neutered): the clear-and-replot regression guard.
   v0.1 rebuilt every artist per frame: ~15/20 ms (beta/fos). v0.2 persistent
@@ -9,14 +14,19 @@ Two tiers:
   every call resolves from params; the repeated vector is no longer served
   from stored state.
 - One-draw frame (update() alone; under Agg its draw_idle draws immediately):
-  loose interactivity backstop. Full-figure rasterization (~35 axes) costs
-  ~73-95 ms and dominates any engine improvement short of blitting; measured
-  v0.1 ~104/135 ms, v0.2 ~77/95 ms. Budget 250 ms.
+  loose interactivity backstop for everything that is not a drag. Full-figure
+  rasterization (~35 axes) costs ~73-95 ms; measured v0.1 ~104/135 ms,
+  v0.2 ~77/95 ms. Budget 250 ms.
+- Blitted drag step (one slider motion event during a drag): the static layer
+  is restored from a cached background and only the data lines, the stats
+  text and the dragged slider are drawn. Measured 2026-10-03: ~20-35 ms on
+  matplotlib 3.11 (its text rendering dominates), ~10 ms on 3.10. Budget 60 ms.
 
 Venv caveat (measured 2026-07-03): identical code is ~5x slower under the
 project-local .venv on /mnt/c (WSL2 9P filesystem). The default ext4 venv
 (/home/alex/.virtualenvs/default) is authoritative for these budgets.
 """
+import statistics
 import time
 
 import pytest
@@ -24,9 +34,11 @@ import pytest
 from shape_plotters.core.engine import ShapePlotterApp
 from shape_plotters.renders.beta import BetaRender
 from shape_plotters.renders.fos import FoSRender
+from tests.dragging import begin_drag, move, release, steps
 
 MUTATION_BUDGET_MS = 5.0
 FRAME_BUDGET_MS = 250.0
+DRAG_STEP_BUDGET_MS = 60.0
 
 
 def _mean_ms(fn, n: int = 10) -> float:
@@ -45,6 +57,7 @@ def test_artist_mutation_under_budget(render_cls) -> None:
         app.fig.canvas.draw()                    # warm-up: font cache + first layout
         app.fig.canvas.draw_idle = lambda: None  # isolate mutation from rasterization
         ms = _mean_ms(app.update)
+        print(f"\nPERF artist mutation [{app.render.name}]: {ms:.2f} ms")
         assert ms < MUTATION_BUDGET_MS, f"{ms:.1f} ms/update >= {MUTATION_BUDGET_MS} ms budget"
     finally:
         plt.close(app.fig)
@@ -59,6 +72,35 @@ def test_frame_time_under_budget(render_cls) -> None:
         app.update()
         app.fig.canvas.draw()      # warm-up: font cache + first layout
         ms = _mean_ms(app.update)  # one full draw per call (immediate under Agg)
+        print(f"\nPERF full frame [{app.render.name}]: {ms:.1f} ms")
         assert ms < FRAME_BUDGET_MS, f"{ms:.0f} ms/frame >= {FRAME_BUDGET_MS:.0f} ms budget"
     finally:
         plt.close(app.fig)
+
+
+@pytest.mark.parametrize("render_cls, presets, key, span", [
+    # Shrinking drags: no refits, so every timed step is a blitted frame.
+    pytest.param(BetaRender, {"beta2": 1.0}, "beta2", (1.0, 0.6, -0.01), id="beta"),
+    pytest.param(FoSRender, {"c": 1.6, "a4": 0.3}, "a4", (0.3, -0.1, -0.01), id="fos"),
+])
+def test_drag_step_under_budget(render_cls, presets, key, span) -> None:
+    import matplotlib.pyplot as plt
+
+    app = ShapePlotterApp(render_cls())
+    try:
+        for name, value in presets.items():
+            app.rows[name].slider.set_val(value)
+        app.fig.canvas.draw()      # warm-up: font cache + first layout
+        times_ms = []
+        for value in begin_drag(app, key, steps(*span)):
+            t0 = time.perf_counter()
+            move(app, key, value)
+            times_ms.append((time.perf_counter() - t0) * 1000.0)
+        release(app, key)
+        ms = statistics.median(times_ms)
+        print(f"\nPERF blitted drag step [{app.render.name}]: {ms:.1f} ms "
+              f"(median of {len(times_ms)})")
+        assert ms < DRAG_STEP_BUDGET_MS, (
+            f"{ms:.1f} ms/step >= {DRAG_STEP_BUDGET_MS:.0f} ms budget")
+    finally:
+        plt.close(app.fig)

{shape_plotters-0.1.0 → shape_plotters-0.2.0}/tests/test_widgets.py

@@ -1,6 +1,7 @@
 """Widget helpers under the Agg backend (conftest sets MPLBACKEND)."""
 import matplotlib.pyplot as plt
 import pytest
+from matplotlib.backend_bases import MouseEvent
 
 from shape_plotters.core.widgets import IntTextBox, SliderRow
 
@@ -12,6 +13,14 @@ def fig():
     plt.close(f)
 
 
+def _press(fig, x_frac: float, y_frac: float) -> None:
+    """Deliver a left-button press at a position given in figure fractions."""
+    width, height = fig.canvas.get_width_height()
+    event = MouseEvent("button_press_event", fig.canvas,
+                       x_frac * width, y_frac * height, button=1)
+    fig.canvas.callbacks.process("button_press_event", event)
+
+
 def test_slider_row_nudges_within_range(fig) -> None:
     row = SliderRow(fig, 0.5, "b2", 0.0, 4.0, 0.0, 0.01)
     row._nudge(+0.01)
@@ -48,3 +57,25 @@ def test_int_textbox_accepts_and_reverts(fig) -> None:
     assert box.value == 96          # reverted
     box._submit("-3")
     assert box.value == 96          # positive ints only
+
+
+def test_press_elsewhere_does_not_redraw_when_not_typing(fig) -> None:
+    # TextBox.stop_typing() does a full canvas.draw() on every press outside
+    # the box. With the Z and N boxes that was two full redraws per click
+    # anywhere in the figure.
+    IntTextBox(fig, (0.1, 0.1, 0.1, 0.05), "Z", 92, lambda: None)
+    fig.canvas.draw()
+    draws: list[int] = []
+    fig.canvas.mpl_connect("draw_event", lambda _event: draws.append(1))
+    _press(fig, 0.8, 0.8)                    # far from the box
+    assert draws == []
+
+
+def test_press_elsewhere_still_ends_typing(fig) -> None:
+    calls: list[int] = []
+    box = IntTextBox(fig, (0.1, 0.1, 0.1, 0.05), "Z", 92, lambda: calls.append(1))
+    fig.canvas.draw()
+    box.box.begin_typing()
+    _press(fig, 0.8, 0.8)
+    assert not box.box.capturekeystrokes     # typing ended
+    assert calls                             # and the text was submitted