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

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

@@ -25,9 +25,11 @@ from .qsb import bake
 
 __all__ = ["Curve", "CurveListModel"]
 
-#: 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:

qmlmathplot/export.py

@@ -0,0 +1,164 @@
+"""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 (the live centre and scale, extended to the export
+    size), ``width`` / ``height`` default to the live view's device size (``dpi`` multiplies
+    both), and ``adjustable`` reconciles the two parameter sets.
+    """
+    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, extended to the export size, unless the caller asked for one
+        range_x = _pair(xlim, "xlim") if xlim is not None else (
+            live[0] - 0.5 * logical[0] * live[2], live[0] + 0.5 * logical[0] * live[2])
+        range_y = _pair(ylim, "ylim") if ylim is not None else (
+            live[1] - 0.5 * logical[1] * live[3], live[1] + 0.5 * logical[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

qmlmathplot/mpl.py

@@ -0,0 +1,232 @@
+"""Hand-off to matplotlib — and through it to sympy's plotting.
+
+This is deliberately a **second renderer**, not the one the Qt view uses, and it is a *sampled*
+one: matplotlib draws polylines, so an oscillating function such as ``sin(1/x)`` aliases exactly
+as it does in any sampling renderer — which is the reason the Qt side exists and evaluates the
+expression per pixel instead. Fonts and antialiasing differ from the Qt view as well, and the
+style mapping below is partial. What this buys is **vector output** (``.svg``/``.pdf``) and
+matplotlib's ecosystem (and sympy's plotting), nothing else.
+
+matplotlib is an *optional* dependency (the ``matplotlib`` extra): this module imports nothing
+until one of its functions is called, and ``import qmlmathplot`` never pulls it in.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import TYPE_CHECKING
+
+import sympy as sp
+
+if TYPE_CHECKING:  # pragma: no cover - typing only; the real imports stay lazy
+    from matplotlib.backends.backend_agg import FigureCanvasAgg
+    from matplotlib.figure import Figure
+
+    from .curve import Curve
+    from .plot import Plot
+
+__all__ = ["figure_for", "save_via_matplotlib", "sympy_plot_for"]
+
+#: Logical pixels to points (96 px/inch, 72 pt/inch): our sizes are in px, matplotlib's in pt.
+PX_TO_PT = 72.0 / 96.0
+#: The DPI the hand-off assumes for sizes that only exist in pixels (the live viewport).
+DEFAULT_DPI = 100.0
+_EXTRA_HINT = (
+    "the matplotlib hand-off needs the optional extra: pip install 'qmlmathplot[matplotlib]'"
+)
+
+
+def _require() -> tuple[type[Figure], type[FigureCanvasAgg]]:
+    """The matplotlib classes for a headless figure, or a clear error naming the extra."""
+    try:
+        from matplotlib.backends.backend_agg import FigureCanvasAgg
+        from matplotlib.figure import Figure
+    except ImportError as exc:                    # no matplotlib installed
+        raise ImportError(_EXTRA_HINT) from exc
+    return Figure, FigureCanvasAgg
+
+
+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 _visible_curves(plot: Plot) -> list[Curve]:
+    """The curves the Qt view would draw (a hidden curve is not handed over)."""
+    return [plot.curves.at(index) for index in range(len(plot.curves))
+            if plot.curves.at(index).visible]
+
+
+def _sample(expression: str, x0: float, x1: float, samples: int) -> tuple[object, object]:
+    """Uniform samples of one curve; NaN where the function is outside its domain.
+
+    matplotlib breaks the line at NaN, which is how the hand-off keeps ``log(x)`` from being
+    drawn for x < 0. Infinities (poles, ``1/x`` at 0) are turned into NaN as well, so a pole
+    breaks the line instead of drawing a connector across it.
+    """
+    import numpy
+
+    symbol = sp.Symbol("x")
+    try:
+        function = sp.lambdify(symbol, sp.sympify(expression, locals={"x": symbol}),
+                               modules=["numpy"])
+        with numpy.errstate(all="ignore"):        # log(x<0) etc.: NaN, not a warning storm
+            xs = numpy.linspace(x0, x1, samples)
+            ys = numpy.asarray(function(xs), dtype=float)
+    except Exception as exc:
+        # Broad on purpose: sympify, lambdify and the evaluation itself all report by raising,
+        # and the caller wants one clear message naming the expression.
+        raise ValueError(f"cannot sample {expression!r}: {exc}") from exc
+    if ys.ndim == 0:                              # a constant expression evaluates to a scalar
+        ys = numpy.full(xs.shape, float(ys))
+    ys[~numpy.isfinite(ys)] = numpy.nan
+    return xs, ys
+
+
+def figure_for(
+    plot: Plot,
+    *,
+    xlim: Sequence[float] | None = None,
+    ylim: Sequence[float] | None = None,
+    samples: int = 2000,
+    adjustable: str = "box",
+    size: tuple[float, float] | None = None,
+    dpi: float = DEFAULT_DPI,
+    transparent: bool = False,
+) -> Figure:
+    """A matplotlib ``Figure`` with one Axes, reflecting this plot as far as it maps.
+
+    ``xlim`` / ``ylim`` default to the camera's visible range; ``size`` is the figure size in
+    device pixels (default: the live viewport) and ``dpi`` turns it into inches. ``adjustable``
+    follows the export's modes: ``"box"`` and ``"datalim"`` map to matplotlib's own, and
+    ``"stretch"`` (independent scales) becomes matplotlib's ``"auto"`` aspect.
+    """
+    if adjustable not in ("box", "datalim", "stretch"):
+        raise ValueError(f'adjustable must be "box", "datalim" or "stretch", got {adjustable!r}')
+    Figure, FigureCanvasAgg = _require()
+    dpi = float(dpi)
+    if not dpi > 0:
+        raise ValueError(f"dpi must be positive, got {dpi!r}")
+
+    x_range = _pair(xlim, "xlim") if xlim is not None else (plot.xlim.x(), plot.xlim.y())
+    y_range = _pair(ylim, "ylim") if ylim is not None else (plot.ylim.x(), plot.ylim.y())
+    if size is None:                              # the live viewport, at the hand-off's dpi
+        viewport = plot.camera.viewport
+        size = (viewport.x(), viewport.y())
+    inches = (size[0] / dpi, size[1] / dpi)
+
+    figure = Figure(figsize=inches, dpi=dpi)
+    FigureCanvasAgg(figure)                       # headless canvas: no pyplot, no GUI backend
+    axes = figure.add_subplot()
+    axes.set_facecolor(plot.background.name())
+    figure.patch.set_facecolor("none" if transparent else plot.background.name())
+    axes.set_xlim(*x_range)
+    axes.set_ylim(*y_range)
+
+    if adjustable == "stretch":                   # independent scales: matplotlib's "auto"
+        axes.set_aspect("auto")
+    else:
+        aspect = plot.camera.aspect               # "auto" | number, same convention as ours
+        axes.set_aspect("auto" if isinstance(aspect, str) else float(aspect),
+                        adjustable=adjustable)
+
+    if plot.axes_position == "zero":              # our axes through world (0,0), no box
+        axes.spines["left"].set_position("zero")
+        axes.spines["bottom"].set_position("zero")
+        axes.spines["top"].set_visible(False)
+        axes.spines["right"].set_visible(False)
+    for spine in axes.spines.values():
+        spine.set_color(plot.axis_color.name())
+        spine.set_linewidth(plot.axis_width * PX_TO_PT)
+
+    axes.set_axisbelow(True)                      # the Qt view paints its grid below the curves
+    if plot.grid:
+        axes.grid(True, color=plot.grid_color.name(),
+                  linewidth=plot.grid_width * PX_TO_PT, alpha=plot.grid_alpha,
+                  linestyle=plot.grid_style)
+    else:
+        # Passing line properties together with `False` makes matplotlib *enable* the grid.
+        axes.grid(False)
+    axes.tick_params(colors=plot.tick_color.name(), labelcolor=plot.text_color.name(),
+                     labelsize=plot.tick_font_size * PX_TO_PT)
+    axes.xaxis.label.set_fontsize(plot.font_size * PX_TO_PT)
+    axes.yaxis.label.set_fontsize(plot.font_size * PX_TO_PT)
+    if plot.title:
+        axes.set_title(plot.title, color=plot.title_color.name(),
+                       fontsize=plot.title_font_size * PX_TO_PT,
+                       fontweight="bold" if plot.title_bold else "normal")
+
+    for curve in _visible_curves(plot):
+        xs, ys = _sample(curve.expression, x_range[0], x_range[1], samples)
+        axes.plot(xs, ys, color=curve.color.name(), linewidth=curve.lineWidth * PX_TO_PT,
+                  label=curve.label or curve.expression)
+    return figure
+
+
+def save_via_matplotlib(
+    plot: Plot,
+    path: str,
+    *,
+    xlim: Sequence[float] | None = None,
+    ylim: Sequence[float] | None = None,
+    samples: int = 2000,
+    adjustable: str = "box",
+    width: float | None = None,
+    height: float | None = None,
+    dpi: float = DEFAULT_DPI,
+    transparent: bool = False,
+) -> None:
+    """Write the hand-off figure with matplotlib's own ``savefig`` (svg/pdf/png/…)."""
+    size = None
+    if width is not None or height is not None:
+        viewport = plot.camera.viewport
+        size = (float(width) if width is not None else viewport.x(),
+                float(height) if height is not None else viewport.y())
+    figure = figure_for(plot, xlim=xlim, ylim=ylim, samples=samples, adjustable=adjustable,
+                        size=size, dpi=dpi, transparent=transparent)
+    figure.savefig(str(path), transparent=transparent)
+
+
+def sympy_plot_for(
+    plot: Plot,
+    *,
+    xlim: Sequence[float] | None = None,
+    ylim: Sequence[float] | None = None,
+    samples: int = 2000,
+    adaptive: bool = False,
+) -> object:
+    """Hand this plot to ``sympy.plotting``, uniform by default (``adaptive`` asks for sympy's.
+
+    Returns whatever ``sympy.plotting.plot(..., show=False)`` returns (a matplotlib-backend
+    ``Plot`` object in sympy 1.14), so ``handle.save(path)``/``handle.show()`` work, the window
+    is the same one the matplotlib hand-off would show, and every curve keeps its colour.
+    """
+    _require()                                    # sympy's plotting backend is matplotlib too
+    symbol = sp.Symbol("x")
+    curves = _visible_curves(plot)
+    if not curves:
+        raise ValueError("nothing to hand to sympy: the plot has no visible curve")
+    x_range = _pair(xlim, "xlim") if xlim is not None else (plot.xlim.x(), plot.xlim.y())
+    y_range = _pair(ylim, "ylim") if ylim is not None else (plot.ylim.x(), plot.ylim.y())
+    expressions = []
+    for curve in curves:
+        try:
+            expressions.append(sp.sympify(curve.expression, locals={"x": symbol}))
+        except Exception as exc:
+            raise ValueError(f"cannot parse {curve.expression!r}: {exc}") from exc
+    handle = sp.plotting.plot(
+        *expressions, (symbol, x_range[0], x_range[1]), show=False,
+        adaptive=adaptive,                        # see Plot.to_sympy for why False is the default
+        nb_of_points=samples,
+        label=[curve.label or curve.expression for curve in curves],
+    )
+    handle.xlim = x_range                         # the same window as the matplotlib hand-off
+    handle.ylim = y_range
+    for index, curve in enumerate(curves):        # per-series style (not a global line_color)
+        handle[index].line_color = curve.color.name()
+    return handle

qmlmathplot/plot.py

@@ -9,10 +9,11 @@ names — see ``theme``.
 from __future__ import annotations
 
 from PySide6.QtCore import Property, QObject, Signal, Slot
-from PySide6.QtGui import QColor, QVector2D
+from PySide6.QtGui import QColor, QImage, QVector2D
 
 from .camera import Camera
 from .curve import DEFAULT_COLOR_CYCLE, Curve, CurveListModel
+from .themes import names, resolve
 
 __all__ = ["Plot"]
 
@@ -60,10 +61,14 @@ class Plot(QObject):
     cameraChanged = Signal()
     curvesChanged = Signal()
     viewChanged = Signal()
-    aspectChanged = Signal()        # forwarded from the camera (the forwarded `aspect`)
+    aspectChanged = Signal()  # forwarded from the camera (the forwarded `aspect`)
     themeChanged = Signal()
 
     backgroundChanged = Signal()
+    axisColorChanged = Signal()
+    axisWidthChanged = Signal()
+    axesPositionChanged = Signal()
+    available_themesChanged = Signal()
     gridChanged = Signal()
     gridColorChanged = Signal()
     gridWidthChanged = Signal()
@@ -85,11 +90,15 @@ class Plot(QObject):
     def __init__(self, parent: QObject | None = None) -> None:
         super().__init__(parent)
         self._camera = Camera(self)
+        self._theme = ""
         self._curves = CurveListModel(DEFAULT_COLOR_CYCLE, self.line_width, self)
         self._camera.viewChanged.connect(self.viewChanged)
         self._camera.aspectChanged.connect(self.aspectChanged)
         self.cameraChanged.emit()
         self.curvesChanged.emit()
+        # matplotlib's look out of the box: the theme file is the single source of truth, so
+        # the fallbacks above and the theme agree instead of drifting apart.
+        self._set_theme("default")
 
     # ------------------------------------------------------------- the model
     def _get_camera(self) -> Camera:
@@ -128,7 +137,9 @@ class Plot(QObject):
     ylim: QVector2D = Property("QVariant", _get_ylim, _set_ylim, notify=viewChanged)
     # `aspect` is forwarded too because a QML *binding* cannot reach through an object chain
     # (`plot.camera.aspect: 1.0` is rejected by QML), while a direct property binds fine.
-    aspect: str | float = Property("QVariant", _get_aspect, _set_aspect, notify=aspectChanged)
+    aspect: str | float = Property(
+        "QVariant", _get_aspect, _set_aspect, notify=aspectChanged
+    )
 
     @Slot(str, "QVariant", "QVariant", str, result=QObject)
     @Slot(str, result=QObject)
@@ -146,23 +157,135 @@ class Plot(QObject):
     def remove_curve(self, curve: Curve) -> None:
         self._curves.remove_curve(curve)
 
+    # --------------------------------------------------------------- export
+    @Slot(result="QVariant")
+    def to_image(
+        self,
+        *,
+        xlim: object = None,
+        ylim: object = None,
+        width: float | None = None,
+        height: float | None = None,
+        dpi: float = 1.0,
+        adjustable: str | None = None,
+        transparent: bool = False,
+    ) -> QImage:
+        """Render this canvas region offscreen and return it (device pixels), see
+        ``docs/api-design.md`` §9. QML calls it with no arguments: the live view, its own size.
+        """
+        from .export import render  # lazy: a pure-QML app never needs QtWidgets
+
+        return render(
+            self,
+            xlim=xlim,
+            ylim=ylim,
+            width=width,
+            height=height,
+            dpi=dpi,
+            adjustable=adjustable,
+            transparent=transparent,
+        )
+
+    def to_matplotlib(
+        self,
+        *,
+        xlim: object = None,
+        ylim: object = None,
+        samples: int = 2000,
+        adjustable: str = "box",
+    ) -> object:
+        """Hand this plot to matplotlib and return a ``matplotlib.figure.Figure`` (one Axes).
+
+        This is a **second renderer**, and a *sampled* one: matplotlib draws polylines, so an
+        oscillating function such as ``sin(1/x)`` aliases (exactly what the Qt view avoids by
+        evaluating the expression per pixel), the fonts and antialiasing differ from the Qt
+        view, and the style mapping is partial — background, grid, per-curve colour/width,
+        tick/text colours, font sizes, title, axis colour/width, the limits, the aspect with
+        matplotlib's ``adjustable``, and ``axes_position="zero"`` (spines through the origin).
+        What it buys is vector output and matplotlib's ecosystem, nothing else. Needs the
+        optional ``matplotlib`` extra (``pip install 'qmlmathplot[matplotlib]'``).
+        """
+        from .mpl import figure_for
+
+        return figure_for(
+            self, xlim=xlim, ylim=ylim, samples=samples, adjustable=adjustable
+        )
+
+    def to_sympy(
+        self,
+        *,
+        xlim: object = None,
+        ylim: object = None,
+        samples: int = 2000,
+        adaptive: bool = False,
+    ) -> object:
+        """Hand this plot to ``sympy.plotting`` and return the Plot object it builds.
+
+        Through sympy this reaches any of sympy's plotting backends. The sampling is ours
+        (uniform, ``samples`` points) unless ``adaptive=True`` asks for sympy's own sampler; the
+        aliasing caveat of :meth:`to_matplotlib` applies either way, because an oscillating
+        function cannot be resolved by sampling at all. Measured on ``sin(1/x)`` over [-1, 1]:
+        sympy 1.14's adaptive sampler produced **289** points — *fewer* than the fixed 2000 —
+        emitted no warning, and drew the same block of vertical connectors, which is why the
+        fixed count is the default. Hidden curves are skipped, each curve keeps its colour, and a
+        passed ``ylim`` is honoured (sympy has no y-range of its own). Needs the optional
+        ``matplotlib`` extra.
+        """
+        from .mpl import sympy_plot_for
+
+        return sympy_plot_for(
+            self, xlim=xlim, ylim=ylim, samples=samples, adaptive=adaptive
+        )
+
+    @Slot(str)
+    def savefig(self, path: str, *, backend: str = "qt", **kwargs: object) -> None:
+        """Write the plot to ``path`` (the format comes from the suffix); QML passes a path only.
+
+        ``backend="qt"`` (the default) renders through the offscreen Qt view — device pixels,
+        with :meth:`to_image`'s keywords. ``backend="matplotlib"`` renders a *sampled* figure
+        through :meth:`to_matplotlib` and calls matplotlib's own ``savefig``, so vector formats
+        (``.svg``, ``.pdf``) work and the look is matplotlib's, not the Qt view's.
+        """
+        if backend == "qt":
+            if not self.to_image(**kwargs).save(str(path)):
+                raise OSError(f"could not write the export to {path!r}")
+            return
+        if backend == "matplotlib":
+            from .mpl import save_via_matplotlib
+
+            save_via_matplotlib(self, str(path), **kwargs)
+            return
+        raise ValueError(f'backend must be "qt" or "matplotlib", got {backend!r}')
+
     # -------------------------------------------------------------- styling
-    background: QColor = _style(QColor, "background", backgroundChanged, QColor("#14141e"))
-    grid: bool = _style(bool, "grid", gridChanged, True)
-    grid_color: QColor = _style(QColor, "grid_color", gridColorChanged, QColor("#2a2a3a"))
-    grid_width: float = _style(float, "grid_width", gridWidthChanged, 1.0)
-    grid_alpha: float = _style(float, "grid_alpha", gridAlphaChanged, 0.5)
+    # The fallbacks repeat matplotlib's default style (themes/default.mplstyle, applied in
+    # __init__) so a plot looks the same whether or not a theme was applied.
+    background: QColor = _style(
+        QColor, "background", backgroundChanged, QColor("white")
+    )
+    grid: bool = _style(bool, "grid", gridChanged, False)
+    grid_color: QColor = _style(
+        QColor, "grid_color", gridColorChanged, QColor("#b0b0b0")
+    )
+    grid_width: float = _style(float, "grid_width", gridWidthChanged, 1.07)
+    grid_alpha: float = _style(float, "grid_alpha", gridAlphaChanged, 1.0)
     #: "-" | "--" | ":" | "-." (QML turns it into a dash pattern).
     grid_style: str = _style(str, "grid_style", gridStyleChanged, "-")
-    text_color: QColor = _style(QColor, "text_color", textColorChanged, QColor("#c8c8d2"))
-    tick_color: QColor = _style(QColor, "tick_color", tickColorChanged, QColor("#6a6a80"))
-    tick_length: float = _style(float, "tick_length", tickLengthChanged, 6.0)
-    font_size: float = _style(float, "font_size", fontSizeChanged, 12.0)
-    tick_font_size: float = _style(float, "tick_font_size", tickFontSizeChanged, 11.0)
+    axis_color: QColor = _style(QColor, "axis_color", axisColorChanged, QColor("black"))
+    axis_width: float = _style(float, "axis_width", axisWidthChanged, 1.07)
+    text_color: QColor = _style(QColor, "text_color", textColorChanged, QColor("black"))
+    tick_color: QColor = _style(QColor, "tick_color", tickColorChanged, QColor("black"))
+    tick_length: float = _style(float, "tick_length", tickLengthChanged, 4.67)
+    font_size: float = _style(float, "font_size", fontSizeChanged, 13.33)
+    tick_font_size: float = _style(float, "tick_font_size", tickFontSizeChanged, 13.33)
     title: str = _style(str, "title", titleChanged, "")
-    title_color: QColor = _style(QColor, "title_color", titleColorChanged, QColor("#e8e8f0"))
-    title_font_size: float = _style(float, "title_font_size", titleFontSizeChanged, 15.0)
-    title_bold: bool = _style(bool, "title_bold", titleBoldChanged, True)
+    title_color: QColor = _style(
+        QColor, "title_color", titleColorChanged, QColor("black")
+    )
+    title_font_size: float = _style(
+        float, "title_font_size", titleFontSizeChanged, 16.0
+    )
+    title_bold: bool = _style(bool, "title_bold", titleBoldChanged, False)
     ticks_visible: bool = _style(bool, "ticks_visible", ticksVisibleChanged, True)
 
     def _get_color_cycle(self) -> list[str]:
@@ -176,37 +299,68 @@ class Plot(QObject):
         self._curves.set_color_cycle(tuple(cycle))
         self.colorCycleChanged.emit()
 
-    color_cycle: list[str] = Property("QVariant", _get_color_cycle, _set_color_cycle,
-                                      notify=colorCycleChanged)
+    color_cycle: list[str] = Property(
+        "QVariant", _get_color_cycle, _set_color_cycle, notify=colorCycleChanged
+    )
 
     def _get_line_width(self) -> float:
-        return float(getattr(self, "_line_width", 1.5))
+        return float(getattr(self, "_line_width", 2.0))
 
     def _set_line_width(self, value: float) -> None:
         value = float(value)
         if value == self._get_line_width():
             return
         self._line_width = value
-        self._curves.set_default_line_width(value)   # default for the curves added later
+        self._curves.set_default_line_width(value)  # default for the curves added later
         self.lineWidthChanged.emit()
 
     #: Default line width of new curves (logical pixels).
-    line_width: float = Property(float, _get_line_width, _set_line_width,
-                                 notify=lineWidthChanged)
+    line_width: float = Property(
+        float, _get_line_width, _set_line_width, notify=lineWidthChanged
+    )
+
+    def _get_axes_position(self) -> str:
+        return getattr(self, "_axes_position", "zero")
+
+    def _set_axes_position(self, value: str) -> None:
+        value = str(value)
+        if value not in ("zero", "edge"):
+            raise ValueError(f'axesPosition must be "zero" or "edge", got {value!r}')
+        if value == self._get_axes_position():
+            return
+        self._axes_position = value
+        self.axesPositionChanged.emit()
+
+    #: Where the ticks ride: the axes through world (0,0), or the item's edges.
+    axes_position: str = Property(
+        str, _get_axes_position, _set_axes_position, notify=axesPositionChanged
+    )
+
+    def _get_available_themes(self) -> list[str]:
+        return list(names())
+
+    #: Theme names a host can offer (``themes.names()``); read-only.
+    available_themes: list[str] = Property(
+        "QVariant", _get_available_themes, notify=available_themesChanged
+    )
 
     def _get_theme(self) -> str:
         return getattr(self, "_theme", "")
 
     def _set_theme(self, name: str) -> None:
-        """Apply a named theme: every entry is a style property of this object."""
-        name = str(name)
-        if name == self._get_theme():
-            return
-        from .themes import resolve      # lazy: a missing themes module must not break import
+        """Apply a named theme: every entry is a style property of this object.
 
-        resolved = resolve(name)         # unknown name -> KeyError, theme unchanged
+        Assigning a theme always applies it — that is what makes ``plot.theme = "default"`` a
+        reset back to matplotlib's look. The style setters emit only on a real change, so a
+        re-application does not churn. An unknown name raises ``KeyError`` before applying
+        anything, leaving the current look alone.
+        """
+        name = str(name)
+        resolved = resolve(name)
         for key, value in resolved.items():
             setattr(self, key, value)
+        if name == self._get_theme():
+            return
         self._theme = name
         self.themeChanged.emit()
 

qmlmathplot/qml/PlotView.qml

@@ -141,32 +141,68 @@ Item {
         }
     }
 
-    // Ticks, labels and title: screen-space furniture, so plain items.
+    // Ticks, labels, axes and title: screen-space furniture, so plain items.
     Item {
+        id: furniture
+
         anchors.fill: parent
         visible: root.plot.ticks_visible
 
+        // The axes are the lines through world (0,0). When 0 is off screen the axis sticks to
+        // the nearest edge instead, so its labels are never lost (the grid stays where it is).
+        // "edge" pins both axes to the item's edges and draws no axis line: the old behaviour.
+        readonly property bool atZero: root.plot.axes_position === "zero"
+        readonly property real xAxisY: atZero
+                                       ? Math.max(0, Math.min(height, root.mapToScreen(0, 0).y))
+                                       : height
+        readonly property real yAxisX: atZero
+                                       ? Math.max(0, Math.min(width, root.mapToScreen(0, 0).x))
+                                       : 0
+
+        Rectangle {
+            visible: furniture.atZero
+            x: 0
+            width: parent.width
+            height: root.plot.axis_width
+            y: furniture.xAxisY - height / 2
+            color: root.plot.axis_color
+        }
+        Rectangle {
+            visible: furniture.atZero
+            x: furniture.yAxisX - width / 2
+            y: 0
+            width: root.plot.axis_width
+            height: parent.height
+            color: root.plot.axis_color
+        }
+
         Repeater {
             model: root.plot.camera.ticks_x
 
+            // The mark and the label ride the x axis; both are clamped so they stay on screen
+            // when the axis is pinned to an edge (a label may never leave the item).
             delegate: Item {
                 required property var modelData
 
                 x: Math.round(root.mapToScreen(modelData[0], 0).x)
                 width: 1
-                height: root.plot.tick_length
-                anchors.bottom: parent.bottom
+                height: furniture.height
 
                 Rectangle {
-                    anchors.fill: parent
+                    y: Math.max(0, Math.min(furniture.xAxisY, furniture.height - height))
+                    width: 1
+                    height: root.plot.tick_length
                     color: root.plot.tick_color
                 }
                 Text {
                     text: modelData[1]
                     color: root.plot.text_color
                     font.pixelSize: root.plot.tick_font_size
-                    x: -Math.round(width / 2)
-                    y: -height - 3
+                    // centred on the tick, but never half off the item
+                    x: Math.max(-parent.x, Math.min(-Math.round(width / 2),
+                                                    furniture.width - width - parent.x))
+                    y: Math.max(0, Math.min(furniture.xAxisY + root.plot.tick_length + 3,
+                                            furniture.height - height))
                 }
             }
         }
@@ -177,21 +213,26 @@ Item {
             delegate: Item {
                 required property var modelData
 
+                x: 0
                 y: Math.round(root.mapToScreen(0, modelData[0]).y)
-                width: root.plot.tick_length
+                width: furniture.width
                 height: 1
-                anchors.left: parent.left
 
                 Rectangle {
-                    anchors.fill: parent
+                    x: Math.max(0, Math.min(furniture.yAxisX - width, furniture.width - width))
+                    width: root.plot.tick_length
+                    height: 1
                     color: root.plot.tick_color
                 }
                 Text {
                     text: modelData[1]
                     color: root.plot.text_color
                     font.pixelSize: root.plot.tick_font_size
-                    x: root.plot.tick_length + 3
-                    y: -Math.round(height / 2)
+                    x: Math.max(3, Math.min(furniture.yAxisX - width - 3,
+                                            furniture.width - width - 3))
+                    // centred on the tick, but never half off the item
+                    y: Math.max(-parent.y, Math.min(-Math.round(height / 2),
+                                                    furniture.height - height - parent.y))
                 }
             }
         }

qmlmathplot/themes/default.mplstyle

@@ -0,0 +1,26 @@
+# Matplotlib's default style (the values in matplotlib.rcParamsDefault), so a plot with no
+# theme looks like a matplotlib plot out of the box. Written out rather than imported because
+# Matplotlib keeps its defaults in rcParams, not in a stylelib file.
+axes.facecolor: white
+figure.facecolor: white
+axes.edgecolor: black
+axes.linewidth: 0.8
+axes.grid: False
+grid.color: b0b0b0
+grid.linestyle: -
+grid.linewidth: 0.8
+grid.alpha: 1.0
+axes.prop_cycle: cycler('color', ['1f77b4', 'ff7f0e', '2ca02c', 'd62728', '9467bd', '8c564b', 'e377c2', '7f7f7f', 'bcbd22', '17becf'])
+lines.linewidth: 1.5
+text.color: black
+axes.labelcolor: black
+xtick.color: black
+ytick.color: black
+xtick.major.size: 3.5
+ytick.major.size: 3.5
+font.size: 10
+xtick.labelsize: medium
+ytick.labelsize: medium
+axes.titlecolor: black
+axes.titlesize: large
+axes.titleweight: normal

qmlmathplot/themes.py

@@ -60,6 +60,8 @@ _SOURCES: dict[str, tuple[str, ...]] = {
     "grid_alpha": ("grid.alpha",),
     "grid_style": ("grid.linestyle",),
     "color_cycle": ("axes.prop_cycle",),
+    "axis_color": ("axes.edgecolor",),
+    "axis_width": ("axes.linewidth",),
     "line_width": ("lines.linewidth",),
     "text_color": ("text.color", "axes.labelcolor"),
     "tick_color": ("xtick.color", "ytick.color"),
@@ -75,26 +77,29 @@ _SOURCES: dict[str, tuple[str, ...]] = {
 _BOOL_KEYS = frozenset({"axes.grid", "axes.titleweight"})
 #: Keys whose value is a size in points (converted to logical pixels).
 _PT_KEYS = frozenset({
-    "grid.linewidth", "lines.linewidth", "xtick.major.size", "ytick.major.size",
+    "grid.linewidth", "lines.linewidth", "axes.linewidth",
+    "xtick.major.size", "ytick.major.size",
     "font.size", "xtick.labelsize", "ytick.labelsize", "axes.titlesize",
 })
 #: Keys whose value is a colour.
 _COLOR_KEYS = frozenset({
     "xtick.color", "ytick.color", "text.color", "axes.labelcolor", "axes.titlecolor",
-    "grid.color", "axes.facecolor", "figure.facecolor",
+    "grid.color", "axes.facecolor", "figure.facecolor", "axes.edgecolor",
 })
 
 
 def names() -> list[str]:
-    """Names of the bundled themes (file stems), plus ``"default"`` (no overrides)."""
+    """Names of the bundled themes (file stems), ``"default"`` first.
+
+    ``"default"`` is Matplotlib's default style (``themes/default.mplstyle``), which is also
+    what a Plot uses before any theme is applied, so ``plot.theme = "default"`` restores it.
+    """
     stems = sorted(p.stem for p in THEME_DIR.glob("*.mplstyle")) if THEME_DIR.is_dir() else []
-    return ["default", *stems]
+    return ["default", *(s for s in stems if s != "default")]
 
 
 def raw(name: str) -> dict[str, str]:
     """The theme's raw ``rcParams`` (key -> text value), before conversion."""
-    if name == "default":
-        return {}
     path = Path(name)
     if not path.is_file():
         path = THEME_DIR / f"{name}.mplstyle"

qmlmathplot/widget.py

@@ -37,9 +37,9 @@ class MathPlotWidget(QWidget):
     """Function plotting widget (QWidget version).
 
     :param expression: expression in sympy syntax, ``"sin(x)"`` by default
-    :param line_width: line width (logical pixels)
-    :param curve_color: curve color (``#rrggbb``)
-    :param background_color: background color (``#rrggbb``)
+    :param line_width: line width (logical pixels); None keeps the plot's own default
+    :param curve_color: curve color (``#rrggbb``); None keeps the plot's own default
+    :param background_color: background color (``#rrggbb``); None keeps the plot's own default
     :param aspect: ``"auto"`` (default) or the ratio of the y scale to the x scale
 
     The signals ``expressionChanged`` / ``errorChanged`` stay in sync with the first curve; a
@@ -54,14 +54,15 @@ class MathPlotWidget(QWidget):
         expression: str = "sin(x)",
         parent: QWidget | None = None,
         *,
-        line_width: float = 1.5,
-        curve_color: str = "#33ccff",
-        background_color: str = "#14141e",
+        line_width: float | None = None,
+        curve_color: str | None = None,
+        background_color: str | None = None,
         aspect: str | float = "auto",
     ) -> None:
         # Check before super().__init__(): constructing a QWidget without a
-        # QApplication aborts inside Qt, so the friendly error would never be reached.
-        if QApplication.instance() is None:
+        # QApplication aborts inside Qt, so the friendly error would never be reached (note
+        # that `QApplication.instance()` is the QGuiApplication in a pure-QML host).
+        if not isinstance(QApplication.instance(), QApplication):
             raise RuntimeError("please create a QApplication first — QQuickWidget needs QtWidgets")
         super().__init__(parent)
         register_qml_types()
@@ -79,8 +80,12 @@ class MathPlotWidget(QWidget):
 
         self._root = self._quick.rootObject()   # status is Ready, so this is always valid
         self._plot = Plot(self)
-        self._plot.background = background_color
-        self._plot.line_width = float(line_width)
+        # None for a style argument means "keep the plot's own default" (which the plot takes
+        # from its theme), so the widget does not re-state matplotlib's numbers.
+        if background_color is not None:
+            self._plot.background = background_color
+        if line_width is not None:
+            self._plot.line_width = float(line_width)
         self._curve = self._plot.add_curve(expression, color=curve_color, line_width=line_width)
         self._curve.expressionChanged.connect(self.expressionChanged)
         self._curve.errorChanged.connect(self.errorChanged)

{qmlmathplot-0.1.0.dist-info → qmlmathplot-0.2.0.dist-info}/METADATA

@@ -1,12 +1,14 @@
 Metadata-Version: 2.3
 Name: qmlmathplot
-Version: 0.1.0
+Version: 0.2.0
 Summary: Embeddable function plotter for Qt Quick / QtWidgets (implicit per-pixel drawing, MVVM)
 Author: I-AM-A-NOOB
 Author-email: I-AM-A-NOOB <suzc08@outlook.com>
 Requires-Dist: sympy>=1.14
 Requires-Dist: pyside6>=6.7
-Requires-Python: >=3.14
+Requires-Dist: matplotlib>=3.8 ; extra == 'matplotlib'
+Requires-Python: >=3.11
+Provides-Extra: matplotlib
 Description-Content-Type: text/markdown
 
 # QMLMathPlot
@@ -38,6 +40,10 @@ window.show()
 app.exec()
 ```
 
+An un-themed plot looks like matplotlib (white background, tab10 colours, grey grid, black
+axes through the origin with the tick labels riding them) — the default style sheet is applied
+at construction, so `plot.theme = "default"` is the reset.
+
 `MathPlotWidget` keeps one curve's worth of convenience (`expression`, `error`,
 `line_width`, `curve_color`, `background_color`, `aspect`, `view_bounds()`,
 `reset_view()`, `zoom()`, `pan_pixels()`); everything else lives on the model behind it:
@@ -116,7 +122,7 @@ The model:
 
 | Object | Members |
 |---|---|
-| `Plot` | `camera`, `curves`, `xlim`/`ylim` (forwarded), `add_curve()` / `remove_curve()`, and the style properties: `background`, `grid`, `grid_color`, `grid_width`, `grid_alpha`, `grid_style`, `color_cycle`, `line_width`, `text_color`, `tick_color`, `tick_length`, `font_size`, `tick_font_size`, `title`, `title_color`, `title_font_size`, `title_bold`, `ticks_visible`, `theme` |
+| `Plot` | `camera`, `curves`, `xlim`/`ylim`/`aspect` (forwarded), `add_curve()` / `remove_curve()`, `available_themes`, and the style properties: `background`, `grid`, `grid_color`, `grid_width`, `grid_alpha`, `grid_style`, `axis_color`, `axis_width`, `axes_position`, `color_cycle`, `line_width`, `text_color`, `tick_color`, `tick_length`, `font_size`, `tick_font_size`, `title`, `title_color`, `title_font_size`, `title_bold`, `ticks_visible`, `theme` |
 | `Camera` | `centre`, `zoom` (world units per logical pixel), `aspect`, `xlim`/`ylim` (derived), `ticks_x`/`ticks_y`, `zoomStep` / `panEnabled` / `zoomEnabled`, slots `setViewport(w, h)` / `zoom_by(delta, u, v, w, h)` / `pan_pixels(dx, dy)` / `reset()` |
 | `Curve` | `expression`, `color`, `lineWidth`, `visible`, `label`, `error` (read-only), the baked `vertexShader` / `fragmentShader` |
 | `CurveListModel` | the curves as a model (`curve`, `expression`, `color`, `lineWidth`, `visible`, `vertexShader`, `fragmentShader` roles) so QML puts one `ShaderEffect` behind each |
@@ -135,8 +141,8 @@ build order — is specified in [`docs/api-design.md`](docs/api-design.md). In s
 Matplotlib *vocabulary* is kept where it is vocabulary (limits, grid, title, ticks, annotate),
 while the *mechanism* is refused — no `Figure`/`Axes`/`subplots` (one view per widget, no
 bounded page), no `FigureCanvas`/`draw()` (the scene is live), no toolbar and no legend (host
-chrome), and an export is a canvas region at a pixel size rather than a re-rendered page (not
-implemented yet).
+chrome), and an export is a canvas region at a pixel size rather than a re-rendered page
+(§9, implemented — see *Export* below).
 
 ## The camera (centre, zoom, aspect)
 
@@ -164,12 +170,16 @@ plot.plot.camera.zoom_by(120, 0.5, 0.5, w, h)     # one wheel notch, anchored at
 
 ## Themes
 
-`Plot.theme` applies a style sheet to the style properties above:
+`Plot.theme` applies a style sheet to the style properties above; the default is
+matplotlib's own default style, so an untouched plot already looks like matplotlib and
+`plot.theme = "default"` is the reset:
 
 ```python
 plot.theme = "ggplot"                # any of the bundled sheets
+plot.theme = "default"               # back to matplotlib's look
 plot.theme = "my-style"              # themes/my-style.mplstyle next to the package
 plot.theme = "path/to/any.mplstyle"  # any file in the same format
+plot.available_themes                 # the names, for a host's picker (both demos use one)
 ```
 
 The 26 bundled sheets are Matplotlib's own styles, vendored verbatim into
@@ -179,6 +189,86 @@ have (spines, figure size, dpi, legend, marker styles, …) are ignored. `themes
 them (`"default"` plus the 26 sheets). An unknown name raises `KeyError` and leaves the current
 theme alone.
 
+## Axes, grid and ticks
+
+- The **grid** is drawn in QML (a `Canvas`), one line per tick position, in `grid_color` /
+  `grid_width` / `grid_alpha` / `grid_style` (`-`, `--`, `:`, `-.`).
+- The **axes** are the lines through world (0,0) — the x-axis at `y = 0`, the y-axis at
+  `x = 0` — drawn in `axis_color` / `axis_width`, and the **tick marks and labels ride those
+  axes** instead of hugging the item's edges. When 0 is off screen the axis sticks to the
+  nearest edge, so its labels are never lost (and a label never leaves the item); the grid
+  stays where it is. `plot.axes_position = "edge"` restores the edge-pinned behaviour.
+- `camera.viewport` reports the last size the view sent, so a host can size an export from it.
+- The tick *values* are nice numbers computed in Python (`Camera.tick_values()` /
+  `nice_ticks()`, steps of 1/2/5 x 10^n) and pushed through `ticksChanged`; QML only positions
+  and formats them, so a frame never recomputes ticks.
+- `plot.ticks_visible = False` hides the whole furniture (axes, marks and labels).
+
+## Export
+
+`savefig()` writes a file, `to_image()` returns a `QImage`; both take the same keywords:
+
+```python
+plot.savefig("out.png", xlim=(-1, 1), ylim=(-1, 1), width=1200, height=400)
+plot.savefig("hi.png", dpi=2.0)                        # the live view, twice the pixels
+image = plot.to_image(width=800, height=600)           # -> QImage
+plot.to_image()                                        # the live view, its own size
+```
+
+- `xlim` / `ylim` default to the **camera**: the live centre and scale, extended to the export
+  size. The *region* is a parameter, so an export can cover more canvas than the widget shows.
+- `width` / `height` are **device pixels** and default to the live view's device size; `dpi`
+  multiplies both (`dpi=2.0` doubles the pixels).
+- `adjustable` reconciles a requested range with a requested size when their aspects disagree —
+  Matplotlib's parameter, and its own default:
+
+  | `adjustable` | What happens |
+  |---|---|
+  | `"box"` (**default**) | one scale, taken from the live scale ratio, chosen so the requested range fits: the range is centred and the leftover pixels stay background — *nothing is distorted* |
+  | `"datalim"` | the camera's own scales, with the limits expanding (never cropped) to fill the size |
+  | `"stretch"` | the requested range maps onto the requested size exactly — independent scales, so a mismatched aspect **distorts** (the "report figure" mode) |
+
+  With no explicit range all three agree, because the range derived from the camera already has
+  the export size's aspect.
+- `transparent=True` clears to alpha 0.
+- Everything else follows the live styling (curves, grid, axes, theme), so an export cannot
+  drift from what the user sees. Rendering goes through an offscreen `QQuickWidget`, so the
+  export needs a `QApplication` (a clear error is raised instead of a crash if there is none).
+
+### Vector output, matplotlib and sympy
+
+`to_matplotlib()` hands the plot to matplotlib (one `Axes`) and `savefig(..., backend="matplotlib")`
+renders through it, so `.svg`/`.pdf` work; `to_sympy()` builds the same figure through
+`sympy.plotting`, which is what you want when the figure should live in sympy's world:
+
+```python
+figure = plot.to_matplotlib(xlim=(-1, 1), ylim=(-1, 1))    # -> matplotlib.figure.Figure
+plot.savefig("out.svg", backend="matplotlib")              # vector, matplotlib's own savefig
+handle = plot.to_sympy(xlim=(-1, 1))
+handle.save("out.png")
+```
+
+matplotlib is an **optional** extra (`pip install "qmlmathplot[matplotlib]"`); nothing in the
+package imports it until one of these is called, and the error names the extra. `sympy` itself is
+a hard dependency, so `to_sympy()` needs matplotlib only because its plotting backend does.
+Neither hand-off needs a Qt application: a `Plot` works in a plain script, which is what makes it
+usable next to a notebook or a matplotlib-only tool.
+
+**This is a second renderer, and a sampled one.** matplotlib draws polylines, so each curve is
+evaluated at `samples` points (default 2000) and an oscillating function such as `sin(1/x)`
+aliases — exactly what the Qt view avoids by evaluating the expression per pixel. SymPy does not
+solve it either, and its adaptive mode does not help: measured on `sin(1/x)` over [-1, 1],
+`sympy.plotting.plot(adaptive=True)` uses **289** points (fewer than a fixed 2000), emits no
+warning in sympy 1.14, and draws the same block of vertical connectors. The difference is how
+the two fail: a sampled renderer draws an artefact, the Qt view draws the envelope the data
+actually supports. (`to_sympy()` returns the object sympy made, so its own `adaptive` mode is
+available there.) Fonts and antialiasing are matplotlib's, not the Qt view's, so the two
+renderers cannot look identical, and the style mapping is partial: background, grid (on/off and
+colour/width/alpha/dash), per-curve colour and width, tick and text colours, font sizes, title,
+axis colour/width, the limits, the aspect with matplotlib's own `adjustable`, and
+`axes_position="zero"` (spines through the origin, no box). What it buys is vector output and
+matplotlib's ecosystem — nothing else.
+
 ## RHI backends
 
 `--backend {d3d11,d3d12,vulkan,metal,opengl,null}`; **if unspecified, Qt's default
@@ -197,6 +287,8 @@ backend is used**. The implementation sets `QSG_RHI_BACKEND` before
 | Plot | `src/qmlmathplot/plot.py` | `Plot`: the camera, the curves and the styling the view binds to |
 | View | `src/qmlmathplot/qml/PlotView.qml` (+ `view.py`) | QML: background, grid, ticks/title, one `ShaderEffect` per curve, pan/zoom input; `view.py` registers the types and yields the component path |
 | Themes | `src/qmlmathplot/themes.py` + `themes/` | the vendored Matplotlib style sheets, resolved onto the `Plot`'s properties |
+| Export | `src/qmlmathplot/export.py` | `Plot.savefig()` / `to_image()`: the canvas region rendered offscreen at a pixel size (QtWidgets is imported lazily) |
+| Hand-off | `src/qmlmathplot/mpl.py` | `Plot.to_matplotlib()` / `to_sympy()` / `savefig(backend="matplotlib")`: a sampled second renderer for vector output (matplotlib is an optional extra, imported lazily) |
 | Bake | `src/qmlmathplot/qsb.py` | GLSL → `.qsb` (PySide6 ships `qsb.exe`), cached by source hash |
 | Widget | `src/qmlmathplot/widget.py` | `MathPlotWidget`: QQuickWidget bridge, drops straight into QtWidgets layouts |
 | Entry | `src/qmlmathplot/app.py` | command line / standalone window (the `qmlmathplot` script, `examples/minimal.py`) |
@@ -237,15 +329,18 @@ QSG_RHI_BACKEND=opengl uv run pytest -m gui
 - `test_curve.py`: a failed expression keeps the last working shaders, the style
   setters are idempotent, and the list model reports the right roles.
 - `test_plot.py`: the plot's properties convert, notify exactly once and are wired
-  (a PySide property with an unresolved notify name silently loses it), the limits
-  are forwarded to the camera, and a theme applies / an unknown name is rejected.
+  (a PySide property with an unresolved notify name silently loses it), the defaults are
+  matplotlib's default style, the limits are forwarded to the camera, and a theme applies
+  (and re-applies as a reset) while an unknown name is rejected.
 - `test_themes.py`: the vendored style sheets resolve to this library's properties.
 - `test_shader_bake.py`: the stage of a baked `.qsb` must match its purpose, and
   the four backend targets GLSL/HLSL/MSL/SPIR-V must all be covered.
 - `test_render_smoke.py`: open a window, render, read pixels; verify the thin-line
   shape, `sin(1/x)` filling its ±1 envelope, no |y|>1 artefacts outside the central
   columns, poles not connected, nothing drawn outside the domain, and the QML
-  furniture (grid lines exactly at the tick positions, ticks/labels, title).
+  furniture (grid lines exactly at the tick positions, the axes crossing at the origin
+  with their labels on them, the axis pinning to the edge once the origin is panned
+  away, the title).
 - `test_widget.py`: `MathPlotWidget` coexisting with neighbouring widgets — the plot
   appearing inside a layout, an expression change / an invalid expression keeping the
   previous graph, curves added/hidden/removed through the model, **the wheel over a
@@ -255,6 +350,17 @@ QSG_RHI_BACKEND=opengl uv run pytest -m gui
   needs one, and a process may only have one).
 - `test_qtquick_coexistence.py`: the same drag conflict in Qt Quick (a `Flickable`
   must not steal the pan).
+- `test_handoff.py`: the matplotlib/sympy hand-off — the figure reflects the limits, aspect,
+  `adjustable`, grid, title, spines at zero and per-curve style; the sampling is uniform and NaN
+  outside the domain (so `log(x)` breaks); `savefig(backend="matplotlib")` writes real `.svg`,
+  `.pdf` and `.png`; `to_sympy().save()` writes a file and keeps per-curve colours; importing
+  `qmlmathplot` does not import matplotlib, and hiding matplotlib produces an error naming the
+  extra.
+- `test_export.py`: `to_image()`/`savefig()` — the image is exactly the requested device size
+  (`dpi` multiplies it), the no-argument form reproduces the live centre and scale, the three
+  `adjustable` modes reconcile range and size as documented (a world 45-degree line stays at 45
+  in `"box"`, with background margins; `"stretch"` fills the frame and distorts), the live
+  camera and background survive an export, and `transparent` clears to alpha 0.
 
 ## Pitfalls near the `sin(1/x)` singularity (fixed — do not repeat)
 
@@ -355,6 +461,12 @@ measurement that settled each one). The Qt/packaging ones that shaped the code:
   same x 9 times, and macros are preprocessor expansion with no call semantics.
 - PySide ties a property's notify signal to the `Signal` **object**; a name string
   silently leaves the property without one (and QML bindings then never refresh).
+- Snap **hairlines** (grid) to a half pixel, but never a **styled** line: rounding the
+  axis position put the 1.07 px y-axis half off the centre column, so the line came out
+  pale where it should be black.
+- `QQuickWidget.setProperty(name, …)` sets it on the **widget**, not on the QML root (the
+  widget has no such property, so it silently does nothing): inject the model with
+  `widget.rootObject().setProperty("plot", plot)`, as `MathPlotWidget` does.
 
 ## Releasing
 
@@ -376,6 +488,12 @@ be rehearsed:
 pip install -i https://test.pypi.org/simple/ qmlmathplot
 ```
 
+If the publish step fails with `invalid-publisher: valid token, but no corresponding
+publisher`, the trusted-publisher entry is missing or does not match. The action prints the
+claims it presented (`repository`, `workflow_ref`, `environment`) — the entry must match them
+exactly, **including the environment name**, and it must exist on the index the run targets: a
+manual run goes to **test.pypi.org**, a tag push to **pypi.org**, so both need an entry.
+
 The workflow runs on Windows: that is the platform this library is verified on (the shader baker
 `qsb` ships inside the PySide6 wheel and is only confirmed to be present there, see `qsb.py`),
 and the GUI tests need a GPU scene graph no runner has. The artifact is `py3-none-any`, so the

{qmlmathplot-0.1.0.dist-info → qmlmathplot-0.2.0.dist-info}/RECORD

@@ -1,10 +1,12 @@
 qmlmathplot/__init__.py,sha256=C_fYVkO8WQPVW1K_wvjdH8OniRbUpdCkIPB-ULvP6Kk,2832
 qmlmathplot/app.py,sha256=9ojtrU9_wIcgUq7Ib449KRkuLSsr7FLzSBNguI-T8l4,3124
-qmlmathplot/camera.py,sha256=CJQ71gMNE-hx3ns1fiLT0j8sJulllnKeYyrZm7fOZrY,15480
-qmlmathplot/curve.py,sha256=BaRhxcLSoX0rLpaiSOrUF52uypDqHu_iVvRToEMtdos,10587
+qmlmathplot/camera.py,sha256=YSLtGODs_efGwmtKbjT9osss-jmyV7MaLEYOu_zcxg0,16894
+qmlmathplot/curve.py,sha256=Q-3S8WhsHWanWnZXkHH_nak8q7CXDHSioqyUyblKQJ0,10723
+qmlmathplot/export.py,sha256=QfoE4TKnKt-xdaUAkB8IsyupyfwFKu8hn0ikKp8mzrI,8065
 qmlmathplot/model.py,sha256=WAY2VyoMKR5vGkPxrr2GOfUnl0xXW01ntfQ_qW8i2Wg,24961
-qmlmathplot/plot.py,sha256=4uG3EOat_F1wQRQ-BGmOAqnK1lBQ0h-pPJrzDD3Dq_I,8955
-qmlmathplot/qml/PlotView.qml,sha256=PBIEwAXGDVpoJEzwUdXDk2FIZqkOak6He4VsVEUJq5w,9249
+qmlmathplot/mpl.py,sha256=Liaqq1NWBjuSe95uxBsx2YbUULU4F5kvcvWDQErnE-Y,10684
+qmlmathplot/plot.py,sha256=XDp_Jg2FQLQLDmUhUy5tuzAFCerihwitaBICp4i_xuA,15306
+qmlmathplot/qml/PlotView.qml,sha256=4XfSGcmlsD6LNua_qhB5DtVuL-PTFO3gG4LhJzzQC7M,11519
 qmlmathplot/qsb.py,sha256=kTaC3hKAZYSNU5M2ySRFcWUdwTZT8DAHUdsUgKRCanc,3964
 qmlmathplot/themes/LICENSE.matplotlib,sha256=ojr3trhyymyw7GeYxkhO2JYoAxUVscbgMFz9b1qrcVM,4928
 qmlmathplot/themes/README.md,sha256=4IHDS6yasksnvrWvhEa5b5aUIa73US2C72-ndS3blow,767
@@ -12,6 +14,7 @@ qmlmathplot/themes/Solarize_Light2.mplstyle,sha256=En_R213nyEuOVDRw_RyN51uYLgJFP
 qmlmathplot/themes/bmh.mplstyle,sha256=IxH21Mw1K17WATUfza3HdG7uBdT1-Sksv0H0P9DsiVY,714
 qmlmathplot/themes/classic.mplstyle,sha256=ewUO1vd72JCowfCwc5i3CJrt1X5wmjSI1UzcSNNhXzc,25082
 qmlmathplot/themes/dark_background.mplstyle,sha256=8nQHo3xgzWx6SPf8rsQ2gT89NXyQHaLhkgsDbAantGk,633
+qmlmathplot/themes/default.mplstyle,sha256=2fVjCiF2yDrw87nz0i4k39fY3izejl5AZ-OKF9SlXwU,869
 qmlmathplot/themes/fast.mplstyle,sha256=HDqa0GATC9GjNeRA8rYiZM-qh7hTxsraeyYziGlbgzg,299
 qmlmathplot/themes/fivethirtyeight.mplstyle,sha256=lkCjlDtqUnDiMxEr6BDa-qMMIfVDxVS8ycfJcv8bmtw,817
 qmlmathplot/themes/ggplot.mplstyle,sha256=S7Oc_ty3DpUM0A2kctZBemMjj7IS0ccJl06QJFQh2Xw,995
@@ -34,10 +37,10 @@ qmlmathplot/themes/seaborn-v0_8-white.mplstyle,sha256=VY6sw8wkqbl0leWtWa5gz8xfDM
 qmlmathplot/themes/seaborn-v0_8-whitegrid.mplstyle,sha256=IOm2H1utXO_zR7FWqMLBiRxHyxABL3kq1fh0-6BDJ0E,694
 qmlmathplot/themes/seaborn-v0_8.mplstyle,sha256=N9lUFHvOn06wT4MODXpVVGQMSueONejeAfCX5UfWrIM,1187
 qmlmathplot/themes/tableau-colorblind10.mplstyle,sha256=PzUMoOtw0V6l0bPk8ApRAKvcxdJmzRU2bVOkNqz8DnU,192
-qmlmathplot/themes.py,sha256=Ny_B1ydTsIsiNqnj-Je68seRU62UQ9VLiDBwpVS3-JA,8937
+qmlmathplot/themes.py,sha256=QocZLOgPYXCJW9fYc6i5q6nHEE_S4mQVZXySZ4ISCPw,9225
 qmlmathplot/view.py,sha256=G6W0WfI4yT0eX4rHswqwu3y48MQTXjcA0BnWpIS1vD0,1746
-qmlmathplot/widget.py,sha256=CGszc9CqmS0-zFDQUs2vJm_xPjPY1ukEtjEtsF5BXEU,7406
-qmlmathplot-0.1.0.dist-info/WHEEL,sha256=3iQx15CyXwGi4dbygedzA4M5T1eqO_SjwdPfUmqt2Cw,81
-qmlmathplot-0.1.0.dist-info/entry_points.txt,sha256=4z36D_RpPSYLiJDRM8iXnrSe1T4c2alfQJPcJTss3qY,54
-qmlmathplot-0.1.0.dist-info/METADATA,sha256=tmTr3CjN0lr7ARxm8LmyFbio0jDXobWy9MiUfVU37zQ,22103
-qmlmathplot-0.1.0.dist-info/RECORD,,
+qmlmathplot/widget.py,sha256=HXSQko0YwixG0bx--BP6k_Fd_fn-58P-ywT2-HZw0E0,7899
+qmlmathplot-0.2.0.dist-info/WHEEL,sha256=xTCBFIZIIyRSxyowOv5Wqg_jFU6KsdIffuulBB09Ph8,80
+qmlmathplot-0.2.0.dist-info/entry_points.txt,sha256=4z36D_RpPSYLiJDRM8iXnrSe1T4c2alfQJPcJTss3qY,54
+qmlmathplot-0.2.0.dist-info/METADATA,sha256=qlC49LZEVjSKctg5FELNUSiMnUkisgwwAd5VtKONzqU,30542
+qmlmathplot-0.2.0.dist-info/RECORD,,

{qmlmathplot-0.1.0.dist-info → qmlmathplot-0.2.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: uv 0.12.24
+Generator: uv 0.13.0
 Root-Is-Purelib: true
 Tag: py3-none-any