qmlmathplot 0.1.0__tar.gz → 0.3.0__tar.gz

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

@@ -1,12 +1,14 @@
 Metadata-Version: 2.3
 Name: qmlmathplot
-Version: 0.1.0
+Version: 0.3.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,22 @@ 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.
+
+`add_curve()` (and `Curve.expression`) accept the expression **either as a string or as a sympy
+expression**: `plot.add_curve(sp.sin(1 / sp.Symbol("x")))` is the same curve as
+`plot.add_curve("sin(1/x)")`. The stored and reported form is always the canonical string — QML,
+a project file and the text field want one — while the parsed expression is cached and exposed as
+`Curve.expr`, which is what re-baking and the matplotlib hand-off use. The object form exists so a
+curve can be composed without string interpolation:
+
+```python
+curve = plot.add_curve("sin(x)")
+plot.add_curve(sp.diff(sp.sympify(curve.expression, locals={"x": sp.Symbol("x")})), label="f'")
+```
+
 `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,9 +134,9 @@ 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()` / `add_implicit()` / `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` |
+| `Curve` | `expression` (string or sympy expression), `expr` (the parsed expression, read-only), `implicit`, `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 |
 
 Every setter is a Qt `Property` with a notify signal, so the same calls work from QML, from a
@@ -135,8 +153,37 @@ 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).
+
+## Implicit curves
+
+An expression whose free symbols are `x` **and** `y` is drawn as the level set `F(x, y) = 0`.
+The artist follows the expression, whoever sets it: `add_curve` routes it by itself, assigning to
+`curve.expression` re-routes the same curve (so a text field can turn `sin(x)` into a circle),
+and `add_implicit` asks for the level-set artist explicitly — also for a function of `x` alone,
+which is a pair of vertical lines. Only a *third* free symbol is refused: substitute parameters
+first.
+
+```python
+plot.add_curve("x**2 + y**2 - 1")        # a circle: {x, y} routes to the level-set artist
+plot.add_implicit("x*y - 1")             # the same artist, asked for by name
+plot.curves.at(0).expression = "x**2 + y**2 - 4"   # re-routes the curve that is already there
+plot.add_curve("a*sin(x)")               # ValueError: substitute `a` first
+```
+
+The renderer is the same idea as the 1-D stroke, one dimension up: one evaluation of `F` and its
+two partials per pixel give the distance to the level set in *pixels*,
+`d = |F| / sqrt((Fx·dx)² + (Fy·dy)²)`, and the coverage is `clamp(lineWidth/2 + 0.5 - d, 0, 1)` —
+analytic antialiasing and a stroke width that does not depend on the angle, with no sampling grid
+(the unit circle measures the same 3 device pixels at 0°, 45°, 90° and 135° for `lineWidth=2` at
+DPR 1.5).
+
+Known limit: **smooth, single-sheet level sets**. Thin features and several branches through one
+pixel (`sin(1/(x*x + y*y))`), and 2-D domains/poles, are not handled yet — the assessment is
+`docs/api-design.md` §6b; pixels where `F` is undefined are dropped. The matplotlib hand-off
+skips implicit curves (a level set has no polyline to sample), while the Qt export renders them
+like anything else.
 
 ## The camera (centre, zoom, aspect)
 
@@ -164,12 +211,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 +230,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
@@ -189,6 +320,14 @@ backend is used**. The implementation sets `QSG_RHI_BACKEND` before
 
 ## Structure (model / view)
 
+The layers are strict about Qt. **`model.py` (expression → GLSL), `themes.py` (style-sheet
+conversion) and `mpl.py` (the sampled hand-off) import no Qt at all** — they are unit-testable
+without a `QApplication`. `Camera`, `Curve` and `Plot` are the **ViewModel**: `QObject`s whose
+`Property`es carry notify signals, which is precisely what the QML component binds to — and why
+a Python-side assignment updates the view with no call in between. `view.py`, `PlotView.qml`,
+`export.py` and `widget.py` are the View/embedding layer and do need Qt; `export.py` and
+`widget.py` import QtWidgets lazily, so a pure-QML host never loads it.
+
 | Layer | File | Responsibility |
 |---|---|---|
 | Model | `src/qmlmathplot/model.py` | expression → GLSL, shader source template (no Qt dependency, unit-testable) |
@@ -197,6 +336,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`) |
@@ -235,17 +376,25 @@ QSG_RHI_BACKEND=opengl uv run pytest -m gui
   (the home view at the first size, resize keeping the scale, an anchored zoom that
   is exactly reversible, the aspect expanding but never cropping, ticks).
 - `test_curve.py`: a failed expression keeps the last working shaders, the style
-  setters are idempotent, and the list model reports the right roles.
+  setters are idempotent, and the list model reports the right roles — plus the
+  `Expr`/string round-trip accounting (a string is parsed once, an expression never).
+- `test_implicit.py`: the routing by free symbols (and the `ValueError` for a third symbol), the
+  level-set shader text (same uniform block as the 1-D one, no sampling loop), and the rendered
+  geometry of a unit circle: crossings a quarter of the height from each edge, a blank middle,
+  radius 1 on both axes, and a stroke of the same width at 0°/45°/90°/135°.
 - `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 +404,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)
 
@@ -285,15 +445,21 @@ extrema/zeros by bisection. The same approach is used here:
   perpendicular foot lands on a segment (on a sloped line it is displaced along x
   by `m·d/√(1+m²)`); with a narrower window the distance degraded to "distance to
   the nearest endpoint" and steep parts looked thin and ragged.
-- **Break on jumps**: via the **analytic pole gap** (denominator sign change, world
-  units) — no vertical connector is drawn at the asymptotes of `1/x`, `tan(x)`.
-  (An earlier "adjacent samples differ by more than 4 viewport heights" criterion
-  was pixel-/viewport-relative, so under magnification it also cut legitimate steep
-  segments; it was removed.)
+- **Break on jumps**: a denominator sign change (world units) decides, in three places,
+  that nothing joins the branches — the polyline segment that straddles the pole is not
+  stroked, a straddling pair does not count as a turn in the band's turn count (it used to
+  fill the pole column solid), and the unbounded-boundary ray is not drawn there. No vertical
+  connector at the asymptotes of `1/x`, `tan(x)`. (An earlier "adjacent samples differ by
+  more than 4 viewport heights" criterion was pixel-/viewport-relative, so under magnification
+  it also cut legitimate steep segments; it was removed. The remaining "spread beyond 32
+  viewport heights" gap is a second line of defence only — at `tan`'s pole column the spread
+  is ~15 viewports, so it never fires there.)
 - **Domain** (derived by sympy, injected as `DOM`): denominator ≠ 0, `log` argument
   > 0, `sqrt` argument ≥ 0, `asin/acos` argument ∈ [−1,1]; pixels outside the domain
-  are discarded outright. NaN/inf samples take part in neither the envelope nor
-  segment joining.
+  are discarded outright — except for the **boundary ray** of a slowly diverging edge
+  (`log(x)` as x→0+), which is a band centred *on* the boundary and therefore paints the few
+  pixels outside the domain that it covers (the whole outer half of that band, otherwise).
+  NaN/inf samples take part in neither the envelope nor segment joining.
 - **Undersampled columns** (several oscillations inside one column) are replaced
   wholesale by the envelope band: a polyline is random sawtooth in such columns.
   There are two criteria, both **scale-independent**: (a) ≥ 2 direction reversals
@@ -355,6 +521,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 +548,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.3.0}/README.md

@@ -27,6 +27,22 @@ 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.
+
+`add_curve()` (and `Curve.expression`) accept the expression **either as a string or as a sympy
+expression**: `plot.add_curve(sp.sin(1 / sp.Symbol("x")))` is the same curve as
+`plot.add_curve("sin(1/x)")`. The stored and reported form is always the canonical string — QML,
+a project file and the text field want one — while the parsed expression is cached and exposed as
+`Curve.expr`, which is what re-baking and the matplotlib hand-off use. The object form exists so a
+curve can be composed without string interpolation:
+
+```python
+curve = plot.add_curve("sin(x)")
+plot.add_curve(sp.diff(sp.sympify(curve.expression, locals={"x": sp.Symbol("x")})), label="f'")
+```
+
 `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,9 +121,9 @@ 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()` / `add_implicit()` / `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` |
+| `Curve` | `expression` (string or sympy expression), `expr` (the parsed expression, read-only), `implicit`, `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 |
 
 Every setter is a Qt `Property` with a notify signal, so the same calls work from QML, from a
@@ -124,8 +140,37 @@ 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).
+
+## Implicit curves
+
+An expression whose free symbols are `x` **and** `y` is drawn as the level set `F(x, y) = 0`.
+The artist follows the expression, whoever sets it: `add_curve` routes it by itself, assigning to
+`curve.expression` re-routes the same curve (so a text field can turn `sin(x)` into a circle),
+and `add_implicit` asks for the level-set artist explicitly — also for a function of `x` alone,
+which is a pair of vertical lines. Only a *third* free symbol is refused: substitute parameters
+first.
+
+```python
+plot.add_curve("x**2 + y**2 - 1")        # a circle: {x, y} routes to the level-set artist
+plot.add_implicit("x*y - 1")             # the same artist, asked for by name
+plot.curves.at(0).expression = "x**2 + y**2 - 4"   # re-routes the curve that is already there
+plot.add_curve("a*sin(x)")               # ValueError: substitute `a` first
+```
+
+The renderer is the same idea as the 1-D stroke, one dimension up: one evaluation of `F` and its
+two partials per pixel give the distance to the level set in *pixels*,
+`d = |F| / sqrt((Fx·dx)² + (Fy·dy)²)`, and the coverage is `clamp(lineWidth/2 + 0.5 - d, 0, 1)` —
+analytic antialiasing and a stroke width that does not depend on the angle, with no sampling grid
+(the unit circle measures the same 3 device pixels at 0°, 45°, 90° and 135° for `lineWidth=2` at
+DPR 1.5).
+
+Known limit: **smooth, single-sheet level sets**. Thin features and several branches through one
+pixel (`sin(1/(x*x + y*y))`), and 2-D domains/poles, are not handled yet — the assessment is
+`docs/api-design.md` §6b; pixels where `F` is undefined are dropped. The matplotlib hand-off
+skips implicit curves (a level set has no polyline to sample), while the Qt export renders them
+like anything else.
 
 ## The camera (centre, zoom, aspect)
 
@@ -153,12 +198,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 +217,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
@@ -178,6 +307,14 @@ backend is used**. The implementation sets `QSG_RHI_BACKEND` before
 
 ## Structure (model / view)
 
+The layers are strict about Qt. **`model.py` (expression → GLSL), `themes.py` (style-sheet
+conversion) and `mpl.py` (the sampled hand-off) import no Qt at all** — they are unit-testable
+without a `QApplication`. `Camera`, `Curve` and `Plot` are the **ViewModel**: `QObject`s whose
+`Property`es carry notify signals, which is precisely what the QML component binds to — and why
+a Python-side assignment updates the view with no call in between. `view.py`, `PlotView.qml`,
+`export.py` and `widget.py` are the View/embedding layer and do need Qt; `export.py` and
+`widget.py` import QtWidgets lazily, so a pure-QML host never loads it.
+
 | Layer | File | Responsibility |
 |---|---|---|
 | Model | `src/qmlmathplot/model.py` | expression → GLSL, shader source template (no Qt dependency, unit-testable) |
@@ -186,6 +323,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`) |
@@ -224,17 +363,25 @@ QSG_RHI_BACKEND=opengl uv run pytest -m gui
   (the home view at the first size, resize keeping the scale, an anchored zoom that
   is exactly reversible, the aspect expanding but never cropping, ticks).
 - `test_curve.py`: a failed expression keeps the last working shaders, the style
-  setters are idempotent, and the list model reports the right roles.
+  setters are idempotent, and the list model reports the right roles — plus the
+  `Expr`/string round-trip accounting (a string is parsed once, an expression never).
+- `test_implicit.py`: the routing by free symbols (and the `ValueError` for a third symbol), the
+  level-set shader text (same uniform block as the 1-D one, no sampling loop), and the rendered
+  geometry of a unit circle: crossings a quarter of the height from each edge, a blank middle,
+  radius 1 on both axes, and a stroke of the same width at 0°/45°/90°/135°.
 - `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 +391,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)
 
@@ -274,15 +432,21 @@ extrema/zeros by bisection. The same approach is used here:
   perpendicular foot lands on a segment (on a sloped line it is displaced along x
   by `m·d/√(1+m²)`); with a narrower window the distance degraded to "distance to
   the nearest endpoint" and steep parts looked thin and ragged.
-- **Break on jumps**: via the **analytic pole gap** (denominator sign change, world
-  units) — no vertical connector is drawn at the asymptotes of `1/x`, `tan(x)`.
-  (An earlier "adjacent samples differ by more than 4 viewport heights" criterion
-  was pixel-/viewport-relative, so under magnification it also cut legitimate steep
-  segments; it was removed.)
+- **Break on jumps**: a denominator sign change (world units) decides, in three places,
+  that nothing joins the branches — the polyline segment that straddles the pole is not
+  stroked, a straddling pair does not count as a turn in the band's turn count (it used to
+  fill the pole column solid), and the unbounded-boundary ray is not drawn there. No vertical
+  connector at the asymptotes of `1/x`, `tan(x)`. (An earlier "adjacent samples differ by
+  more than 4 viewport heights" criterion was pixel-/viewport-relative, so under magnification
+  it also cut legitimate steep segments; it was removed. The remaining "spread beyond 32
+  viewport heights" gap is a second line of defence only — at `tan`'s pole column the spread
+  is ~15 viewports, so it never fires there.)
 - **Domain** (derived by sympy, injected as `DOM`): denominator ≠ 0, `log` argument
   > 0, `sqrt` argument ≥ 0, `asin/acos` argument ∈ [−1,1]; pixels outside the domain
-  are discarded outright. NaN/inf samples take part in neither the envelope nor
-  segment joining.
+  are discarded outright — except for the **boundary ray** of a slowly diverging edge
+  (`log(x)` as x→0+), which is a band centred *on* the boundary and therefore paints the few
+  pixels outside the domain that it covers (the whole outer half of that band, otherwise).
+  NaN/inf samples take part in neither the envelope nor segment joining.
 - **Undersampled columns** (several oscillations inside one column) are replaced
   wholesale by the envelope band: a polyline is random sawtooth in such columns.
   There are two criteria, both **scale-independent**: (a) ≥ 2 direction reversals
@@ -344,6 +508,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 +535,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