qmlmathplot 0.1.0__py3-none-any.whl

qmlmathplot/__init__.py

@@ -0,0 +1,84 @@
+"""QMLMathPlot — an embeddable function plotter for Qt (Qt Quick and QtWidgets).
+
+The plot is an **infinite canvas with a camera**: the camera holds where you are looking
+(centre, zoom, aspect) and the visible range follows from it, so resizing a widget shows more
+or less canvas instead of distorting or re-zooming the curve. Curves are expressions evaluated
+per pixel in a fragment shader, so the cost does not depend on the function's frequency.
+
+QtWidgets layout in one line:
+
+    from PySide6.QtWidgets import QApplication, QVBoxLayout, QWidget
+    from qmlmathplot import MathPlotWidget
+
+    app = QApplication([])
+    window = QWidget()
+    box = QVBoxLayout(window)
+    plot = MathPlotWidget("sin(1/x)")
+    box.addWidget(plot)
+    window.show()
+    app.exec()
+
+Qt Quick (QML) — the component plus the model:
+
+    import QmlMathPlot 1.0
+    PlotView { plot: myPlot; anchors.fill: parent }
+
+    from PySide6.QtGui import QGuiApplication
+    from PySide6.QtQuick import QQuickView
+    from PySide6.QtCore import QUrl
+    from qmlmathplot import Plot, qml_component_path, register_qml_types
+
+    app = QGuiApplication([])
+    register_qml_types()
+    view = QQuickView()
+    view.setSource(QUrl.fromLocalFile(qml_component_path()))
+    view.rootObject().setProperty("plot", Plot())
+    view.show()
+    app.exec()
+
+Model, without Qt widgets:
+
+    plot = Plot()
+    plot.xlim, plot.ylim = (-6.0, 6.0), (-2.0, 2.0)
+    curve = plot.add_curve("sin(1/x)", label="sin(1/x)")
+    curve.expression = "sin(2/x)"          # one signal -> re-bake -> the view swaps it
+    plot.theme = "ggplot"                  # Matplotlib's style sheets, see qmlmathplot.themes
+
+Demos: ``examples/minimal.py``, ``examples/explorer_qtwidgets.py``,
+``examples/explorer_qtquick.py``. Design notes: ``docs/api-design.md``.
+"""
+
+from typing import TYPE_CHECKING
+
+from .camera import HOME_SIZE, HOME_VIEW, Camera, nice_ticks
+from .curve import Curve, CurveListModel
+from .plot import Plot
+from .view import QML_MAJOR, QML_MINOR, QML_URI, qml_component_path, register_qml_types
+
+if TYPE_CHECKING:  # only for type checkers; at runtime the module-level __getattr__ is used
+    from .widget import MathPlotWidget
+
+__all__ = [
+    "Camera",
+    "Curve",
+    "CurveListModel",
+    "HOME_SIZE",
+    "HOME_VIEW",
+    "MathPlotWidget",
+    "nice_ticks",
+    "Plot",
+    "qml_component_path",
+    "QML_MAJOR",
+    "QML_MINOR",
+    "QML_URI",
+    "register_qml_types",
+]
+
+
+def __getattr__(name: str) -> object:
+    """``MathPlotWidget`` is imported lazily, so pure-QML use never loads QtWidgets."""
+    if name == "MathPlotWidget":
+        from .widget import MathPlotWidget
+
+        return MathPlotWidget
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

qmlmathplot/app.py

@@ -0,0 +1,79 @@
+"""MVP entry point: wraps the component into a minimal verifiable window (called by `main.py` /
+`uv run qmlmathplot`).
+
+    python main.py --backend d3d11 "sin(1/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
+during platform initialization, so calling ``QQuickWindow.setGraphicsApi()`` later has no effect
+(the window's surface has already been created for the default backend).
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+from PySide6.QtCore import QUrl
+from PySide6.QtGui import QGuiApplication
+from PySide6.QtQuick import QQuickView
+
+from .plot import Plot
+from .view import qml_component_path, register_qml_types
+
+# Valid QSG_RHI_BACKEND values (Qt 6); unset = Qt default (d3d11 on Windows)
+BACKENDS = ("d3d11", "d3d12", "vulkan", "metal", "opengl", "null")
+
+DEFAULT_EXPRESSION = "sin(x)"
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="qmlmathplot",
+        description="Minimal verifiable window for QMLMathPlot (drag to pan, wheel to zoom).",
+    )
+    parser.add_argument("expression", nargs="?", default=DEFAULT_EXPRESSION,
+                        help=f"expression in sympy syntax (default {DEFAULT_EXPRESSION})")
+    parser.add_argument("--backend", choices=BACKENDS, default=None,
+                        help="RHI backend for Qt Quick; Qt's default when not specified")
+    parser.add_argument("--width", type=int, default=900, help="window width (default 900)")
+    parser.add_argument("--height", type=int, default=600, help="window height (default 600)")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(sys.argv[1:] if argv is None else argv)
+
+    if args.backend is not None:
+        # An explicitly given backend wins over the environment: the command line overrides all
+        os.environ["QSG_RHI_BACKEND"] = args.backend
+
+    app = QGuiApplication(sys.argv[:1])
+    register_qml_types()
+
+    view = QQuickView()
+    view.setResizeMode(QQuickView.ResizeMode.SizeRootObjectToView)
+    view.setTitle(f"QMLMathPlot — {args.expression}")
+    view.resize(args.width, args.height)
+    view.setSource(QUrl.fromLocalFile(qml_component_path()))
+    if view.status() is not QQuickView.Status.Ready:
+        for err in view.errors():
+            print(err.toString(), file=sys.stderr)
+        return 1
+
+    root = view.rootObject()
+    if root is None:
+        print("failed to create the QML root object", file=sys.stderr)
+        return 1
+
+    # MVVM: the app side owns the model and injects it into the component (which also
+    # brings its own when nothing is injected)
+    plot = Plot()
+    plot.add_curve(args.expression)
+    root.setProperty("plot", plot)
+
+    view.show()
+    print(f"RHI backend: {view.graphicsApi()}  (QSG_RHI_BACKEND={os.environ.get('QSG_RHI_BACKEND', 'not set')})",
+          flush=True)
+    return app.exec()

qmlmathplot/camera.py

@@ -0,0 +1,366 @@
+"""Camera layer: where we look at the infinite canvas, plus the nice-number tick algorithm.
+
+The camera stores three numbers that do not depend on the widget at all — ``centre``,
+``zoom`` (world units per *logical* pixel on x) and ``aspect`` (the ratio of the y scale to
+the x scale; ``"auto"`` leaves it to the widget's shape). The visible range (``xlim`` /
+``ylim``) is *derived* from them and the last reported size, so resizing changes what is
+visible without touching the state — which is what makes an infinite canvas cheap.
+"""
+
+from __future__ import annotations
+
+import math
+
+from PySide6.QtCore import Property, QObject, Signal, Slot
+from PySide6.QtGui import QVector2D
+
+__all__ = ["HOME_SIZE", "HOME_VIEW", "Camera", "nice_ticks"]
+
+#: Home view — the classic 12x4 window — as (xmin, xmax, ymin, ymax).
+#:
+#: The home is a *view*, but the camera stores scales, so the two meet at a reference size:
+#: the first reported size turns the home view into (zoom, y scale) for that widget, and
+#: the constants below are only the fallback used before any size is known.
+HOME_VIEW = (-6.0, 6.0, -2.0, 2.0)
+#: Reference size for the home view (before the first ``setViewport``).
+HOME_SIZE = (900.0, 600.0)
+
+
+def _pair(value: object) -> tuple[float, float]:
+    """Two floats from a QVector2D, a QPointF or any 2-sequence."""
+    if isinstance(value, (QVector2D,)):
+        return (value.x(), value.y())
+    x, y = value  # type: ignore[misc]  # documented: any pair-like value
+    return (float(x), float(y))
+
+
+def nice_ticks(lo: float, hi: float, target: int = 8) -> list[tuple[float, str]]:
+    """Ticks covering ``[lo, hi]`` at nice-number steps (1/2/5 x 10^n), about ``target`` of
+    them, as ``(value, label)``.
+
+    Pure and Qt-free: the tick values are decided once per camera change (not per frame) and
+    QML only positions the labels it is given.
+    """
+    if not hi > lo or target < 1:
+        return []
+    raw = (hi - lo) / target
+    magnitude = 10.0 ** math.floor(math.log10(raw))
+    for multiple in (1.0, 2.0, 5.0, 10.0):
+        if raw <= multiple * magnitude:
+            step = multiple * magnitude
+            break
+    else:  # pragma: no cover - the 10.0 branch always matches
+        step = 10.0 * magnitude
+
+    decimals = max(0, -math.floor(math.log10(step) + 1e-9))
+    first = math.ceil(lo / step - 1e-9) * step
+    out: list[tuple[float, str]] = []
+    for i in range(int(math.floor((hi - first) / step + 1e-9)) + 1):
+        # Round to the step's own precision: repeated addition accumulates noise (0.6000000000000001)
+        # and the label would then disagree with the position.
+        value = round(first + i * step, decimals)
+        if abs(value) < step * 1e-6:
+            value = 0.0                       # no "-0" labels
+        out.append((value, _tick_label(value, step, decimals)))
+    return out
+
+
+def _tick_label(value: float, step: float, decimals: int) -> str:
+    if abs(value) >= 1e7 or (value != 0.0 and abs(step) < 1e-7):
+        return f"{value:g}"
+    return f"{value:.{decimals}f}"
+
+
+def _qml_pairs(ticks: list[tuple[float, str]]) -> list[list[float | str]]:
+    """Ticks as two-element *lists* for QML: a Python tuple crosses a QVariant as an opaque
+    value (QML cannot index it), so the pairs have to be lists to be readable there."""
+    return [[value, label] for value, label in ticks]
+
+
+class Camera(QObject):
+    """The view onto the infinite canvas: centre, zoom (units per logical pixel) and aspect.
+
+    ``aspect`` is the ratio of the y scale to the x scale, so ``1.0`` means square units (a
+    world circle is drawn round) and ``"auto"`` keeps the two scales independent, letting the
+    widget's shape decide how much canvas is visible.
+    """
+
+    viewChanged = Signal()
+    aspectChanged = Signal()
+    ticksChanged = Signal()
+    zoomStepChanged = Signal()
+    panEnabledChanged = Signal()
+    zoomEnabledChanged = Signal()
+
+    #: Scale limits (world units per pixel), to keep panning/zooming reversible.
+    MIN_SCALE = 1e-12
+    MAX_SCALE = 1e12
+
+    def __init__(self, parent: QObject | None = None) -> None:
+        super().__init__(parent)
+        self._centre = QVector2D(0.0, 0.0)
+        self._zoom = (HOME_VIEW[1] - HOME_VIEW[0]) / HOME_SIZE[0]
+        self._aspect: str | float = "auto"
+        self._y_scale = (HOME_VIEW[3] - HOME_VIEW[2]) / HOME_SIZE[1]
+        self._size: tuple[float, float] | None = None
+        # True while the home *view* has not been resolved for a real size: the first report
+        # then sets the scales from it, so a window opened at any size shows the home window.
+        self._home = True
+        self._zoom_step = 0.9
+        self._pan_enabled = True
+        self._zoom_enabled = True
+
+    # ------------------------------------------------------------- state
+    def _get_centre(self) -> QVector2D:
+        return QVector2D(self._centre)
+
+    def _set_centre(self, value: object) -> None:
+        x, y = _pair(value)
+        if (x, y) == (self._centre.x(), self._centre.y()):
+            return
+        self._centre = QVector2D(x, y)
+        self._home = False
+        self._view_changed()
+
+    # "QVariant" rather than QVector2D so a plain ``(x, y)`` from Python is accepted too.
+    centre: QVector2D = Property("QVariant", _get_centre, _set_centre, notify=viewChanged)
+
+    def _get_zoom(self) -> float:
+        return self._zoom
+
+    def _set_zoom(self, value: float) -> None:
+        self._scale_to(float(value))
+
+    zoom: float = Property(float, _get_zoom, _set_zoom, notify=viewChanged)
+
+    def _get_aspect(self) -> str | float:
+        return self._aspect
+
+    def _set_aspect(self, value: str | float) -> None:
+        if isinstance(value, str):
+            if value != "auto":
+                raise ValueError(f'aspect must be "auto" or a positive number, got {value!r}')
+        elif not float(value) > 0:
+            raise ValueError(f"aspect must be positive, got {value!r}")
+        if value == self._aspect:
+            return
+        old_y = self.scale_y
+        self._aspect = value
+        self._home = False
+        if isinstance(value, str):
+            self._y_scale = old_y            # switching to "auto" keeps the current shape
+        else:
+            # Expand, never crop: a numeric aspect may only show *more* than was visible.
+            self._scale_to(max(self._zoom, float(value) * old_y), keep_ratio=False)
+        self.aspectChanged.emit()
+        self._view_changed()
+
+    aspect: str | float = Property("QVariant", _get_aspect, _set_aspect, notify=aspectChanged)
+
+    def _get_scale_x(self) -> float:
+        return self._zoom
+
+    def _get_scale_y(self) -> float:
+        if isinstance(self._aspect, str):
+            return self._y_scale
+        return self._zoom / float(self._aspect)
+
+    scale_x: float = Property(float, _get_scale_x, notify=viewChanged)
+    scale_y: float = Property(float, _get_scale_y, notify=viewChanged)
+
+    def _scale_to(self, value: float, *, keep_ratio: bool = True) -> None:
+        """Set the x scale; in "auto" mode both scales move together (a uniform zoom)."""
+        value = min(max(value, self.MIN_SCALE), self.MAX_SCALE)
+        if value == self._zoom:
+            return
+        factor = value / self._zoom
+        self._zoom = value
+        if keep_ratio and isinstance(self._aspect, str):
+            self._y_scale = min(max(self._y_scale * factor, self.MIN_SCALE), self.MAX_SCALE)
+        self._home = False
+        self._view_changed()
+
+    # ------------------------------------------------------- derived ranges
+    def _effective_size(self) -> tuple[float, float]:
+        """Size used for the derived ranges: the last reported one, or the reference."""
+        return self._size if self._size is not None else HOME_SIZE
+
+    def _get_xlim(self) -> QVector2D:
+        width, _ = self._effective_size()
+        half = 0.5 * width * self.scale_x
+        return QVector2D(self._centre.x() - half, self._centre.x() + half)
+
+    def _set_xlim(self, value: object) -> None:
+        lo, hi = _pair(value)
+        width, _ = self._effective_size()
+        if not hi > lo or width <= 0:
+            return
+        self._centre = QVector2D(0.5 * (lo + hi), self._centre.y())
+        self._scale_to((hi - lo) / width)    # keeps the ratio: y follows the same factor
+
+    def _get_ylim(self) -> QVector2D:
+        _, height = self._effective_size()
+        half = 0.5 * height * self.scale_y
+        return QVector2D(self._centre.y() - half, self._centre.y() + half)
+
+    def _set_ylim(self, value: object) -> None:
+        lo, hi = _pair(value)
+        _, height = self._effective_size()
+        if not hi > lo or height <= 0:
+            return
+        self._centre = QVector2D(self._centre.x(), 0.5 * (lo + hi))
+        if isinstance(self._aspect, str):
+            self._y_scale = min(max((hi - lo) / height, self.MIN_SCALE), self.MAX_SCALE)
+            self._home = False
+            self._view_changed()
+        else:
+            self._scale_to((hi - lo) / height * float(self._aspect), keep_ratio=False)
+
+    xlim: QVector2D = Property("QVariant", _get_xlim, _set_xlim, notify=viewChanged)
+    ylim: QVector2D = Property("QVariant", _get_ylim, _set_ylim, notify=viewChanged)
+
+    # --------------------------------------------------------------- ticks
+    def tick_values(self) -> tuple[list[tuple[float, str]], list[tuple[float, str]]]:
+        """Ticks for both axes of the visible range, as ``(value, label)`` pairs."""
+        xlim, ylim = self._get_xlim(), self._get_ylim()
+        return nice_ticks(xlim.x(), xlim.y()), nice_ticks(ylim.x(), ylim.y())
+
+    def _get_ticks_x(self) -> list[list[float | str]]:
+        return _qml_pairs(self.tick_values()[0])
+
+    def _get_ticks_y(self) -> list[list[float | str]]:
+        return _qml_pairs(self.tick_values()[1])
+
+    ticks_x: list[tuple[float, str]] = Property("QVariant", _get_ticks_x, notify=ticksChanged)
+    ticks_y: list[tuple[float, str]] = Property("QVariant", _get_ticks_y, notify=ticksChanged)
+
+    # ----------------------------------------------------------- behaviour
+    def _get_zoom_step(self) -> float:
+        return self._zoom_step
+
+    def _set_zoom_step(self, value: float) -> None:
+        value = float(value)
+        if not 0.0 < value < 1.0:
+            raise ValueError(f"zoomStep must be in (0, 1), got {value!r}")
+        if value == self._zoom_step:
+            return
+        self._zoom_step = value
+        self.zoomStepChanged.emit()
+
+    #: Scale factor of one wheel notch (0.9 = 10% closer per notch).
+    zoomStep: float = Property(float, _get_zoom_step, _set_zoom_step, notify=zoomStepChanged)
+
+    def _get_pan_enabled(self) -> bool:
+        return self._pan_enabled
+
+    def _set_pan_enabled(self, value: bool) -> None:
+        value = bool(value)
+        if value == self._pan_enabled:
+            return
+        self._pan_enabled = value
+        self.panEnabledChanged.emit()
+
+    panEnabled: bool = Property(bool, _get_pan_enabled, _set_pan_enabled, notify=panEnabledChanged)
+
+    def _get_zoom_enabled(self) -> bool:
+        return self._zoom_enabled
+
+    def _set_zoom_enabled(self, value: bool) -> None:
+        value = bool(value)
+        if value == self._zoom_enabled:
+            return
+        self._zoom_enabled = value
+        self.zoomEnabledChanged.emit()
+
+    zoomEnabled: bool = Property(
+        bool, _get_zoom_enabled, _set_zoom_enabled, notify=zoomEnabledChanged
+    )
+
+    def _view_changed(self) -> None:
+        self.viewChanged.emit()
+        self.ticksChanged.emit()
+
+    # --------------------------------------------------------------- slots
+    @Slot(float, float)
+    def setViewport(self, width: float, height: float) -> None:
+        """Record the widget size (logical pixels) — used by the derived ranges only.
+
+        Drawing never depends on it: the shader derives its mapping from the camera and its
+        own size. The first report resolves the home view (see ``HOME_VIEW``); later reports
+        keep the scales, so nothing zooms while a window or a splitter is dragged.
+        """
+        if width <= 0 or height <= 0:
+            return
+        size = (float(width), float(height))
+        if size == self._size:
+            return
+        self._size = size
+        self._resolve_home()
+        self._view_changed()
+
+    def _resolve_home(self) -> None:
+        """Turn the home view into scales for the known size (once, while still at home)."""
+        if not self._home:
+            return
+        width, height = self._effective_size()
+        x_scale = (HOME_VIEW[1] - HOME_VIEW[0]) / width
+        y_scale = (HOME_VIEW[3] - HOME_VIEW[2]) / height
+        if isinstance(self._aspect, str):
+            self._zoom, self._y_scale = x_scale, y_scale
+        else:
+            aspect = float(self._aspect)
+            self._zoom = max(x_scale, aspect * y_scale)   # expand, never crop
+            self._y_scale = self._zoom / aspect
+        if self._size is not None:
+            self._home = False
+
+    @Slot(float, float, float, float, float)
+    def zoom_by(self, delta: float, u: float, v: float, width: float, height: float) -> None:
+        """Zoom by ``delta`` wheel units (120 = one notch), anchored at the normalised
+        cursor position ``(u, v)`` of a ``width`` x ``height`` viewport.
+
+        The factor depends only on ``delta``, so scrolling up and down at the same position
+        are exact inverses; the world point under the cursor stays put.
+        """
+        if not self._zoom_enabled or delta == 0:
+            return
+        target = min(max(self._zoom * self._zoom_step ** (delta / 120.0), self.MIN_SCALE),
+                     self.MAX_SCALE)
+        factor = target / self._zoom
+        if factor == 1.0:
+            return
+        if width > 0 and height > 0:
+            anchor_x = self._centre.x() + (u - 0.5) * width * self.scale_x
+            anchor_y = self._centre.y() + (0.5 - v) * height * self.scale_y
+        else:
+            anchor_x, anchor_y = self._centre.x(), self._centre.y()
+        self._zoom = target
+        if isinstance(self._aspect, str):
+            self._y_scale = min(max(self._y_scale * factor, self.MIN_SCALE), self.MAX_SCALE)
+        if width > 0 and height > 0:
+            self._centre = QVector2D(
+                anchor_x - (u - 0.5) * width * self.scale_x,
+                anchor_y - (0.5 - v) * height * self.scale_y,
+            )
+        self._home = False
+        self._view_changed()
+
+    @Slot(float, float)
+    def pan_pixels(self, dx: float, dy: float) -> None:
+        """Pan by a pixel displacement (screen y points down, world y points up)."""
+        if not self._pan_enabled or (dx == 0.0 and dy == 0.0):
+            return
+        self._centre = QVector2D(
+            self._centre.x() - dx * self.scale_x,
+            self._centre.y() + dy * self.scale_y,
+        )
+        self._home = False
+        self._view_changed()
+
+    @Slot()
+    def reset(self) -> None:
+        """Back to the home view (centre and scales as the camera was configured)."""
+        self._centre = QVector2D(0.0, 0.0)
+        self._home = True
+        self._resolve_home()
+        self._view_changed()