qmlmathplot 0.3.0__py3-none-any.whl → 0.4.1__py3-none-any.whl

qmlmathplot/__init__.py

@@ -52,34 +52,54 @@ from typing import TYPE_CHECKING
 
 from .camera import HOME_SIZE, HOME_VIEW, Camera, nice_ticks
 from .curve import Curve, CurveListModel, ImplicitCurve
+from .figure import Axes, Figure
+from .input import ViewInput
 from .plot import Plot
+from .qsb import cache_dir, cache_info, clear_cache, prune_cache
 from .view import QML_MAJOR, QML_MINOR, QML_URI, qml_component_path, register_qml_types
 
 if TYPE_CHECKING:  # only for type checkers; at runtime the module-level __getattr__ is used
+    from .canvas import FigureCanvasQt
     from .widget import MathPlotWidget
 
 __all__ = [
+    "Axes",
+    "cache_dir",
+    "cache_info",
     "Camera",
+    "clear_cache",
     "Curve",
     "CurveListModel",
+    "Figure",
+    "FigureCanvasQt",
     "HOME_SIZE",
     "HOME_VIEW",
     "ImplicitCurve",
     "MathPlotWidget",
     "nice_ticks",
     "Plot",
+    "prune_cache",
     "qml_component_path",
     "QML_MAJOR",
     "QML_MINOR",
     "QML_URI",
     "register_qml_types",
+    "ViewInput",
 ]
 
 
 def __getattr__(name: str) -> object:
-    """``MathPlotWidget`` is imported lazily, so pure-QML use never loads QtWidgets."""
+    """QtWidgets-backed names are lazy, so pure-QML use never loads QtWidgets."""
     if name == "MathPlotWidget":
         from .widget import MathPlotWidget
 
         return MathPlotWidget
+    if name == "FigureCanvasQt":
+        from .canvas import FigureCanvasQt
+
+        return FigureCanvasQt
+    if name == "pyplot":
+        from importlib import import_module
+
+        return import_module(".pyplot", __name__)
     raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

qmlmathplot/animation.py

@@ -0,0 +1,87 @@
+"""The one eased-camera animation shared by wheel and keyboard moves.
+
+Kept out of :class:`~qmlmathplot.camera.Camera` so the camera stays geometry + ticks: this
+object owns the ``QVariantAnimation`` and the interpolation policy, and calls back with the
+state to apply. Direct manipulation (drag, pinch, direct setters) stops it.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from PySide6.QtCore import QAbstractAnimation, QEasingCurve, QObject, QVariantAnimation
+
+__all__ = ["CameraAnimator"]
+
+State = tuple[float, float, float, float]      # centre x, centre y, scale x, scale y
+
+
+class CameraAnimator(QObject):
+    """Interpolate between two camera states; ``apply`` runs on every frame.
+
+    Scales interpolate geometrically (constant perceived zoom rate) and the centre linearly;
+    OutCubic gives the same short settle for a wheel notch and a keypress.
+    """
+
+    def __init__(self, apply: Callable[[State], None], parent: QObject | None = None) -> None:
+        super().__init__(parent)
+        self._apply: Callable[[State], None] = apply
+        self._from: State | None = None
+        self._to: State | None = None
+        self._animation: QVariantAnimation = QVariantAnimation(self)
+        self._animation.setStartValue(0.0)
+        self._animation.setEndValue(1.0)
+        self._animation.setEasingCurve(QEasingCurve.Type.OutCubic)
+        self._animation.valueChanged.connect(self._on_tick)
+        self._animation.finished.connect(self._on_finished)
+
+    # ------------------------------------------------------------------ state
+    @property
+    def running(self) -> bool:
+        return self._animation.state() == QAbstractAnimation.State.Running
+
+    def target(self, current: State) -> State:
+        """The state an in-flight animation is heading for (accumulate rapid wheel/key
+        presses); ``current`` otherwise."""
+        if self._to is not None and self.running:
+            return self._to
+        return current
+
+    # ------------------------------------------------------------- lifecycle
+    def start(self, start: State, end: State, duration: int) -> None:
+        duration = int(duration)
+        if duration <= 0:
+            self.stop()
+            self._apply(end)
+            return
+        if start == end:
+            self.stop()
+            return
+        self._from = start
+        self._to = end
+        self._animation.stop()
+        self._animation.setDuration(duration)
+        self._animation.start()
+
+    def stop(self) -> None:
+        if self._animation.state() != QAbstractAnimation.State.Stopped:
+            self._animation.stop()
+        self._from = None
+        self._to = None
+
+    # ------------------------------------------------------------- callbacks
+    def _on_tick(self, value: float) -> None:
+        if self._from is None or self._to is None:
+            return
+        t = float(value)
+        fx, fy, fsx, fsy = self._from
+        tx, ty, tsx, tsy = self._to
+        sx = fsx * (tsx / fsx) ** t
+        sy = fsy * (tsy / fsy) ** t
+        self._apply((fx + (tx - fx) * t, fy + (ty - fy) * t, sx, sy))
+
+    def _on_finished(self) -> None:
+        if self._to is not None:
+            self._apply(self._to)
+        self._from = None
+        self._to = None

qmlmathplot/camera.py

@@ -14,6 +14,9 @@ import math
 from PySide6.QtCore import Property, QObject, Signal, Slot
 from PySide6.QtGui import QVector2D
 
+from .animation import CameraAnimator, State
+from .input import ViewInput
+
 __all__ = ["HOME_SIZE", "HOME_VIEW", "Camera", "nice_ticks"]
 
 #: Home view — the classic 12x4 window — as (xmin, xmax, ymin, ymax).
@@ -22,7 +25,7 @@ __all__ = ["HOME_SIZE", "HOME_VIEW", "Camera", "nice_ticks"]
 #: the first reported size turns the home view into (zoom, y scale) for that widget, and
 #: the constants below are only the fallback used before any size is known.
 HOME_VIEW = (-6.0, 6.0, -2.0, 2.0)
-#: Reference size for the home view (before the first ``setViewport``).
+#: Reference size for the home view (before the first ``set_viewport``).
 HOME_SIZE = (900.0, 600.0)
 
 
@@ -91,6 +94,7 @@ class Camera(QObject):
     zoomStepChanged = Signal()
     panEnabledChanged = Signal()
     zoomEnabledChanged = Signal()
+    animationDurationChanged = Signal()
 
     #: Scale limits (world units per pixel), to keep panning/zooming reversible.
     MIN_SCALE = 1e-12
@@ -109,6 +113,16 @@ class Camera(QObject):
         self._zoom_step = 0.9
         self._pan_enabled = True
         self._zoom_enabled = True
+        self._ticks_key: tuple[float, float, float, float] | None = None
+        self._ticks_x: list[tuple[float, str]] = []
+        self._ticks_y: list[tuple[float, str]] = []
+        self._ticks_x_qml: list[list[float | str]] = []
+        self._ticks_y_qml: list[list[float | str]] = []
+        self._input = ViewInput(self)
+        self._animation_duration = 160
+        # One animation drives every discrete camera move (a wheel notch, a keypress). Drags
+        # and touch gestures are direct manipulation and must never be animated through.
+        self._animator = CameraAnimator(self._apply_state, self)
 
     # ------------------------------------------------------------- state
     def _get_centre(self) -> QVector2D:
@@ -118,6 +132,7 @@ class Camera(QObject):
         x, y = _pair(value)
         if (x, y) == (self._centre.x(), self._centre.y()):
             return
+        self._stop_animation()
         self._centre = QVector2D(x, y)
         self._home = False
         self._view_changed()
@@ -144,6 +159,7 @@ class Camera(QObject):
             raise ValueError(f"aspect must be positive, got {value!r}")
         if value == self._aspect:
             return
+        self._stop_animation()
         old_y = self.scale_y
         self._aspect = value
         self._home = False
@@ -173,6 +189,7 @@ class Camera(QObject):
         value = min(max(value, self.MIN_SCALE), self.MAX_SCALE)
         if value == self._zoom:
             return
+        self._stop_animation()
         factor = value / self._zoom
         self._zoom = value
         if keep_ratio and isinstance(self._aspect, str):
@@ -195,6 +212,7 @@ class Camera(QObject):
         width, _ = self._effective_size()
         if not hi > lo or width <= 0:
             return
+        self._stop_animation()
         self._centre = QVector2D(0.5 * (lo + hi), self._centre.y())
         self._scale_to((hi - lo) / width)    # keeps the ratio: y follows the same factor
 
@@ -208,6 +226,7 @@ class Camera(QObject):
         _, height = self._effective_size()
         if not hi > lo or height <= 0:
             return
+        self._stop_animation()
         self._centre = QVector2D(self._centre.x(), 0.5 * (lo + hi))
         if isinstance(self._aspect, str):
             self._y_scale = min(max((hi - lo) / height, self.MIN_SCALE), self.MAX_SCALE)
@@ -227,16 +246,30 @@ class Camera(QObject):
     viewport: QVector2D = Property("QVariant", _get_viewport, notify=viewChanged)
 
     # --------------------------------------------------------------- ticks
+    def _ensure_ticks(self) -> None:
+        """Recompute both axes once per distinct view; the two properties share the result."""
+        xlim, ylim = self._get_xlim(), self._get_ylim()
+        key = (xlim.x(), xlim.y(), ylim.x(), ylim.y())
+        if key == self._ticks_key:
+            return
+        self._ticks_key = key
+        self._ticks_x = nice_ticks(xlim.x(), xlim.y())
+        self._ticks_y = nice_ticks(ylim.x(), ylim.y())
+        self._ticks_x_qml = _qml_pairs(self._ticks_x)
+        self._ticks_y_qml = _qml_pairs(self._ticks_y)
+
     def tick_values(self) -> tuple[list[tuple[float, str]], list[tuple[float, str]]]:
         """Ticks for both axes of the visible range, as ``(value, label)`` pairs."""
-        xlim, ylim = self._get_xlim(), self._get_ylim()
-        return nice_ticks(xlim.x(), xlim.y()), nice_ticks(ylim.x(), ylim.y())
+        self._ensure_ticks()
+        return self._ticks_x, self._ticks_y
 
     def _get_ticks_x(self) -> list[list[float | str]]:
-        return _qml_pairs(self.tick_values()[0])
+        self._ensure_ticks()
+        return self._ticks_x_qml
 
     def _get_ticks_y(self) -> list[list[float | str]]:
-        return _qml_pairs(self.tick_values()[1])
+        self._ensure_ticks()
+        return self._ticks_y_qml
 
     ticks_x: list[tuple[float, str]] = Property("QVariant", _get_ticks_x, notify=ticksChanged)
     ticks_y: list[tuple[float, str]] = Property("QVariant", _get_ticks_y, notify=ticksChanged)
@@ -283,9 +316,147 @@ class Camera(QObject):
         bool, _get_zoom_enabled, _set_zoom_enabled, notify=zoomEnabledChanged
     )
 
+    def _get_input(self) -> ViewInput:
+        return self._input
+
+    #: Keyboard bindings, focus switch and pan step (see :class:`ViewInput`).
+    input: ViewInput = Property(ViewInput, _get_input, constant=True)
+
+    def _get_animation_duration(self) -> int:
+        return self._animation_duration
+
+    def _set_animation_duration(self, value: int) -> None:
+        value = int(value)
+        if value < 0:
+            raise ValueError(f"animationDuration must be >= 0, got {value!r}")
+        if value == self._animation_duration:
+            return
+        self._animation_duration = value
+        self.animationDurationChanged.emit()
+
+    #: Duration of a wheel/keyboard camera move in ms; 0 disables the animation.
+    animationDuration: int = Property(
+        int, _get_animation_duration, _set_animation_duration, notify=animationDurationChanged
+    )
+
+    # --------------------------------------------------------------- animation
+    def _state(self) -> tuple[float, float, float, float]:
+        return (self._centre.x(), self._centre.y(), self._zoom, self._get_scale_y())
+
+    def _clamp_state(
+        self, centre_x: float, centre_y: float, scale_x: float, scale_y: float
+    ) -> tuple[float, float, float, float]:
+        return (
+            float(centre_x),
+            float(centre_y),
+            min(max(float(scale_x), self.MIN_SCALE), self.MAX_SCALE),
+            min(max(float(scale_y), self.MIN_SCALE), self.MAX_SCALE),
+        )
+
+    def _apply_view(
+        self, centre_x: float, centre_y: float, scale_x: float, scale_y: float
+    ) -> None:
+        """Apply a state without stopping the animation that produced it."""
+        centre_x, centre_y, scale_x, scale_y = self._clamp_state(
+            centre_x, centre_y, scale_x, scale_y
+        )
+        if (centre_x, centre_y, scale_x, scale_y) == self._state():
+            return
+        self._centre = QVector2D(centre_x, centre_y)
+        self._zoom = scale_x
+        if isinstance(self._aspect, str):
+            self._y_scale = scale_y
+        self._home = False
+        self._view_changed()
+
+    def _target_state(self) -> State:
+        """The state an in-flight animation is heading for (accumulate rapid wheel/key
+        presses); the current state otherwise."""
+        return self._animator.target(self._state())
+
+    def _stop_animation(self) -> None:
+        self._animator.stop()
+
+    @Slot()
+    def stop_animation(self) -> None:
+        """Cancel an in-flight animated move (called by the view on direct manipulation)."""
+        self._animator.stop()
+
+    def _apply_state(self, state: State) -> None:
+        self._apply_view(*state)
+
+    def _animate_to(self, state: State, duration: int) -> None:
+        self._animator.start(self._state(), self._clamp_state(*state), duration)
+
+    def _zoom_state(
+        self,
+        base: tuple[float, float, float, float],
+        factor: float,
+        u: float,
+        v: float,
+        width: float,
+        height: float,
+    ) -> tuple[float, float, float, float]:
+        """The state after scaling ``base`` by ``factor`` with (u, v) held fixed."""
+        bx, by, bsx, bsy = base
+        tsx = min(max(bsx * factor, self.MIN_SCALE), self.MAX_SCALE)
+        actual = tsx / bsx
+        if isinstance(self._aspect, str):
+            tsy = min(max(bsy * actual, self.MIN_SCALE), self.MAX_SCALE)
+        else:
+            tsy = tsx / float(self._aspect)
+        if width > 0 and height > 0:
+            anchor_x = bx + (u - 0.5) * width * bsx
+            anchor_y = by + (0.5 - v) * height * bsy
+            tx = anchor_x - (u - 0.5) * width * tsx
+            ty = anchor_y - (0.5 - v) * height * tsy
+        else:
+            tx, ty = bx, by
+        return self._clamp_state(tx, ty, tsx, tsy)
+
+    @Slot(float, float, float, float, float)
+    def zoom_at(self, factor: float, u: float, v: float, width: float, height: float) -> None:
+        """Magnify the view by ``factor`` (>1 closer, <1 farther) with (u, v) held fixed.
+
+        The primitive behind a pinch: the gesture supplies the incremental magnification.
+        """
+        factor = float(factor)
+        if not self._zoom_enabled or factor <= 0.0 or factor == 1.0:
+            return
+        self._stop_animation()
+        self._apply_view(*self._zoom_state(self._state(), 1.0 / factor, u, v, width, height))
+
+    @Slot(float, float, float, float, float, int)
+    def animate_zoom(
+        self, delta: float, u: float, v: float, width: float, height: float, duration: int
+    ) -> None:
+        """Animate one wheel/keyboard zoom step (``delta`` wheel units, 120 = one notch)."""
+        if not self._zoom_enabled or delta == 0:
+            return
+        factor = self._zoom_step ** (float(delta) / 120.0)
+        self._animate_to(
+            self._zoom_state(self._target_state(), factor, u, v, width, height), duration
+        )
+
+    @Slot(float, float, int)
+    def animate_pan(self, dx: float, dy: float, duration: int) -> None:
+        """Animate a pan by a pixel displacement (screen y points down)."""
+        if not self._pan_enabled or (dx == 0.0 and dy == 0.0):
+            return
+        bx, by, bsx, bsy = self._target_state()
+        self._animate_to((bx - dx * bsx, by + dy * bsy, bsx, bsy), duration)
+
     def _view_changed(self) -> None:
+        previous_key = self._ticks_key
+        previous_x, previous_y = self._ticks_x, self._ticks_y
+        self._ensure_ticks()
         self.viewChanged.emit()
-        self.ticksChanged.emit()
+        # During a pan the tick labels usually stay the same; re-emitting TicksChanged would
+        # rebuild QML's tick Repeaters every frame for identical rows.
+        if (previous_key is None
+                or previous_x != self._ticks_x
+                or previous_y != self._ticks_y):
+            self.ticksChanged.emit()
 
     @Slot(float, float, float, float)
     def set_view(self, centre_x: float, centre_y: float, scale_x: float, scale_y: float) -> None:
@@ -296,6 +467,7 @@ class Camera(QObject):
         and restoring it afterwards. ``"auto"`` stays "auto" (the scales are simply set), a
         numeric aspect is re-derived from the pair so the two scales are exactly as asked.
         """
+        self._stop_animation()
         scale_x = min(max(float(scale_x), self.MIN_SCALE), self.MAX_SCALE)
         scale_y = min(max(float(scale_y), self.MIN_SCALE), self.MAX_SCALE)
         self._centre = QVector2D(float(centre_x), float(centre_y))
@@ -310,7 +482,7 @@ class Camera(QObject):
 
     # --------------------------------------------------------------- slots
     @Slot(float, float)
-    def setViewport(self, width: float, height: float) -> None:
+    def set_viewport(self, width: float, height: float) -> None:
         """Record the widget size (logical pixels) — used by the derived ranges only.
 
         Drawing never depends on it: the shader derives its mapping from the camera and its
@@ -322,6 +494,7 @@ class Camera(QObject):
         size = (float(width), float(height))
         if size == self._size:
             return
+        self._stop_animation()
         self._size = size
         self._resolve_home()
         self._view_changed()
@@ -352,42 +525,23 @@ class Camera(QObject):
         """
         if not self._zoom_enabled or delta == 0:
             return
-        target = min(max(self._zoom * self._zoom_step ** (delta / 120.0), self.MIN_SCALE),
-                     self.MAX_SCALE)
-        factor = target / self._zoom
-        if factor == 1.0:
-            return
-        if width > 0 and height > 0:
-            anchor_x = self._centre.x() + (u - 0.5) * width * self.scale_x
-            anchor_y = self._centre.y() + (0.5 - v) * height * self.scale_y
-        else:
-            anchor_x, anchor_y = self._centre.x(), self._centre.y()
-        self._zoom = target
-        if isinstance(self._aspect, str):
-            self._y_scale = min(max(self._y_scale * factor, self.MIN_SCALE), self.MAX_SCALE)
-        if width > 0 and height > 0:
-            self._centre = QVector2D(
-                anchor_x - (u - 0.5) * width * self.scale_x,
-                anchor_y - (0.5 - v) * height * self.scale_y,
-            )
-        self._home = False
-        self._view_changed()
+        factor = self._zoom_step ** (float(delta) / 120.0)
+        self._stop_animation()
+        self._apply_view(*self._zoom_state(self._state(), factor, u, v, width, height))
 
     @Slot(float, float)
     def pan_pixels(self, dx: float, dy: float) -> None:
         """Pan by a pixel displacement (screen y points down, world y points up)."""
         if not self._pan_enabled or (dx == 0.0 and dy == 0.0):
             return
-        self._centre = QVector2D(
-            self._centre.x() - dx * self.scale_x,
-            self._centre.y() + dy * self.scale_y,
-        )
-        self._home = False
-        self._view_changed()
+        self._stop_animation()
+        cx, cy, sx, sy = self._state()
+        self._apply_view(cx - dx * sx, cy + dy * sy, sx, sy)
 
     @Slot()
     def reset(self) -> None:
         """Back to the home view (centre and scales as the camera was configured)."""
+        self._stop_animation()
         self._centre = QVector2D(0.0, 0.0)
         self._home = True
         self._resolve_home()

qmlmathplot/canvas.py

@@ -0,0 +1,107 @@
+"""Matplotlib-shaped canvas: a QWidget that hosts one compatibility :class:`Figure`.
+
+QtWidgets is imported here, so this module stays lazy in ``qmlmathplot.__init__`` exactly like
+:mod:`qmlmathplot.widget`: a pure-QML app never loads QtWidgets.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from PySide6.QtWidgets import QWidget
+
+from .widget import MathPlotWidget
+
+if TYPE_CHECKING:  # pragma: no cover - typing only
+    from .figure import Figure
+
+__all__ = ["FigureCanvas", "FigureCanvasQt"]
+
+
+class FigureCanvasQt(MathPlotWidget):
+    """A ``MathPlotWidget`` attached to a compatibility ``Figure``.
+
+    Matplotlib code constructs canvases and then calls ``draw()``; here the Qt scene is live,
+    so ``draw()`` / ``draw_idle()`` are harmless no-ops. ``print_figure`` and ``savefig``
+    forward to the same region-based export as :meth:`Figure.savefig`.
+    """
+
+    def __init__(
+        self,
+        figure: Figure | None = None,
+        parent: QWidget | None = None,
+        *,
+        width: int | None = None,
+        height: int | None = None,
+        dpi: float | None = None,
+    ) -> None:
+        from .figure import Figure
+
+        host = figure if figure is not None else Figure()
+        if dpi is not None:
+            host.set_dpi(dpi)
+        super().__init__(None, parent, plot=host.plot)
+        self._figure = host
+        host.canvas = self
+        target_width, target_height = host.get_size_pixels()
+        if width is not None:
+            target_width = int(width)
+        if height is not None:
+            target_height = int(height)
+        self.resize(target_width, target_height)
+
+    @property
+    def figure(self) -> "Figure":
+        return self._figure
+
+    @property
+    def figure_canvas(self) -> "FigureCanvasQt":
+        """Matplotlib's canvas property is called ``figure_canvas`` on some backends; this
+        alias keeps both spellings working."""
+        return self
+
+    # ---------------------------------------------------------- live scene
+    def draw(self) -> None:
+        """No-op: the scene repaints from model signals; there is no deferred renderer."""
+        self.update()
+
+    def draw_idle(self) -> None:
+        self.update()
+
+    def flush_events(self) -> None:
+        """No-op: Qt owns the event loop."""
+
+    # -------------------------------------------------------------- export
+    def print_figure(self, filename: str, **kwargs: object) -> None:
+        self._figure.savefig(filename, **kwargs)
+
+    def savefig(self, filename: str, **kwargs: object) -> None:
+        self._figure.savefig(filename, **kwargs)
+
+    # ------------------------------------------------------------- geometry
+    def get_width_height(self, physical: bool = False) -> tuple[int, int]:
+        if physical:
+            ratio = self.devicePixelRatioF()
+            return (round(self.width() * ratio), round(self.height() * ratio))
+        return (self.width(), self.height())
+
+    @property
+    def device_pixel_ratio(self) -> float:
+        return self.devicePixelRatioF()
+
+    # ------------------------------------------------------ explicitly absent
+    def mpl_connect(self, *args: object, **kwargs: object) -> None:
+        raise NotImplementedError(
+            "mpl_connect is not part of QMLMathPlot: Qt signals are the event system "
+            "(camera.viewChanged, camera.aspectChanged, curve.expressionChanged, …)"
+        )
+
+    def blit(self, *args: object, **kwargs: object) -> None:
+        raise NotImplementedError(
+            "blit is not part of QMLMathPlot: the Qt scene is live, there is no raster "
+            "buffer to restore"
+        )
+
+
+#: The shorter spelling used by ``matplotlib.backends.backend_qt*``.
+FigureCanvas = FigureCanvasQt