qmlmathplot 0.1.0__tar.gz → 0.2.0__tar.gz

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

@@ -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 → qmlmathplot-0.2.0}/README.md

@@ -27,6 +27,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:
@@ -105,7 +109,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 |
@@ -124,8 +128,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)
 
@@ -153,12 +157,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
@@ -168,6 +176,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
@@ -186,6 +274,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`) |
@@ -226,15 +316,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
@@ -244,6 +337,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)
 
@@ -344,6 +448,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
 
@@ -365,6 +475,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 → qmlmathplot-0.2.0}/pyproject.toml

@@ -1,9 +1,9 @@
 [project]
 name = "qmlmathplot"
-version = "0.1.0"
+version = "0.2.0"
 description = "Embeddable function plotter for Qt Quick / QtWidgets (implicit per-pixel drawing, MVVM)"
 readme = "README.md"
-requires-python = ">=3.14"
+requires-python = ">=3.11"
 dependencies = [
     "sympy>=1.14",
     "PySide6>=6.7",
@@ -13,6 +13,9 @@ dependencies = [
 name = "I-AM-A-NOOB"
 email = "suzc08@outlook.com"
 
+[project.optional-dependencies]
+matplotlib = ["matplotlib>=3.8"]
+
 [project.scripts]
 qmlmathplot = "qmlmathplot.app:main"
 
@@ -21,7 +24,10 @@ requires = ["uv_build>=0.12.18,<0.13.0"]
 build-backend = "uv_build"
 
 [dependency-groups]
-dev = ["pytest>=9.1.1"]
+dev = [
+    "pytest>=9.1.1",
+    "matplotlib>=3.8",
+]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

{qmlmathplot-0.1.0 → qmlmathplot-0.2.0}/pyproject.toml.orig

@@ -1,17 +1,22 @@
 [project]
 name = "qmlmathplot"
-version = "0.1.0"
+version = "0.2.0"
 description = "Embeddable function plotter for Qt Quick / QtWidgets (implicit per-pixel drawing, MVVM)"
 readme = "README.md"
 authors = [
     { name = "I-AM-A-NOOB", email = "suzc08@outlook.com" }
 ]
-requires-python = ">=3.14"
+requires-python = ">=3.11"
 dependencies = [
     "sympy>=1.14",
     "PySide6>=6.7",
 ]
 
+[project.optional-dependencies]
+# The matplotlib hand-off (Plot.to_matplotlib / savefig(backend="matplotlib")) is optional:
+# nothing in the package imports matplotlib until that path is used.
+matplotlib = ["matplotlib>=3.8"]
+
 [project.scripts]
 qmlmathplot = "qmlmathplot.app:main"
 
@@ -22,6 +27,7 @@ build-backend = "uv_build"
 [dependency-groups]
 dev = [
     "pytest>=9.1.1",
+    "matplotlib>=3.8",      # the hand-off tests need it (the feature itself stays optional)
 ]
 
 [tool.pytest.ini_options]

{qmlmathplot-0.1.0 → qmlmathplot-0.2.0}/src/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-0.1.0 → qmlmathplot-0.2.0}/src/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: