qmlmathplot 0.2.0__tar.gz → 0.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: qmlmathplot
-Version: 0.2.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>
@@ -44,6 +44,18 @@ An un-themed plot looks like matplotlib (white background, tab10 colours, grey g
 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:
@@ -122,9 +134,9 @@ The model:
 
 | Object | Members |
 |---|---|
-| `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` |
+| `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
@@ -144,6 +156,35 @@ bounded page), no `FigureCanvas`/`draw()` (the scene is live), no toolbar and no
 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)
 
 `Camera` stores three numbers that do not depend on the widget: `centre` (world coordinates in
@@ -279,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) |
@@ -327,7 +376,12 @@ 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 defaults are
   matplotlib's default style, the limits are forwarded to the camera, and a theme applies
@@ -391,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

{qmlmathplot-0.2.0 → qmlmathplot-0.3.0}/README.md

@@ -31,6 +31,18 @@ An un-themed plot looks like matplotlib (white background, tab10 colours, grey g
 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:
@@ -109,9 +121,9 @@ The model:
 
 | Object | Members |
 |---|---|
-| `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` |
+| `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
@@ -131,6 +143,35 @@ bounded page), no `FigureCanvas`/`draw()` (the scene is live), no toolbar and no
 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)
 
 `Camera` stores three numbers that do not depend on the widget: `centre` (world coordinates in
@@ -266,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) |
@@ -314,7 +363,12 @@ 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 defaults are
   matplotlib's default style, the limits are forwarded to the camera, and a theme applies
@@ -378,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

{qmlmathplot-0.2.0 → qmlmathplot-0.3.0}/pyproject.toml

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

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

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

{qmlmathplot-0.2.0 → qmlmathplot-0.3.0}/src/qmlmathplot/__init__.py

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

qmlmathplot-0.3.0/src/qmlmathplot/__main__.py

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

{qmlmathplot-0.2.0 → qmlmathplot-0.3.0}/src/qmlmathplot/app.py

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