qmlmathplot 0.4.1__tar.gz → 0.4.2__tar.gz

{qmlmathplot-0.4.1 → qmlmathplot-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: qmlmathplot
-Version: 0.4.1
+Version: 0.4.2
 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>
@@ -143,11 +143,13 @@ The model:
 
 | Object | Members |
 |---|---|
-| `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`, `xlabel`, `ylabel`, `title_color`, `title_font_size`, `title_bold`, `ticks_visible`, `theme` |
+| `Plot` | `camera`, `curves`, `annotations`, `guides`, `xlim`/`ylim`/`aspect` (forwarded), `add_curve()` / `add_implicit()` / `remove_curve()`, `annotate()` / `add_text()` / `add_hline()` / `add_vline()`, `set_xticks()` / `set_yticks()`, `available_themes`, and the style properties: `background`, `grid`, `grid_x`, `grid_y`, `grid_color`, `grid_width`, `grid_alpha`, `grid_style`, `axis_color`, `axis_width`, `axes_position`, `color_cycle`, `line_width`, `text_color`, `tick_color`, `tick_length`, `tick_width`, `tick_pad`, `ticks_top`, `ticks_right`, `minor_ticks`, `spine_top` / `spine_bottom` / `spine_left` / `spine_right`, `font_size`, `tick_font_size`, `title`, `xlabel`, `ylabel`, `title_color`, `title_font_size`, `title_bold`, `legend`, `legend_position`, `ticks_visible`, `theme` |
 | `Camera` | `centre`, `zoom` (world units per logical pixel), `aspect`, `xlim`/`ylim` (derived), `ticks_x`/`ticks_y`, `zoomStep` / `panEnabled` / `zoomEnabled`, `animationDuration`, `input` (a `ViewInput`), slots `set_viewport(w, h)` / `zoom_by(delta, u, v, w, h)` / `zoom_at(factor, u, v, w, h)` / `pan_pixels(dx, dy)` / `animate_zoom(...)` / `animate_pan(dx, dy, ms)` / `stop_animation()` / `reset()` |
 | `ViewInput` | `keyboardEnabled`, `keyPanStep`, `keyPanRepeatInterval`, `panLeftShortcut` / `panRightShortcut` / `panUpShortcut` / `panDownShortcut` / `zoomInShortcut` / `zoomOutShortcut`, `matches(key, modifiers, shortcut)` |
 | `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 |
+| `CurveListModel` | the curves as a model (`curve`, `expression`, `color`, `lineWidth`, `visible`, `label`, `vertexShader`, `fragmentShader` roles) so QML puts one `ShaderEffect` behind each |
+| `Annotation` | `text`, `xy` (world), `xytext` (pixel offset), `arrow`, `color`, `fontSize`, `visible` |
+| `Guide` | `kind` (`"h"`/`"v"`), `value`, `color`, `width`, `style`, `visible` |
 
 Every setter is a Qt `Property` with a notify signal, so the same calls work from QML, from a
 Qt Designer slot or from a `QTimer`:
@@ -210,8 +212,10 @@ plt.show()                             # blocks in a script; use block=False in
 ```
 
 What maps: one figure/one axes (`subplots()` and `subplot(111)`), `plot(expression)`,
-`xlim`/`ylim`, `title`/`xlabel`/`ylabel`, `grid`, `aspect`, `savefig`/`to_image`, themes.
-`plt.gcf()`/`gca()`/`sca()`/`close()`/`show()` follow Matplotlib's current-figure shape.
+`xlim`/`ylim`, `title`/`xlabel`/`ylabel`, `grid(axis=...)`, `aspect`, `savefig`/`to_image`,
+themes, `legend`, `annotate`/`text`, `axhline`/`axvline`, `set_xticks`/`set_yticks` and
+`tick_params`. `plt.gcf()`/`gca()`/`sca()`/`close()`/`show()` follow Matplotlib's
+current-figure shape.
 
 What is deliberately different:
 
@@ -224,8 +228,9 @@ What is deliberately different:
   deferred renderer or blitting.
 - **`savefig` is a region at a pixel size**, not a page at a dpi. `width`/`height` are device
   pixels and `dpi` is a multiplier; `backend="matplotlib"` is the vector route.
-- **No legends, annotations, log axes or manual ticks yet.** `legend()`, `annotate()`,
-  `set_xscale()` and `set_xticks()` raise with the reason; chrome belongs to the host.
+- **Log axes and full annotation styling are not implemented.** `set_xscale()`/`set_yscale()`
+  raise with the reason; annotations support text + a straight arrow + pixel offset, not
+  Matplotlib's bbox/connectionstyle engine.
 - **Themes are per figure**, not `rcParams`; `plt` has no global style state beyond the current
   figure.
 - **`mpl_connect`/`blit` are absent.** Qt signals are the event system.
@@ -312,8 +317,9 @@ plot.plot.camera.zoom_by(120, 0.5, 0.5, w, h)     # one wheel notch, anchored at
 
 ## Keyboard, touch and animation
 
-Clicking the plot gives it focus; while it has focus the arrow keys pan (10% of the viewport
-per press by default), `+`/`=` zooms in and `-`/`_` zooms out. Held keys advance continuously:
+Clicking the plot or pressing Tab while it is in the focus chain gives it focus; while it has
+focus the arrow keys pan (10% of the viewport per press by default), `+`/`=` zooms in and
+`-`/`_` zooms out. Held keys advance continuously:
 one `keyPanStep` per `keyPanRepeatInterval` (100 ms by default), integrated every frame, so
 there is no OS key-repeat delay or granular stepping. Several arrows combine, so `Left+Up`
 moves diagonally at the normal speed. Every command is a property on the camera's `input`
@@ -359,7 +365,7 @@ plot.available_themes                 # the names, for a host's picker (both dem
 The 26 bundled sheets are Matplotlib's own styles, vendored verbatim into
 `qmlmathplot/themes/*.mplstyle` and converted at load time: Matplotlib's `rcParams` keys are
 mapped onto this library's property names, and keys describing things this library does not
-have (spines, figure size, dpi, legend, marker styles, …) are ignored. `themes.names()` lists
+have (figure size, dpi, legend, marker styles, …) are ignored. `themes.names()` lists
 them (`"default"` plus the 26 sheets). An unknown name raises `KeyError` and leaves the current
 theme alone.
 
@@ -371,13 +377,77 @@ theme alone.
   `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.
+  stays where it is. `plot.axes_position = "edge"` keeps the labels at the edges without
+  drawing axis lines.
+- `plot.axes_position = "box"` draws the four Matplotlib-style **spines** around the viewport
+  (same `axis_color` / `axis_width`), with ticks and labels on the bottom/left edges. It is a
+  property, not a separate theme, so it composes with any theme:
+  ```python
+  plot.axes_position = "box"
+  plot.grid = True
+  ```
+- Furniture is part of the same QML scene, so `to_image()` / `savefig()` capture the box,
+  grid, ticks, labels and title exactly as the live view renders them (there is an export
+  regression test for the four spines).
 - `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).
 
+## Annotations, legend and guides
+
+Annotation elements are **model-driven**, not host QML: the same objects render in the live view
+and in `to_image()` / `savefig()`.
+
+```python
+plot.annotate("pole", xy=(0.0, 0.0), xytext=(24, -18), arrowprops={"color": "#333333"})
+plot.text(2.0, 1.0, "f(2)=1", color="#333333", font_size=12)
+plot.add_hline(0.5, color="#888888", style="--")     # horizontal guide
+plot.add_vline(1.0, color="#888888", style=":")      # vertical guide
+
+plot.add_curve("sin(x)", label="sin")
+plot.add_curve("cos(x)", label="cos")
+plot.legend = True
+plot.legend_position = "upper right"                 # best | upper left | lower right | lower left
+
+plot.set_xticks([-3, 0, 3], ["-3", "0", "3"])        # explicit positions + labels
+plot.set_yticks([-1, 1])
+plot.grid_x = True
+plot.grid_y = False                                  # per-axis grid
+plot.tick_width = 1.5
+plot.tick_pad = 4.0
+plot.ticks_top = True
+plot.ticks_right = True
+plot.minor_ticks = True                              # four minor marks per major interval
+plot.spine_top = False                               # "box" mode only
+```
+
+`xy` is in world coordinates and `xytext` is a **logical-pixel offset** from it, so annotations
+stay attached to the data while the label keeps a stable screen offset. `Annotation` and `Guide`
+are also exposed as objects (`plot.annotations.at(i)`, `plot.guides.at(i)`) for per-item edits.
+
+The Matplotlib facade forwards the same surface:
+
+```python
+ax.annotate("pole", xy=(0, 0), xytext=(24, -18), arrowprops={"color": "#333"})
+ax.text(2, 1, "f(2)=1")
+ax.legend(loc="lower right")
+ax.set_xticks([-3, 0, 3], labels=["-3", "0", "3"])
+ax.tick_params(axis="x", length=6, width=1.5, top=True)
+ax.grid(True, axis="x")
+ax.axhline(0.5, color="#888888")
+ax.axvline(1.0, color="#888888")
+```
+
+`plt.annotate` / `plt.text` / `plt.legend` / `plt.xticks` / `plt.yticks` /
+`plt.tick_params` / `plt.axhline` / `plt.axvline` forward to the current axes. The
+`to_matplotlib()` hand-off maps labels, legend, annotations, guides and explicit ticks as well.
+
+The annotation/guide/legend layers are part of the QML scene. The export path now drains the
+queued Canvas paints before the synchronous readback, so the grid, annotations and guides are
+present in screenshots too (previously a Canvas-painted grid could miss the grab).
+
 ## Export
 
 `savefig()` writes a file, `to_image()` returns a `QImage`; both take the same keywords:
@@ -487,7 +557,7 @@ The supported path is GeoGebra's column idea implemented on the GPU: sample the
 sub-pixel x grid, stroke the polyline, and fill the exact interval enclosure where a column
 cannot be represented by a line.
 
-1. **Sub-pixel polyline stroke.** Each pixel evaluates `F` at **16 samples over ±2 columns**
+1. **Sub-pixel polyline stroke.** Each pixel evaluates `F` at **14 samples over ±2 columns**
    (0.25 logical-px spacing). Adjacent valid samples form a polyline, and coverage is
    `R - distance to the nearest segment` — Desmos' stroke rule. The sample spacing is
    sub-pixel, so the vertices themselves are sub-pixel and the segments are diagonal: the
@@ -522,7 +592,7 @@ cannot be represented by a line.
      viewport bottom; no filled ray.
    - **whole**: `DrawInterval.drawWhole` — one vertical segment at `x.low`.
    Deliberate deviations, because this is a fragment shader and not the Java tuple list: the
-   16-sample polyline supersamples GGB's one interval per column for resolved stretches; a
+   14-sample polyline supersamples GGB's one interval per column for resolved stretches; a
    dependent quotient's whole column is still suppressed (the fixed-x polyline draws the real
    branches, avoiding the `x/sqrt(x**2)` connector); and a joined inverted column uses those
    sample branches instead of replaying `JoinLines.inverted`'s neighbour decisions.
@@ -530,7 +600,7 @@ cannot be represented by a line.
    never evaluated; a pixel just outside the domain still gets the band, which is centred
    on the boundary.
 
-An ordinary pixel costs **16 `F` evaluations** plus two interval evaluations; there is no
+An ordinary pixel costs **14 `F` evaluations** plus two interval evaluations; there is no
 march, no tangent-foot projection and no column probe on the supported path. Expressions
 with an operation the interval backend does not implement (`floor`, `sign`, …) compile the
 legacy sampled band + ray + march path (`#define USE_INTERVAL 0`); it is the only user of
@@ -565,6 +635,8 @@ uv run ruff check src tests examples   # bug-level lint (undefined names, unused
   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_overlay.py`: annotations (`annotate`/`text`), horizontal/vertical guides, legend and
+  custom ticks, the `Axes`/`pyplot` forwarding, and the matplotlib hand-off mapping.
 - `test_qsb_cache.py`: the cache location/info/clear API and the age + LRU prune; unrelated
   files in the temp directory are not touched.
 - `test_shader_bake.py`: the stage of a baked `.qsb` must match its purpose, and
@@ -579,11 +651,11 @@ uv run ruff check src tests examples   # bug-level lint (undefined names, unused
   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
   scroll area being consumed by the plot (zoom instead of scrolling the parent)**, the
-  fixed aspect being undistorted by the widget's shape, and the plot staying out of the
-  Tab focus chain. `conftest.py` provides a session-scoped `QApplication` (QtWidgets
+  fixed aspect being undistorted by the widget's shape, and Tab reaching the plot and leaving
+  it again. `conftest.py` provides a session-scoped `QApplication` (QtWidgets
   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).
+  must not steal the pan), plus Tab focus entering and leaving the QML plot.
 - `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`,
@@ -677,14 +749,27 @@ Startup to the first frame is about **230 ms**, attributed as follows
 Per-frame grab cycles (900×600, `grabToImage` — frame + readback, so an upper bound on
 the GPU cost), steady state on the same window: `sin(1/x)` default **13.6 ms**, `tan(x)`
 default **12.4 ms**, `sin(1/x)` at zoom 90 (worst case) **12.5 ms**. The previous
-march/interval renderer measured 27/34/33 ms on the same machine: 16 samples are cheaper
+march/interval renderer measured 27/34/33 ms on the same machine: 14 samples are cheaper
 than the march's seed + tangent projection + walk + probe, and the march is now compiled
 only for the legacy path. The 1-D fragment source is about 21 KB.
 
-**Per-pixel `F` evaluations.** The supported path is fixed: 16 samples for the polyline
-(plus two interval evaluations for the column and the stroke footprint); there is no
-march budget and no band-window evaluation. The old fixed-grid/march table is superseded
-and no longer describes the shipped path.
+**Per-pixel `F` evaluations.** The supported path uses 14 samples for the polyline in the live
+view and in exports; two interval evaluations cover the column and the stroke footprint. There
+is no march budget and no band-window evaluation. Anti-aliasing comes from the analytic
+coverage ramp, not from the sample count; the samples only approximate the polyline. Sampling
+was tuned by the render tests: 8 samples overfills the `sin(1/x)` transition and breaks the
+`log` descent, 12 still overfills slightly, 14 passes.
+
+An interval early-out over ±2 columns rejects background pixels before the sample loop: if the
+pixel is farther than the stroke radius from the curve's y range in that window, it returns
+transparent without evaluating `F`. Measured by alternating two live 900×600 views (15 pans
+each, `grabToImage`, including readback): `sin(x)` 23.7 → 22.2 ms, `sin(1/x)` 23.6 → 21.0 ms,
+`x**2` 22.7 → 20.4 ms. Whole/infinite columns keep the full path, so `tan`/`1/x` near a pole
+are unchanged.
+
+The stroke-footprint interval is evaluated only when the column interval is empty (the domain
+boundary's outer half). On the common path this is two interval evaluations (`wide`, `own`)
+instead of three: another 17.0 → 16.4 ms on `sin(x)` in the same two-view measurement.
 
 ## Shader cache
 
@@ -739,6 +824,9 @@ measurement that settled each one). The Qt/packaging ones that shaped the code:
   **device** pixels with an integral device width (`_deviceWidth`/`_snapLine`), not logical
   half-pixels: the 1.07-logical axis is 2 device px at DPR 1.5 and otherwise alternated
   between one and two rows as it drifted with the zoom.
+- `qsb.exe` is a **console-subsystem** program. A windowed/frozen host (`pythonw`,
+  PyInstaller `--windowed`) would flash a cmd window on every cache-miss bake; `qsb.bake()`
+  passes `CREATE_NO_WINDOW` on Windows. `capture_output=True` alone does not prevent it.
 - `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.

{qmlmathplot-0.4.1 → qmlmathplot-0.4.2}/README.md

@@ -130,11 +130,13 @@ The model:
 
 | Object | Members |
 |---|---|
-| `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`, `xlabel`, `ylabel`, `title_color`, `title_font_size`, `title_bold`, `ticks_visible`, `theme` |
+| `Plot` | `camera`, `curves`, `annotations`, `guides`, `xlim`/`ylim`/`aspect` (forwarded), `add_curve()` / `add_implicit()` / `remove_curve()`, `annotate()` / `add_text()` / `add_hline()` / `add_vline()`, `set_xticks()` / `set_yticks()`, `available_themes`, and the style properties: `background`, `grid`, `grid_x`, `grid_y`, `grid_color`, `grid_width`, `grid_alpha`, `grid_style`, `axis_color`, `axis_width`, `axes_position`, `color_cycle`, `line_width`, `text_color`, `tick_color`, `tick_length`, `tick_width`, `tick_pad`, `ticks_top`, `ticks_right`, `minor_ticks`, `spine_top` / `spine_bottom` / `spine_left` / `spine_right`, `font_size`, `tick_font_size`, `title`, `xlabel`, `ylabel`, `title_color`, `title_font_size`, `title_bold`, `legend`, `legend_position`, `ticks_visible`, `theme` |
 | `Camera` | `centre`, `zoom` (world units per logical pixel), `aspect`, `xlim`/`ylim` (derived), `ticks_x`/`ticks_y`, `zoomStep` / `panEnabled` / `zoomEnabled`, `animationDuration`, `input` (a `ViewInput`), slots `set_viewport(w, h)` / `zoom_by(delta, u, v, w, h)` / `zoom_at(factor, u, v, w, h)` / `pan_pixels(dx, dy)` / `animate_zoom(...)` / `animate_pan(dx, dy, ms)` / `stop_animation()` / `reset()` |
 | `ViewInput` | `keyboardEnabled`, `keyPanStep`, `keyPanRepeatInterval`, `panLeftShortcut` / `panRightShortcut` / `panUpShortcut` / `panDownShortcut` / `zoomInShortcut` / `zoomOutShortcut`, `matches(key, modifiers, shortcut)` |
 | `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 |
+| `CurveListModel` | the curves as a model (`curve`, `expression`, `color`, `lineWidth`, `visible`, `label`, `vertexShader`, `fragmentShader` roles) so QML puts one `ShaderEffect` behind each |
+| `Annotation` | `text`, `xy` (world), `xytext` (pixel offset), `arrow`, `color`, `fontSize`, `visible` |
+| `Guide` | `kind` (`"h"`/`"v"`), `value`, `color`, `width`, `style`, `visible` |
 
 Every setter is a Qt `Property` with a notify signal, so the same calls work from QML, from a
 Qt Designer slot or from a `QTimer`:
@@ -197,8 +199,10 @@ plt.show()                             # blocks in a script; use block=False in
 ```
 
 What maps: one figure/one axes (`subplots()` and `subplot(111)`), `plot(expression)`,
-`xlim`/`ylim`, `title`/`xlabel`/`ylabel`, `grid`, `aspect`, `savefig`/`to_image`, themes.
-`plt.gcf()`/`gca()`/`sca()`/`close()`/`show()` follow Matplotlib's current-figure shape.
+`xlim`/`ylim`, `title`/`xlabel`/`ylabel`, `grid(axis=...)`, `aspect`, `savefig`/`to_image`,
+themes, `legend`, `annotate`/`text`, `axhline`/`axvline`, `set_xticks`/`set_yticks` and
+`tick_params`. `plt.gcf()`/`gca()`/`sca()`/`close()`/`show()` follow Matplotlib's
+current-figure shape.
 
 What is deliberately different:
 
@@ -211,8 +215,9 @@ What is deliberately different:
   deferred renderer or blitting.
 - **`savefig` is a region at a pixel size**, not a page at a dpi. `width`/`height` are device
   pixels and `dpi` is a multiplier; `backend="matplotlib"` is the vector route.
-- **No legends, annotations, log axes or manual ticks yet.** `legend()`, `annotate()`,
-  `set_xscale()` and `set_xticks()` raise with the reason; chrome belongs to the host.
+- **Log axes and full annotation styling are not implemented.** `set_xscale()`/`set_yscale()`
+  raise with the reason; annotations support text + a straight arrow + pixel offset, not
+  Matplotlib's bbox/connectionstyle engine.
 - **Themes are per figure**, not `rcParams`; `plt` has no global style state beyond the current
   figure.
 - **`mpl_connect`/`blit` are absent.** Qt signals are the event system.
@@ -299,8 +304,9 @@ plot.plot.camera.zoom_by(120, 0.5, 0.5, w, h)     # one wheel notch, anchored at
 
 ## Keyboard, touch and animation
 
-Clicking the plot gives it focus; while it has focus the arrow keys pan (10% of the viewport
-per press by default), `+`/`=` zooms in and `-`/`_` zooms out. Held keys advance continuously:
+Clicking the plot or pressing Tab while it is in the focus chain gives it focus; while it has
+focus the arrow keys pan (10% of the viewport per press by default), `+`/`=` zooms in and
+`-`/`_` zooms out. Held keys advance continuously:
 one `keyPanStep` per `keyPanRepeatInterval` (100 ms by default), integrated every frame, so
 there is no OS key-repeat delay or granular stepping. Several arrows combine, so `Left+Up`
 moves diagonally at the normal speed. Every command is a property on the camera's `input`
@@ -346,7 +352,7 @@ plot.available_themes                 # the names, for a host's picker (both dem
 The 26 bundled sheets are Matplotlib's own styles, vendored verbatim into
 `qmlmathplot/themes/*.mplstyle` and converted at load time: Matplotlib's `rcParams` keys are
 mapped onto this library's property names, and keys describing things this library does not
-have (spines, figure size, dpi, legend, marker styles, …) are ignored. `themes.names()` lists
+have (figure size, dpi, legend, marker styles, …) are ignored. `themes.names()` lists
 them (`"default"` plus the 26 sheets). An unknown name raises `KeyError` and leaves the current
 theme alone.
 
@@ -358,13 +364,77 @@ theme alone.
   `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.
+  stays where it is. `plot.axes_position = "edge"` keeps the labels at the edges without
+  drawing axis lines.
+- `plot.axes_position = "box"` draws the four Matplotlib-style **spines** around the viewport
+  (same `axis_color` / `axis_width`), with ticks and labels on the bottom/left edges. It is a
+  property, not a separate theme, so it composes with any theme:
+  ```python
+  plot.axes_position = "box"
+  plot.grid = True
+  ```
+- Furniture is part of the same QML scene, so `to_image()` / `savefig()` capture the box,
+  grid, ticks, labels and title exactly as the live view renders them (there is an export
+  regression test for the four spines).
 - `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).
 
+## Annotations, legend and guides
+
+Annotation elements are **model-driven**, not host QML: the same objects render in the live view
+and in `to_image()` / `savefig()`.
+
+```python
+plot.annotate("pole", xy=(0.0, 0.0), xytext=(24, -18), arrowprops={"color": "#333333"})
+plot.text(2.0, 1.0, "f(2)=1", color="#333333", font_size=12)
+plot.add_hline(0.5, color="#888888", style="--")     # horizontal guide
+plot.add_vline(1.0, color="#888888", style=":")      # vertical guide
+
+plot.add_curve("sin(x)", label="sin")
+plot.add_curve("cos(x)", label="cos")
+plot.legend = True
+plot.legend_position = "upper right"                 # best | upper left | lower right | lower left
+
+plot.set_xticks([-3, 0, 3], ["-3", "0", "3"])        # explicit positions + labels
+plot.set_yticks([-1, 1])
+plot.grid_x = True
+plot.grid_y = False                                  # per-axis grid
+plot.tick_width = 1.5
+plot.tick_pad = 4.0
+plot.ticks_top = True
+plot.ticks_right = True
+plot.minor_ticks = True                              # four minor marks per major interval
+plot.spine_top = False                               # "box" mode only
+```
+
+`xy` is in world coordinates and `xytext` is a **logical-pixel offset** from it, so annotations
+stay attached to the data while the label keeps a stable screen offset. `Annotation` and `Guide`
+are also exposed as objects (`plot.annotations.at(i)`, `plot.guides.at(i)`) for per-item edits.
+
+The Matplotlib facade forwards the same surface:
+
+```python
+ax.annotate("pole", xy=(0, 0), xytext=(24, -18), arrowprops={"color": "#333"})
+ax.text(2, 1, "f(2)=1")
+ax.legend(loc="lower right")
+ax.set_xticks([-3, 0, 3], labels=["-3", "0", "3"])
+ax.tick_params(axis="x", length=6, width=1.5, top=True)
+ax.grid(True, axis="x")
+ax.axhline(0.5, color="#888888")
+ax.axvline(1.0, color="#888888")
+```
+
+`plt.annotate` / `plt.text` / `plt.legend` / `plt.xticks` / `plt.yticks` /
+`plt.tick_params` / `plt.axhline` / `plt.axvline` forward to the current axes. The
+`to_matplotlib()` hand-off maps labels, legend, annotations, guides and explicit ticks as well.
+
+The annotation/guide/legend layers are part of the QML scene. The export path now drains the
+queued Canvas paints before the synchronous readback, so the grid, annotations and guides are
+present in screenshots too (previously a Canvas-painted grid could miss the grab).
+
 ## Export
 
 `savefig()` writes a file, `to_image()` returns a `QImage`; both take the same keywords:
@@ -474,7 +544,7 @@ The supported path is GeoGebra's column idea implemented on the GPU: sample the
 sub-pixel x grid, stroke the polyline, and fill the exact interval enclosure where a column
 cannot be represented by a line.
 
-1. **Sub-pixel polyline stroke.** Each pixel evaluates `F` at **16 samples over ±2 columns**
+1. **Sub-pixel polyline stroke.** Each pixel evaluates `F` at **14 samples over ±2 columns**
    (0.25 logical-px spacing). Adjacent valid samples form a polyline, and coverage is
    `R - distance to the nearest segment` — Desmos' stroke rule. The sample spacing is
    sub-pixel, so the vertices themselves are sub-pixel and the segments are diagonal: the
@@ -509,7 +579,7 @@ cannot be represented by a line.
      viewport bottom; no filled ray.
    - **whole**: `DrawInterval.drawWhole` — one vertical segment at `x.low`.
    Deliberate deviations, because this is a fragment shader and not the Java tuple list: the
-   16-sample polyline supersamples GGB's one interval per column for resolved stretches; a
+   14-sample polyline supersamples GGB's one interval per column for resolved stretches; a
    dependent quotient's whole column is still suppressed (the fixed-x polyline draws the real
    branches, avoiding the `x/sqrt(x**2)` connector); and a joined inverted column uses those
    sample branches instead of replaying `JoinLines.inverted`'s neighbour decisions.
@@ -517,7 +587,7 @@ cannot be represented by a line.
    never evaluated; a pixel just outside the domain still gets the band, which is centred
    on the boundary.
 
-An ordinary pixel costs **16 `F` evaluations** plus two interval evaluations; there is no
+An ordinary pixel costs **14 `F` evaluations** plus two interval evaluations; there is no
 march, no tangent-foot projection and no column probe on the supported path. Expressions
 with an operation the interval backend does not implement (`floor`, `sign`, …) compile the
 legacy sampled band + ray + march path (`#define USE_INTERVAL 0`); it is the only user of
@@ -552,6 +622,8 @@ uv run ruff check src tests examples   # bug-level lint (undefined names, unused
   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_overlay.py`: annotations (`annotate`/`text`), horizontal/vertical guides, legend and
+  custom ticks, the `Axes`/`pyplot` forwarding, and the matplotlib hand-off mapping.
 - `test_qsb_cache.py`: the cache location/info/clear API and the age + LRU prune; unrelated
   files in the temp directory are not touched.
 - `test_shader_bake.py`: the stage of a baked `.qsb` must match its purpose, and
@@ -566,11 +638,11 @@ uv run ruff check src tests examples   # bug-level lint (undefined names, unused
   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
   scroll area being consumed by the plot (zoom instead of scrolling the parent)**, the
-  fixed aspect being undistorted by the widget's shape, and the plot staying out of the
-  Tab focus chain. `conftest.py` provides a session-scoped `QApplication` (QtWidgets
+  fixed aspect being undistorted by the widget's shape, and Tab reaching the plot and leaving
+  it again. `conftest.py` provides a session-scoped `QApplication` (QtWidgets
   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).
+  must not steal the pan), plus Tab focus entering and leaving the QML plot.
 - `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`,
@@ -664,14 +736,27 @@ Startup to the first frame is about **230 ms**, attributed as follows
 Per-frame grab cycles (900×600, `grabToImage` — frame + readback, so an upper bound on
 the GPU cost), steady state on the same window: `sin(1/x)` default **13.6 ms**, `tan(x)`
 default **12.4 ms**, `sin(1/x)` at zoom 90 (worst case) **12.5 ms**. The previous
-march/interval renderer measured 27/34/33 ms on the same machine: 16 samples are cheaper
+march/interval renderer measured 27/34/33 ms on the same machine: 14 samples are cheaper
 than the march's seed + tangent projection + walk + probe, and the march is now compiled
 only for the legacy path. The 1-D fragment source is about 21 KB.
 
-**Per-pixel `F` evaluations.** The supported path is fixed: 16 samples for the polyline
-(plus two interval evaluations for the column and the stroke footprint); there is no
-march budget and no band-window evaluation. The old fixed-grid/march table is superseded
-and no longer describes the shipped path.
+**Per-pixel `F` evaluations.** The supported path uses 14 samples for the polyline in the live
+view and in exports; two interval evaluations cover the column and the stroke footprint. There
+is no march budget and no band-window evaluation. Anti-aliasing comes from the analytic
+coverage ramp, not from the sample count; the samples only approximate the polyline. Sampling
+was tuned by the render tests: 8 samples overfills the `sin(1/x)` transition and breaks the
+`log` descent, 12 still overfills slightly, 14 passes.
+
+An interval early-out over ±2 columns rejects background pixels before the sample loop: if the
+pixel is farther than the stroke radius from the curve's y range in that window, it returns
+transparent without evaluating `F`. Measured by alternating two live 900×600 views (15 pans
+each, `grabToImage`, including readback): `sin(x)` 23.7 → 22.2 ms, `sin(1/x)` 23.6 → 21.0 ms,
+`x**2` 22.7 → 20.4 ms. Whole/infinite columns keep the full path, so `tan`/`1/x` near a pole
+are unchanged.
+
+The stroke-footprint interval is evaluated only when the column interval is empty (the domain
+boundary's outer half). On the common path this is two interval evaluations (`wide`, `own`)
+instead of three: another 17.0 → 16.4 ms on `sin(x)` in the same two-view measurement.
 
 ## Shader cache
 
@@ -726,6 +811,9 @@ measurement that settled each one). The Qt/packaging ones that shaped the code:
   **device** pixels with an integral device width (`_deviceWidth`/`_snapLine`), not logical
   half-pixels: the 1.07-logical axis is 2 device px at DPR 1.5 and otherwise alternated
   between one and two rows as it drifted with the zoom.
+- `qsb.exe` is a **console-subsystem** program. A windowed/frozen host (`pythonw`,
+  PyInstaller `--windowed`) would flash a cmd window on every cache-miss bake; `qsb.bake()`
+  passes `CREATE_NO_WINDOW` on Windows. `capture_output=True` alone does not prevent it.
 - `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.

{qmlmathplot-0.4.1 → qmlmathplot-0.4.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "qmlmathplot"
-version = "0.4.1"
+version = "0.4.2"
 description = "Embeddable function plotter for Qt Quick / QtWidgets (implicit per-pixel drawing, MVVM)"
 readme = "README.md"
 requires-python = ">=3.11"

{qmlmathplot-0.4.1 → qmlmathplot-0.4.2}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "qmlmathplot"
-version = "0.4.1"
+version = "0.4.2"
 description = "Embeddable function plotter for Qt Quick / QtWidgets (implicit per-pixel drawing, MVVM)"
 readme = "README.md"
 authors = [

{qmlmathplot-0.4.1 → qmlmathplot-0.4.2}/src/qmlmathplot/__init__.py

@@ -54,6 +54,7 @@ from .camera import HOME_SIZE, HOME_VIEW, Camera, nice_ticks
 from .curve import Curve, CurveListModel, ImplicitCurve
 from .figure import Axes, Figure
 from .input import ViewInput
+from .overlay import Annotation, Guide
 from .plot import Plot
 from .qsb import cache_dir, cache_info, clear_cache, prune_cache
 from .view import QML_MAJOR, QML_MINOR, QML_URI, qml_component_path, register_qml_types
@@ -63,6 +64,7 @@ if TYPE_CHECKING:  # only for type checkers; at runtime the module-level __getat
     from .widget import MathPlotWidget
 
 __all__ = [
+    "Annotation",
     "Axes",
     "cache_dir",
     "cache_info",
@@ -72,6 +74,7 @@ __all__ = [
     "CurveListModel",
     "Figure",
     "FigureCanvasQt",
+    "Guide",
     "HOME_SIZE",
     "HOME_VIEW",
     "ImplicitCurve",

{qmlmathplot-0.4.1 → qmlmathplot-0.4.2}/src/qmlmathplot/curve.py

@@ -431,6 +431,7 @@ class CurveListModel(QAbstractListModel):
     VisibleRole = CurveRole + 4
     VertexShaderRole = CurveRole + 5
     FragmentShaderRole = CurveRole + 6
+    LabelRole = CurveRole + 7
 
     _ROLES = {
         CurveRole: b"curve",
@@ -440,6 +441,7 @@ class CurveListModel(QAbstractListModel):
         VisibleRole: b"visible",
         VertexShaderRole: b"vertexShader",
         FragmentShaderRole: b"fragmentShader",
+        LabelRole: b"label",
     }
 
     def __init__(
@@ -478,6 +480,8 @@ class CurveListModel(QAbstractListModel):
             return curve.vertexShader
         if role == self.FragmentShaderRole:
             return curve.fragmentShader
+        if role == self.LabelRole:
+            return curve.label
         return None
 
     def _notify(self, curve: Curve, roles: tuple[int, ...]) -> None:
@@ -498,6 +502,7 @@ class CurveListModel(QAbstractListModel):
             lambda c=curve: self._notify(c, (self.ColorRole, self.LineWidthRole))
         )
         curve.visibleChanged.connect(lambda c=curve: self._notify(c, (self.VisibleRole,)))
+        curve.labelChanged.connect(lambda c=curve: self._notify(c, (self.LabelRole,)))
 
     # ---------------------------------------------------------------- public
     def _defaults(self, color: object, line_width: object) -> tuple[QColor, float]:

{qmlmathplot-0.4.1 → qmlmathplot-0.4.2}/src/qmlmathplot/export.py

@@ -14,7 +14,7 @@ from __future__ import annotations
 from collections.abc import Sequence
 from typing import TYPE_CHECKING
 
-from PySide6.QtCore import QSize, Qt, QUrl
+from PySide6.QtCore import QCoreApplication, QSize, Qt, QUrl
 from PySide6.QtGui import QColor, QImage
 
 if TYPE_CHECKING:  # pragma: no cover - typing only; the real imports stay lazy
@@ -155,6 +155,10 @@ def render(
 
         camera.set_viewport(logical[0], logical[1])
         camera.set_view(centre[0], centre[1], scale[0], scale[1])
+        # Let QML's Canvas-based furniture (grid, guides) handle its queued paint before the
+        # synchronous readback; the scene-graph items are already ready, Canvas is not.
+        for _ in range(3):
+            QCoreApplication.processEvents()
         image = widget.grabFramebuffer()
     finally:
         # Restore before the event loop runs again, so no live view repaints the export state.