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

qmlmathplot/__init__.py

@@ -51,7 +51,7 @@ Demos: ``examples/minimal.py``, ``examples/explorer_qtwidgets.py``,
 from typing import TYPE_CHECKING
 
 from .camera import HOME_SIZE, HOME_VIEW, Camera, nice_ticks
-from .curve import Curve, CurveListModel
+from .curve import Curve, CurveListModel, ImplicitCurve
 from .plot import Plot
 from .view import QML_MAJOR, QML_MINOR, QML_URI, qml_component_path, register_qml_types
 
@@ -64,6 +64,7 @@ __all__ = [
     "CurveListModel",
     "HOME_SIZE",
     "HOME_VIEW",
+    "ImplicitCurve",
     "MathPlotWidget",
     "nice_ticks",
     "Plot",

qmlmathplot/__main__.py

@@ -0,0 +1,13 @@
+"""``python -m qmlmathplot`` — the same entry point as the installed ``qmlmathplot`` script.
+
+Keeping it here means the command works even when the console script is not on ``PATH`` (a
+``pip install --user``, a virtualenv used through ``python -m``, or a checkout run with
+``uv run``).
+"""
+
+import sys
+
+from .app import main
+
+if __name__ == "__main__":
+    sys.exit(main())

qmlmathplot/app.py

@@ -1,7 +1,10 @@
-"""MVP entry point: wraps the component into a minimal verifiable window (called by `main.py` /
-`uv run qmlmathplot`).
+"""MVP entry point: wraps the component into a minimal verifiable window.
 
-    python main.py --backend d3d11 "sin(1/x)"
+Reachable as the installed ``qmlmathplot`` console script, as ``python -m qmlmathplot``, and as
+``examples/minimal.py``:
+
+    python -m qmlmathplot --backend d3d11 "sin(1/x)"
+    uv run qmlmathplot "tan(x)"
 
 The RHI backend comes from the launch argument; without it, Qt's default backend is used. When
 specified it must be written to ``QSG_RHI_BACKEND`` *before* ``QGuiApplication`` — Qt reads it

qmlmathplot/camera.py

@@ -219,6 +219,13 @@ class Camera(QObject):
     xlim: QVector2D = Property("QVariant", _get_xlim, _set_xlim, notify=viewChanged)
     ylim: QVector2D = Property("QVariant", _get_ylim, _set_ylim, notify=viewChanged)
 
+    def _get_viewport(self) -> QVector2D:
+        width, height = self._effective_size()
+        return QVector2D(width, height)
+
+    #: Last reported size in logical pixels (the reference size before the first report).
+    viewport: QVector2D = Property("QVariant", _get_viewport, notify=viewChanged)
+
     # --------------------------------------------------------------- ticks
     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."""
@@ -280,6 +287,27 @@ class Camera(QObject):
         self.viewChanged.emit()
         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:
+        """Set the centre and *both* scales at once (world units per logical pixel).
+
+        The camera normally derives the y scale from ``aspect``; this is the primitive for a
+        caller that has two scales in hand — the exporter borrowing the camera for a render,
+        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.
+        """
+        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))
+        self._zoom = scale_x
+        if isinstance(self._aspect, str):
+            self._y_scale = scale_y
+        else:
+            self._aspect = scale_x / scale_y
+            self.aspectChanged.emit()
+        self._home = False
+        self._view_changed()
+
     # --------------------------------------------------------------- slots
     @Slot(float, float)
     def setViewport(self, width: float, height: float) -> None:

qmlmathplot/curve.py

@@ -1,8 +1,12 @@
 """Curve layer: one expression -> GLSL -> .qsb plus its style, and the list model QML repeats.
 
-A curve knows nothing about the view: the camera decides where we look, the curve decides
-what is drawn. One curve = one fragment shader pass (see ``model.FRAGMENT_TEMPLATE``), so
-``visible`` is the lever that costs nothing.
+A curve knows nothing about the view: the camera decides where we look, the curve decides what is
+drawn. One curve = one fragment shader pass, so ``visible`` is the lever that costs nothing.
+
+Two artists share the class: ``Curve`` draws ``y = f(x)`` (see ``model.FRAGMENT_TEMPLATE``) and
+``ImplicitCurve`` draws the level set ``F(x, y) = 0`` (``model.IMPLICIT_FRAGMENT_TEMPLATE``).
+They differ only in the shader *sources* — the uniform block, the model roles and the QML side
+are the same — so ``curve_for()`` can pick one from the expression's free symbols.
 """
 
 from __future__ import annotations
@@ -20,23 +24,76 @@ from PySide6.QtCore import (
 )
 from PySide6.QtGui import QColor
 
-from .model import shader_sources
+from .model import implicit_shader_sources, shader_sources
 from .qsb import bake
 
-__all__ = ["Curve", "CurveListModel"]
+__all__ = ["Curve", "CurveListModel", "ImplicitCurve", "curve_for", "parsed"]
 
-#: First colour of the default cycle (also the classic single-curve colour).
-DEFAULT_COLOR = "#33ccff"
-DEFAULT_COLOR_CYCLE = ("#33ccff", "#ff8866", "#7ddc7d", "#e0c341", "#c98bff")
+#: First colour of the default cycle (matplotlib's "tab10" blue, as in its default style).
+DEFAULT_COLOR = "#1f77b4"
+#: matplotlib's default ten-colour cycle.
+DEFAULT_COLOR_CYCLE = ("#1f77b4", "#ff7f0e", "#2ca02c", "#d62728", "#9467bd",
+                       "#8c564b", "#e377c2", "#7f7f7f", "#bcbd22", "#17becf")
 
 
 def _color(value: object) -> QColor:
-    """A QColor from a QColor or anything QColor() understands ("#rrggbb", a name, …)."""
+    """A QColor from a QColor, anything QColor() understands ("#rrggbb", a name, …), or None
+    for the default curve colour."""
+    if value is None:
+        return QColor(DEFAULT_COLOR)
     return QColor(value) if not isinstance(value, QColor) else QColor(value)
 
 
+def parsed(value: str | sp.Expr) -> tuple[str, sp.Expr]:
+    """The canonical string and the parsed expression of a curve input.
+
+    A string is parsed here, once; a sympy expression is used as it is (no ``Expr -> str ->
+    Expr`` round trip). The canonical string is what identifies the expression.
+    """
+    if isinstance(value, sp.Basic):
+        return str(value), value
+    return str(value), sp.sympify(value, locals={"x": sp.Symbol("x"), "y": sp.Symbol("y")})
+
+
+def curve_for(
+    expression: str | sp.Expr,
+    *,
+    implicit: bool | None = None,
+    color: object = None,
+    line_width: object = None,
+    label: str = "",
+    parent: QObject | None = None,
+) -> Curve:
+    """Create the artist an expression needs.
+
+    Auto-routed by the free symbols: ``x`` (or none) is a 1-D curve ``y = f(x)``, ``x`` and ``y``
+    is an implicit curve (the level set ``F(x, y) = 0``), and anything else raises — a parameter
+    must be substituted before it is plotted, and silently evaluating it as a pixel coordinate is
+    exactly the trap this avoids. ``implicit=True`` picks the level-set artist regardless of the
+    symbols (``add_implicit``).
+    """
+    text, expr = parsed(expression)
+    names = {symbol.name for symbol in expr.free_symbols}
+    if names - {"x", "y"}:
+        raise ValueError(
+            f"{sorted(names - {'x', 'y'})} must be substituted first: only x (or x and y) may "
+            f"be free, got {text!r}"
+        )
+    cls: type[Curve] = ImplicitCurve if (implicit or "y" in names) else Curve
+    return cls(expr, color=color, line_width=line_width, label=label, parent=parent)
+
+
 class Curve(QObject):
-    """One curve: an expression, its baked shaders, its style and its error text."""
+    """One curve: an expression, its baked shaders, its style and its error text.
+
+    The fragment shader follows the expression: ``y = f(x)`` while only ``x`` (or nothing) is
+    free, the level set ``F(x, y) = 0`` as soon as ``y`` appears — so ``add_curve`` and assigning
+    to ``expression`` both route themselves, and a text field can turn a function into a level
+    set. ``ImplicitCurve`` forces the level-set template regardless of the symbols.
+    """
+
+    #: Forced to the level-set template (see ``ImplicitCurve``).
+    _force_implicit = False
 
     expressionChanged = Signal()
     styleChanged = Signal()
@@ -47,7 +104,7 @@ class Curve(QObject):
 
     def __init__(
         self,
-        expression: str = "sin(x)",
+        expression: str | sp.Expr = "sin(x)",
         color: str | QColor = DEFAULT_COLOR,
         line_width: float = 1.5,
         label: str = "",
@@ -55,7 +112,8 @@ class Curve(QObject):
     ) -> None:
         super().__init__(parent)
         self._symbol = sp.Symbol("x")
-        self._expression = str(expression)
+        self._expression = ""
+        self._expr: sp.Expr = sp.Integer(0)      # replaced by the first assignment below
         self._color = _color(color)
         self._line_width = float(line_width)
         self._label = str(label)
@@ -63,23 +121,62 @@ class Curve(QObject):
         self._error = ""
         self._vertex = QUrl()
         self._fragment = QUrl()
-        self._compile(self._expression)
+        self._set_expression(expression)
 
     # ---------------------------------------------------------------- Expression
     def _get_expression(self) -> str:
         return self._expression
 
-    def _set_expression(self, source: str) -> None:
-        source = str(source)
-        if source == self._expression:
+    def _set_expression(self, source: str | sp.Expr) -> None:
+        """Set the expression from a string (parsed here, once) or from a sympy expression.
+
+        The canonical **string** is what identifies the expression — ``sp.sin(x)`` and
+        ``"sin(x)"`` are the same, and re-setting either is free — while the parsed
+        ``sp.Expr`` is cached for the bake and for the matplotlib hand-off, so neither ever
+        stringifies and re-parses again.
+        """
+        if isinstance(source, str):
+            canonical = source
+        else:
+            canonical = str(source)
+        if canonical == self._expression:
             return
-        self._expression = source
+        if isinstance(source, sp.Basic):          # already an expression: use it as it is
+            expr: sp.Expr = source
+        else:
+            try:
+                expr = sp.sympify(source, locals={"x": self._symbol, "y": sp.Symbol("y")})
+            except Exception as exc:
+                # Keep the last parsed expression: the shaders stay, `expression` is what was
+                # typed and `error` says why.
+                self._expression = str(canonical)
+                self._error = f"{type(exc).__name__}: {exc}"
+                self.expressionChanged.emit()
+                self.errorChanged.emit()
+                return
+        previous = self._expr
+        self._expression = str(canonical)
+        self._expr = expr
         self.expressionChanged.emit()
-        self._compile(source)
+        if not self._compile(expr):
+            # `expression` stays what was set (the text field shows it), `expr` stays what is
+            # drawn — the same rule as the unparsable string above.
+            self._expr = previous
 
     # Annotate the value type (PySide6 idiom): Property is a descriptor, so without the
     # annotation a type checker only sees the Property object and flags every read and write.
-    expression: str = Property(str, _get_expression, _set_expression, notify=expressionChanged)
+    # Declared "QVariant" so an ``sp.Expr`` reaches the setter unconverted; the getter is always
+    # the canonical string (QML, a project file and the text field all want one).
+    expression: str | sp.Expr = Property("QVariant", _get_expression, _set_expression,
+                                         notify=expressionChanged)
+
+    def _get_expr(self) -> sp.Expr:
+        return self._expr
+
+    #: The parsed expression being drawn (read-only): the object form the setter accepts, and
+    #: the one the bake and the matplotlib hand-off use. It follows the last expression that
+    #: compiled, so `expression` can show a failing edit while `expr` keeps the drawn curve.
+    expr: sp.Expr = Property("QVariant", _get_expr, notify=expressionChanged)
 
     # ------------------------------------------------------------------ Style
     def _get_color(self) -> QColor:
@@ -145,23 +242,57 @@ class Curve(QObject):
 
     error: str = Property(str, _get_error, notify=errorChanged)
 
-    def _compile(self, source: str) -> None:
-        """expression -> GLSL -> .qsb; on failure keep the last working shaders and write the
-        reason into ``error``."""
+    @property
+    def implicit(self) -> bool:
+        """Whether this curve is currently drawn as a level set ``F(x, y) = 0``.
+
+        Read-only, and it follows the expression: assigning ``"x**2 + y**2 - 1"`` switches this
+        curve's shader to the implicit one. The matplotlib hand-off uses it to skip level sets,
+        which cannot be sampled into a polyline.
+        """
+        return self._force_implicit or "y" in {symbol.name for symbol in self._expr.free_symbols}
+
+    def _sources(self, expr: sp.Expr) -> tuple[str, str]:
+        """The shader sources for this expression; anything unrenderable raises ``ValueError``
+        (which ``_compile`` turns into ``error``, keeping the last working shaders)."""
+        names = {symbol.name for symbol in expr.free_symbols}
+        if names - {"x", "y"}:
+            raise ValueError(
+                f"only x (or x and y) may be free, got {sorted(names)}: substitute parameters "
+                "first"
+            )
+        return implicit_shader_sources(expr) if (self._force_implicit or "y" in names) \
+            else shader_sources(expr)
+
+    def _compile(self, expr: sp.Expr) -> bool:
+        """expr -> GLSL -> .qsb; on failure keep the last working shaders, write the reason into
+        ``error`` and return False. The expression is parsed by the setter, never here."""
         try:
-            expr = sp.sympify(source, locals={"x": self._symbol})
-            vert_src, frag_src = shader_sources(expr)
+            vert_src, frag_src = self._sources(expr)
             vertex = bake(vert_src, "vert")
             fragment = bake(frag_src, "frag")
         except Exception as exc:  # noqa: BLE001 — expression or bake can fail; both reach the UI
             self._error = f"{type(exc).__name__}: {exc}"
             self.errorChanged.emit()
-            return
+            return False
         self._error = ""
         self._vertex = QUrl.fromLocalFile(str(vertex))
         self._fragment = QUrl.fromLocalFile(str(fragment))
         self.errorChanged.emit()
         self.shadersChanged.emit()
+        return True
+
+
+class ImplicitCurve(Curve):
+    """A curve drawn from the level set ``F(x, y) = 0``, whatever the free symbols.
+
+    No sampling and no envelope band: one evaluation of ``F`` and its two partials per pixel give
+    the distance to the level set (``docs/api-design.md`` §6b). Thin features and several
+    branches through one pixel are not handled yet, and a domain/pole curve is not special-cased
+    either — pixels where ``F`` is undefined come out NaN and are dropped.
+    """
+
+    _force_implicit = True
 
 
 class CurveListModel(QAbstractListModel):
@@ -243,21 +374,16 @@ class CurveListModel(QAbstractListModel):
         curve.visibleChanged.connect(lambda c=curve: self._notify(c, (self.VisibleRole,)))
 
     # ---------------------------------------------------------------- public
-    @Slot(str, "QVariant", "QVariant", str, result=QObject)
-    @Slot(str, result=QObject)
-    def add_curve(
-        self,
-        expression: str,
-        color: object = None,
-        line_width: object = None,
-        label: str = "",
-    ) -> Curve:
-        """Append a curve. Colour and line width default to the plot's cycle and width."""
+    # "QVariant" so a sympy expression is not stringified on the way in (see Plot.add_curve).
+    @Slot("QVariant", "QVariant", "QVariant", str, result=QObject)
+    @Slot("QVariant", result=QObject)
+    def _defaults(self, color: object, line_width: object) -> tuple[QColor, float]:
         if color is None:
             color = self._cycle[len(self._curves) % len(self._cycle)]
-        if line_width is None:
-            line_width = self._default_line_width
-        curve = Curve(expression, color, float(line_width), label, parent=self)  # type: ignore[arg-type]
+        return _color(color), (self._default_line_width if line_width is None
+                               else float(line_width))  # type: ignore[arg-type]
+
+    def _append(self, curve: Curve) -> Curve:
         row = len(self._curves)
         self.beginInsertRows(QModelIndex(), row, row)
         self._curves.append(curve)
@@ -265,6 +391,37 @@ class CurveListModel(QAbstractListModel):
         self._watch(curve)
         return curve
 
+    @Slot("QVariant", "QVariant", "QVariant", str, result=QObject)
+    @Slot("QVariant", result=QObject)
+    def add_curve(
+        self,
+        expression: str | sp.Expr,
+        color: object = None,
+        line_width: object = None,
+        label: str = "",
+    ) -> Curve:
+        """Append the artist the expression needs: ``y = f(x)``, or the level set
+        ``F(x, y) = 0`` when both symbols are free (see ``curve_for``). Colour and line width
+        default to the plot's cycle and width."""
+        default_color, default_width = self._defaults(color, line_width)
+        return self._append(curve_for(expression, color=default_color, line_width=default_width,
+                                      label=label, parent=self))
+
+    @Slot("QVariant", "QVariant", "QVariant", str, result=QObject)
+    @Slot("QVariant", result=QObject)
+    def add_implicit(
+        self,
+        expression: str | sp.Expr,
+        color: object = None,
+        line_width: object = None,
+        label: str = "",
+    ) -> Curve:
+        """Append an implicit curve (the level set ``F(x, y) = 0``) explicitly, whatever the free
+        symbols: ``x`` alone is a valid level set (vertical lines)."""
+        default_color, default_width = self._defaults(color, line_width)
+        return self._append(curve_for(expression, implicit=True, color=default_color,
+                                      line_width=default_width, label=label, parent=self))
+
     @Slot(QObject)
     def remove_curve(self, curve: Curve) -> None:
         row = self.index_of(curve)

qmlmathplot/export.py

@@ -0,0 +1,174 @@
+"""Export layer: render a region of this canvas at a pixel size (docs/api-design.md §9).
+
+An export is not a re-draw at another ``dpi`` — the plot *is* a Qt scene, so the same scene is
+rendered into a hidden ``QQuickWidget`` and read back synchronously. Everything (curves, grid,
+axes, theme) follows the live styling, so an export cannot drift from what the user sees; only
+the camera is *borrowed* for the duration of the render and restored before the event loop runs
+again, so the live view never repaints the export state.
+
+QtWidgets is imported lazily (a pure-QML app that never exports never loads it).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import QSize, Qt, QUrl
+from PySide6.QtGui import QColor, QImage
+
+if TYPE_CHECKING:  # pragma: no cover - typing only; the real imports stay lazy
+    from PySide6.QtQuickWidgets import QQuickWidget
+    from PySide6.QtWidgets import QApplication
+
+    from .plot import Plot
+
+__all__ = ["ADJUSTABLES", "render"]
+
+#: How a requested range and a requested pixel size are reconciled (see the module docstring).
+ADJUSTABLES = ("box", "datalim", "stretch")
+
+
+def _pair(value: Sequence[float], name: str) -> tuple[float, float]:
+    try:
+        lo, hi = (float(value[0]), float(value[1]))
+    except (TypeError, IndexError, KeyError):
+        raise ValueError(f"{name} must be a (min, max) pair, got {value!r}") from None
+    if not hi > lo:
+        raise ValueError(f"{name} must be increasing, got {value!r}")
+    return lo, hi
+
+
+def _widgets() -> tuple[type[QApplication], type[QQuickWidget]]:
+    """The QtWidgets classes the export needs, or a clear error when they are not usable."""
+    try:
+        from PySide6.QtQuickWidgets import QQuickWidget
+        from PySide6.QtWidgets import QApplication
+    except ImportError as exc:  # pragma: no cover - both ship with PySide6
+        raise RuntimeError("exporting needs QtWidgets/QtQuickWidgets (PySide6)") from exc
+    if not isinstance(QApplication.instance(), QApplication):
+        # Creating a QWidget under a bare QGuiApplication aborts the process inside Qt (and
+        # `QApplication.instance()` *is* the QGuiApplication there), so this has to be refused
+        # before the offscreen widget is touched.
+        raise RuntimeError(
+            "exporting needs a QApplication: the offscreen render uses a QQuickWidget; "
+            "create one (MathPlotWidget does it for you) or use a widgets host"
+        )
+    return QApplication, QQuickWidget
+
+
+def render(
+    plot: Plot,
+    *,
+    xlim: Sequence[float] | None = None,
+    ylim: Sequence[float] | None = None,
+    width: float | None = None,
+    height: float | None = None,
+    dpi: float = 1.0,
+    adjustable: str | None = None,
+    transparent: bool = False,
+) -> QImage:
+    """Render ``plot`` offscreen and return the grabbed image, in device pixels.
+
+    ``xlim`` / ``ylim`` default to the camera's own view (its centre and scales applied to the
+    size it was told it has — that is exactly ``camera.xlim`` / ``ylim``), ``width`` /
+    ``height`` default to the live view's device size (``dpi`` multiplies both), and
+    ``adjustable`` reconciles the two parameter sets. The pixel size changes the resolution,
+    never the region: the region cannot depend on the screen's ``devicePixelRatio``.
+    """
+    dpi = float(dpi)
+    if not dpi > 0:
+        raise ValueError(f"dpi must be positive, got {dpi!r}")
+    mode = "box" if adjustable is None else str(adjustable)      # matplotlib's own default
+    if mode not in ADJUSTABLES:
+        raise ValueError(f"adjustable must be one of {ADJUSTABLES}, got {adjustable!r}")
+    for name, value in (("width", width), ("height", height)):
+        if value is not None and not float(value) > 0:
+            raise ValueError(f"{name} must be positive, got {value!r}")
+
+    _app, quick_widget = _widgets()
+    from .view import qml_component_path, register_qml_types
+
+    register_qml_types()
+    camera = plot.camera
+    live = (camera.centre.x(), camera.centre.y(), camera.scale_x, camera.scale_y)
+    live_size = (camera.viewport.x(), camera.viewport.y())
+    background = plot.background
+
+    widget: QQuickWidget = quick_widget()
+    widget.setAttribute(Qt.WidgetAttribute.WA_DontShowOnScreen, True)
+    widget.setResizeMode(quick_widget.ResizeMode.SizeRootObjectToView)
+    widget.setFocusPolicy(Qt.FocusPolicy.NoFocus)
+    image = QImage()
+    device = (0, 0)
+    try:
+        if transparent:
+            plot.background = QColor(0, 0, 0, 0)
+            widget.setClearColor(QColor(0, 0, 0, 0))
+        widget.setSource(QUrl.fromLocalFile(qml_component_path()))
+        if widget.status() != quick_widget.Status.Ready:
+            errors = "; ".join(error.toString() for error in widget.errors())
+            raise RuntimeError(f"the QML component failed to load: {errors}")
+        root = widget.rootObject()          # the widget itself has no such property
+        if root is None:
+            raise RuntimeError("the QML component has no root object")
+        root.setProperty("plot", plot)
+
+        # width/height are device pixels, so the offscreen view gets the logical size
+        pixel_ratio = widget.devicePixelRatioF()
+        device = (
+            round((float(width) if width is not None else live_size[0] * pixel_ratio) * dpi),
+            round((float(height) if height is not None else live_size[1] * pixel_ratio) * dpi),
+        )
+        logical = (device[0] / pixel_ratio, device[1] / pixel_ratio)
+        widget.resize(round(logical[0]), round(logical[1]))
+        widget.show()                       # offscreen: WA_DontShowOnScreen, never exposed
+
+        # The range: the camera's own view — its centre and scales applied to the size it was
+        # told it has, which is exactly ``camera.xlim``/``ylim`` — unless the caller asked for
+        # one. Not ``logical`` (the export's size): the scale is world units per logical pixel
+        # *of the live view*, so deriving the range from the offscreen widget's logical size
+        # made the region depend on the screen's devicePixelRatio and silently cropped it by
+        # that factor (at DPR 1.5 a ±2.5 view came out as ±1.67 at 400×400 device pixels, and a
+        # level set whose visible arc sat at |x| > 1.67 was not drawn at all). ``width``,
+        # ``height`` and ``dpi`` change the number of pixels, never the region; a caller that
+        # wants a different region passes ``xlim``/``ylim``.
+        range_x = _pair(xlim, "xlim") if xlim is not None else (
+            live[0] - 0.5 * live_size[0] * live[2], live[0] + 0.5 * live_size[0] * live[2])
+        range_y = _pair(ylim, "ylim") if ylim is not None else (
+            live[1] - 0.5 * live_size[1] * live[3], live[1] + 0.5 * live_size[1] * live[3])
+        span_x, span_y = range_x[1] - range_x[0], range_y[1] - range_y[0]
+        centre = (0.5 * (range_x[0] + range_x[1]), 0.5 * (range_y[0] + range_y[1]))
+
+        if mode == "stretch":               # the range maps onto the size exactly
+            scale = (span_x / logical[0], span_y / logical[1])
+        elif mode == "box":                 # the live ratio, the range drawn as large as it fits
+            # The largest scale (the smallest world units per pixel) for which the requested
+            # range still fits: the binding axis is exact, the other keeps background margins.
+            # Drawn without distortion — a world circle stays round, only the visible span
+            # changes when the requested range's aspect differs from the size's.
+            ratio = live[2] / live[3]
+            scale_x = max(span_x / logical[0], ratio * span_y / logical[1])
+            scale = (scale_x, scale_x / ratio)
+        else:                               # "datalim": the live scales, the limits expand
+            scale = (max(live[2], span_x / logical[0]), max(live[3], span_y / logical[1]))
+
+        camera.setViewport(logical[0], logical[1])
+        camera.set_view(centre[0], centre[1], scale[0], scale[1])
+        image = widget.grabFramebuffer()
+    finally:
+        # Restore before the event loop runs again, so no live view repaints the export state.
+        camera.set_view(live[0], live[1], live[2], live[3])
+        camera.setViewport(live_size[0], live_size[1])
+        plot.background = background
+        widget.hide()
+        widget.deleteLater()
+
+    if image.size() != QSize(device[0], device[1]):
+        # At a fractional devicePixelRatio the offscreen widget can land within one pixel of the
+        # requested size; make the promise exact (a 1 px nearest resample is invisible).
+        image = image.scaled(
+            device[0], device[1],
+            Qt.AspectRatioMode.IgnoreAspectRatio, Qt.TransformationMode.FastTransformation,
+        )
+    return image