quantized-lab 0.8.0__tar.gz → 0.9.0__tar.gz

quantized_lab-0.9.0/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: quantized-lab
+Version: 0.9.0
+Summary: Plot, analyze, and publish lab data - magnetometry, XRD, reflectometry - with OriginPro file interop, golden-verified analysis, and reproducible pipelines.
+Project-URL: Homepage, https://github.com/pquarterman17/quantized
+Project-URL: Documentation, https://github.com/pquarterman17/quantized/wiki
+Project-URL: Repository, https://github.com/pquarterman17/quantized
+Project-URL: Releases, https://github.com/pquarterman17/quantized/releases
+Project-URL: Issues, https://github.com/pquarterman17/quantized/issues
+Author: Paige Quarterman
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Requires-Python: >=3.11
+Requires-Dist: fastapi>=0.139.0
+Requires-Dist: h5py>=3.10
+Requires-Dist: matplotlib>=3.11.0
+Requires-Dist: numpy>=1.26
+Requires-Dist: openpyxl>=3.1
+Requires-Dist: periodictable>=1.7
+Requires-Dist: platformdirs>=4.10.0
+Requires-Dist: pydantic>=2.7
+Requires-Dist: python-multipart>=0.0.32
+Requires-Dist: scipy>=1.11
+Requires-Dist: uvicorn[standard]>=0.51.0
+Provides-Extra: bumps
+Requires-Dist: bumps>=1.0; extra == 'bumps'
+Provides-Extra: desktop
+Requires-Dist: pywebview>=5.1; extra == 'desktop'
+Provides-Extra: office
+Requires-Dist: python-docx>=1.1; extra == 'office'
+Requires-Dist: python-pptx>=1.0; extra == 'office'
+Provides-Extra: origin-com
+Requires-Dist: pywin32; (sys_platform == 'win32') and extra == 'origin-com'
+Provides-Extra: stats
+Requires-Dist: lifelines>=0.27; extra == 'stats'
+Requires-Dist: statsmodels>=0.14; extra == 'stats'
+Description-Content-Type: text/markdown
+
+# quantized
+
+**Plot, analyze, and publish lab data — magnetometry, X-ray/neutron
+diffraction & reflectometry, transport — in one fast, reproducible app.**
+
+A clean-architecture Python (FastAPI) + React application, born as a port
+of the `quantized_matlab` scientific toolbox and grown into a full
+OriginPro-class daily driver. Backend math is **golden-verified** against
+the MATLAB original; the GUI is a ground-up revamp.
+
+> **Install:** `pip install quantized-lab` → run `qz`
+> (the PyPI name is `quantized-lab`; the package you import and the
+> commands you run are plain `quantized` / `qz`)
+
+## What it does
+
+**Import instrument data** — Quantum Design VSM/PPMS/MPMS, Lake Shore VSM,
+PANalytical XRDML (1-D scans *and* 2-D reciprocal-space maps with Q-space),
+Rigaku, NCNR reflectometry/PNR, refl1d, SIMS, generic CSV/Excel — with
+content sniffing for ambiguous extensions, drag-drop, paste, guided import
+wizard, and one-click re-import when the source file changes.
+
+**Read and write OriginPro files** — native, clean-room `.opj`/`.opju`
+readers recover workbooks, figures (with styles, legends, annotations),
+and notes; the `.opj` writer produces projects real Origin loads; plus
+Origin-ASCII + `.ogs` scripts, `.otp` template import, and an optional
+Windows COM "Send to Origin" bridge.
+
+**Explore interactively** — an Origin-style pointer tool (drag, resize,
+and pin plot text; draggable legends), multi-window MDI with linked
+zoom/cursor groups, a ctrl-click panel builder (side-by-side / grid /
+overlay with automatic dual-Y by unit family), linked row selection and
+masking across every view, worksheet with formulas and filters, and
+app-wide **undo/redo**.
+
+**Analyze with domain depth** — 29+ fit models plus a no-eval custom
+equation builder, AICc model scanning, global/batch/ODR fits, an optional
+[bumps](https://github.com/bumps/bumps) engine with DREAM posterior
+sampling; a Peak Analyzer wizard; baselines from ALS to Shirley to
+interactive anchor points; Parratt reflectivity; RSM strain analysis;
+Williamson-Hall, FFT film thickness, and reflectivity-FFT reductions;
+hysteresis, relaxation, and a full statistics suite.
+
+**Publish** — vector PDF/SVG export (server-rendered matplotlib) that
+matches the screen: rich-text labels (µ₀H, Å⁻¹, χ″…), journal size
+presets (APS/Nature/thesis…), per-series styles, fills, color-mapped
+scatter, engineering/scientific tick formats, and a multi-panel figure
+composer for Fig. 1(a)–(d)-style pages.
+
+**Stay reproducible** — every correction is a replayable pipeline step
+with a recalculation DAG, a macro recorder emits runnable scripts,
+workspaces save to a single `.dwk` file, and everything is scriptable
+through the HTTP API and a plugin system.
+
+**DiraCulator** — the built-in materials calculators (units, X-ray/neutron,
+crystallography, SLD, semiconductors, superconductors, magnetism, optics,
+vacuum, and more) also launch standalone: `diraculator` (or
+`qz --calc`), with its own Start Menu entry in the Windows installer.
+
+## Scope
+
+Magnetometry / XRD / reflectometry / lab-data analysis. Electron-microscopy
+tooling (EELS/EDS, imaging) is **out of scope** and lives in the separate
+`fermiviewer` project.
+
+## Run it
+
+| Method | Command | Notes |
+|--------|---------|-------|
+| pipx (recommended) | `pipx install quantized-lab && qz` | isolated env, `qz` on PATH, no dev tools needed |
+| uv tool | `uv tool install quantized-lab && qz` | same idea, via `uv` |
+| pip | `pip install quantized-lab && qz` | into whatever env is active |
+| Native installer | download from [Releases](https://github.com/pquarterman17/quantized/releases) | Windows `.exe` (NSIS, auto-updates), macOS `.dmg`, Linux `.deb` — no Python required |
+| From source | see below | for development |
+
+Once installed, `qz` serves the app at `http://127.0.0.1:8000` and opens a
+browser tab. An empty library shows a **"Drop files here, or use ⊞ to import
+/ ✚ for a demo"** hint — click **✚** for an instant synthetic dataset, so a
+fresh install has something to plot within seconds.
+
+**From source — double-click a launcher** (builds the UI + installs deps on
+first run, then opens the app in your browser):
+
+- **Windows:** double-click `run.cmd`
+- **macOS:** double-click `run.command` (first time: right-click → Open)
+
+**Or one command** (after `uv` + Node.js are installed):
+
+```bash
+# first time only: build the UI bundle the app serves
+cd frontend && npm install && npm run build && cd ..
+
+uv run qz                 # serve on :8000 and open a browser tab
+uv run qz --port 9000     # different port
+uv run qz --no-browser    # headless (don't open a tab; never auto-exits)
+uv run qz --desktop       # native window (needs: pip install quantized-lab[desktop])
+uv run qz --dev           # contributor mode: Vite HMR + reloading backend
+uv run diraculator        # the materials calculators, standalone
+```
+
+The default mode behaves like an app: closing the last browser tab shuts
+the server down (a page refresh doesn't). Set `QZ_AUTO_SHUTDOWN=0` to opt
+out, use `--no-browser` for a persistent/headless server, or stop any mode
+with **Ctrl+C** in its window. A busy port falls back to a free one
+automatically, so the app and a standalone DiraCulator coexist.
+
+Building your own wheel/sdist? Build the frontend **first** —
+`cd frontend && npm ci && npm run build` — before `uv build`, or the wheel
+ships without a UI.
+
+## Documentation
+
+- **[Wiki](https://github.com/pquarterman17/quantized/wiki)** — installation,
+  getting started, feature guides, Origin interop
+- **[Releases](https://github.com/pquarterman17/quantized/releases)** —
+  installers + changelogs
+- [`RELEASE.md`](https://github.com/pquarterman17/quantized/blob/main/RELEASE.md)
+  — how releases are built and published
+- In-app: **⌘K** command palette, **Help ▸ Keyboard shortcuts**, and
+  **Help ▸ Text formatting** for the rich-text label syntax
+
+## Architecture (for contributors)
+
+Pure `io/` + `calc/` libraries (data in → results out, no web imports),
+thin FastAPI `routes/`, a 500-line per-module ceiling, ~400-line React
+component ceiling, and **golden tests** that freeze MATLAB outputs as the
+parity oracle — enforced by tests, not convention. See
+[`CLAUDE.md`](https://github.com/pquarterman17/quantized/blob/main/CLAUDE.md).
+
+```bash
+uv sync --group dev          # backend deps
+uv run pytest                # backend tests (+ `-m golden` for MATLAB parity)
+uv run ruff check src tests && uv run mypy src
+cd frontend && npm test && npm run build
+```
+
+License: Apache-2.0.

quantized_lab-0.9.0/README.md

@@ -0,0 +1,137 @@
+# quantized
+
+**Plot, analyze, and publish lab data — magnetometry, X-ray/neutron
+diffraction & reflectometry, transport — in one fast, reproducible app.**
+
+A clean-architecture Python (FastAPI) + React application, born as a port
+of the `quantized_matlab` scientific toolbox and grown into a full
+OriginPro-class daily driver. Backend math is **golden-verified** against
+the MATLAB original; the GUI is a ground-up revamp.
+
+> **Install:** `pip install quantized-lab` → run `qz`
+> (the PyPI name is `quantized-lab`; the package you import and the
+> commands you run are plain `quantized` / `qz`)
+
+## What it does
+
+**Import instrument data** — Quantum Design VSM/PPMS/MPMS, Lake Shore VSM,
+PANalytical XRDML (1-D scans *and* 2-D reciprocal-space maps with Q-space),
+Rigaku, NCNR reflectometry/PNR, refl1d, SIMS, generic CSV/Excel — with
+content sniffing for ambiguous extensions, drag-drop, paste, guided import
+wizard, and one-click re-import when the source file changes.
+
+**Read and write OriginPro files** — native, clean-room `.opj`/`.opju`
+readers recover workbooks, figures (with styles, legends, annotations),
+and notes; the `.opj` writer produces projects real Origin loads; plus
+Origin-ASCII + `.ogs` scripts, `.otp` template import, and an optional
+Windows COM "Send to Origin" bridge.
+
+**Explore interactively** — an Origin-style pointer tool (drag, resize,
+and pin plot text; draggable legends), multi-window MDI with linked
+zoom/cursor groups, a ctrl-click panel builder (side-by-side / grid /
+overlay with automatic dual-Y by unit family), linked row selection and
+masking across every view, worksheet with formulas and filters, and
+app-wide **undo/redo**.
+
+**Analyze with domain depth** — 29+ fit models plus a no-eval custom
+equation builder, AICc model scanning, global/batch/ODR fits, an optional
+[bumps](https://github.com/bumps/bumps) engine with DREAM posterior
+sampling; a Peak Analyzer wizard; baselines from ALS to Shirley to
+interactive anchor points; Parratt reflectivity; RSM strain analysis;
+Williamson-Hall, FFT film thickness, and reflectivity-FFT reductions;
+hysteresis, relaxation, and a full statistics suite.
+
+**Publish** — vector PDF/SVG export (server-rendered matplotlib) that
+matches the screen: rich-text labels (µ₀H, Å⁻¹, χ″…), journal size
+presets (APS/Nature/thesis…), per-series styles, fills, color-mapped
+scatter, engineering/scientific tick formats, and a multi-panel figure
+composer for Fig. 1(a)–(d)-style pages.
+
+**Stay reproducible** — every correction is a replayable pipeline step
+with a recalculation DAG, a macro recorder emits runnable scripts,
+workspaces save to a single `.dwk` file, and everything is scriptable
+through the HTTP API and a plugin system.
+
+**DiraCulator** — the built-in materials calculators (units, X-ray/neutron,
+crystallography, SLD, semiconductors, superconductors, magnetism, optics,
+vacuum, and more) also launch standalone: `diraculator` (or
+`qz --calc`), with its own Start Menu entry in the Windows installer.
+
+## Scope
+
+Magnetometry / XRD / reflectometry / lab-data analysis. Electron-microscopy
+tooling (EELS/EDS, imaging) is **out of scope** and lives in the separate
+`fermiviewer` project.
+
+## Run it
+
+| Method | Command | Notes |
+|--------|---------|-------|
+| pipx (recommended) | `pipx install quantized-lab && qz` | isolated env, `qz` on PATH, no dev tools needed |
+| uv tool | `uv tool install quantized-lab && qz` | same idea, via `uv` |
+| pip | `pip install quantized-lab && qz` | into whatever env is active |
+| Native installer | download from [Releases](https://github.com/pquarterman17/quantized/releases) | Windows `.exe` (NSIS, auto-updates), macOS `.dmg`, Linux `.deb` — no Python required |
+| From source | see below | for development |
+
+Once installed, `qz` serves the app at `http://127.0.0.1:8000` and opens a
+browser tab. An empty library shows a **"Drop files here, or use ⊞ to import
+/ ✚ for a demo"** hint — click **✚** for an instant synthetic dataset, so a
+fresh install has something to plot within seconds.
+
+**From source — double-click a launcher** (builds the UI + installs deps on
+first run, then opens the app in your browser):
+
+- **Windows:** double-click `run.cmd`
+- **macOS:** double-click `run.command` (first time: right-click → Open)
+
+**Or one command** (after `uv` + Node.js are installed):
+
+```bash
+# first time only: build the UI bundle the app serves
+cd frontend && npm install && npm run build && cd ..
+
+uv run qz                 # serve on :8000 and open a browser tab
+uv run qz --port 9000     # different port
+uv run qz --no-browser    # headless (don't open a tab; never auto-exits)
+uv run qz --desktop       # native window (needs: pip install quantized-lab[desktop])
+uv run qz --dev           # contributor mode: Vite HMR + reloading backend
+uv run diraculator        # the materials calculators, standalone
+```
+
+The default mode behaves like an app: closing the last browser tab shuts
+the server down (a page refresh doesn't). Set `QZ_AUTO_SHUTDOWN=0` to opt
+out, use `--no-browser` for a persistent/headless server, or stop any mode
+with **Ctrl+C** in its window. A busy port falls back to a free one
+automatically, so the app and a standalone DiraCulator coexist.
+
+Building your own wheel/sdist? Build the frontend **first** —
+`cd frontend && npm ci && npm run build` — before `uv build`, or the wheel
+ships without a UI.
+
+## Documentation
+
+- **[Wiki](https://github.com/pquarterman17/quantized/wiki)** — installation,
+  getting started, feature guides, Origin interop
+- **[Releases](https://github.com/pquarterman17/quantized/releases)** —
+  installers + changelogs
+- [`RELEASE.md`](https://github.com/pquarterman17/quantized/blob/main/RELEASE.md)
+  — how releases are built and published
+- In-app: **⌘K** command palette, **Help ▸ Keyboard shortcuts**, and
+  **Help ▸ Text formatting** for the rich-text label syntax
+
+## Architecture (for contributors)
+
+Pure `io/` + `calc/` libraries (data in → results out, no web imports),
+thin FastAPI `routes/`, a 500-line per-module ceiling, ~400-line React
+component ceiling, and **golden tests** that freeze MATLAB outputs as the
+parity oracle — enforced by tests, not convention. See
+[`CLAUDE.md`](https://github.com/pquarterman17/quantized/blob/main/CLAUDE.md).
+
+```bash
+uv sync --group dev          # backend deps
+uv run pytest                # backend tests (+ `-m golden` for MATLAB parity)
+uv run ruff check src tests && uv run mypy src
+cd frontend && npm test && npm run build
+```
+
+License: Apache-2.0.

{quantized_lab-0.8.0 → quantized_lab-0.9.0}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "quantized-lab"
-version = "0.8.0"
-description = "Clean-architecture Python + React port of the quantized_matlab scientific toolbox (magnetometry / XRD / lab data)."
+version = "0.9.0"
+description = "Plot, analyze, and publish lab data - magnetometry, XRD, reflectometry - with OriginPro file interop, golden-verified analysis, and reproducible pipelines."
 readme = "README.md"
 requires-python = ">=3.11"
 license = "Apache-2.0"
@@ -20,6 +20,13 @@ dependencies = [
     "platformdirs>=4.10.0",
 ]
 
+[project.urls]
+Homepage = "https://github.com/pquarterman17/quantized"
+Documentation = "https://github.com/pquarterman17/quantized/wiki"
+Repository = "https://github.com/pquarterman17/quantized"
+Releases = "https://github.com/pquarterman17/quantized/releases"
+Issues = "https://github.com/pquarterman17/quantized/issues"
+
 [project.scripts]
 qz = "quantized.cli:main"
 quantized = "quantized.cli:main"

{quantized_lab-0.8.0 → quantized_lab-0.9.0}/src/quantized/__init__.py

@@ -7,5 +7,5 @@ Layered, enforced architecture (see CLAUDE.md):
 
 from __future__ import annotations
 
-__version__ = "0.7.0"
+__version__ = "0.9.0"
 __all__ = ["__version__"]

quantized_lab-0.9.0/src/quantized/calc/figure_labels.py

@@ -0,0 +1,127 @@
+"""Mathtext label guard for figure export (GOTO #5 rich-text labels).
+
+Labels flow from the UI as plain text with optional ``$...$`` mathtext
+regions (the frontend's ``lib/richtext`` micro-syntax is a strict subset of
+matplotlib mathtext, so passthrough is the rendering mechanism). matplotlib
+parses math regions at DRAW time, which means an invalid label would raise
+inside ``fig.savefig`` and turn an export into a 500. This module is the
+shared chokepoint every ``calc.figure*`` renderer routes its user-supplied
+strings through: it pre-validates with matplotlib's own mathtext parser and,
+on failure, escapes the dollar signs so the label renders as literal text
+(matplotlib renders ``\\$`` as a plain ``$``) -- an invalid label must NEVER
+error an export.
+
+Screen/export WYSIWYG (bug-hunt fix): the frontend's parser
+(``frontend/src/lib/richtext.ts``) only accepts a STRICT SUBSET of
+mathtext -- Greek letters, ``\\AA \\circ \\times \\cdot \\pm \\prime \\,
+\\mathrm \\mathit``, and literal Unicode -- and rejects everything else
+(e.g. ``\\frac``, ``\\sqrt``, ``\\sum``) as invalid markup, rendering it
+literally on screen. Raw matplotlib accepts a much larger command set, so
+without this gate a label like ``$\\frac{1}{2}$`` would render literal text
+("Invalid markup") on screen but an actual fraction in the PDF/SVG export --
+a WYSIWYG violation. `_uses_only_supported_commands` enumerates the SAME
+command set the frontend parser accepts and rejects (falls back to literal)
+any ``$...$`` region using a command outside it, BEFORE the matplotlib trial
+parse below ever runs. Keep `SUPPORTED_MATHTEXT_COMMANDS` in sync with
+richtext.ts's ``GREEK``/``SYMBOLS`` tables + ``mathrm``/``mathit`` handling.
+
+Pure layer: string in -> string out. matplotlib is imported lazily (same
+convention as the figure modules -- the heavy import is paid only on export).
+"""
+
+from __future__ import annotations
+
+import re
+from functools import lru_cache
+from typing import Any
+
+__all__ = ["safe_mathtext_label", "SUPPORTED_MATHTEXT_COMMANDS"]
+
+# A "$" not preceded by a backslash -- matplotlib's own math-region rule
+# (matplotlib.cbook.is_math_text counts these; an odd count means the string
+# is rendered as literal text, dollars visible, no mathtext at all).
+_UNESCAPED_DOLLAR = re.compile(r"(?<!\\)\$")
+
+# A backslash command name (`\foo`) inside a math region. `\,` (thin space)
+# is handled separately by richtext.ts before its name-based dispatch and
+# has no letters, so it never matches this and is implicitly always allowed.
+_COMMAND = re.compile(r"\\([a-zA-Z]+)")
+
+# Mirrors frontend/src/lib/richtext.ts's `GREEK` table: lowercase (+ \var*
+# variants) render italic, uppercase upright -- irrelevant here, we only
+# need the NAME set, not the styling.
+_GREEK_COMMANDS = frozenset(
+    {
+        "alpha", "beta", "gamma", "delta", "epsilon", "varepsilon", "zeta",
+        "eta", "theta", "vartheta", "iota", "kappa", "lambda", "mu", "nu",
+        "xi", "pi", "rho", "sigma", "varsigma", "tau", "upsilon", "phi",
+        "varphi", "chi", "psi", "omega",
+        "Gamma", "Delta", "Theta", "Lambda", "Xi", "Pi", "Sigma", "Upsilon",
+        "Phi", "Psi", "Omega",
+    }
+)
+# Mirrors richtext.ts's `SYMBOLS` table (non-Greek symbol commands).
+_SYMBOL_COMMANDS = frozenset({"AA", "circ", "times", "cdot", "pm", "prime"})
+# Mirrors richtext.ts's `\mathrm{...}` / `\mathit{...}` style-group handling.
+_STYLE_COMMANDS = frozenset({"mathrm", "mathit"})
+
+SUPPORTED_MATHTEXT_COMMANDS = _GREEK_COMMANDS | _SYMBOL_COMMANDS | _STYLE_COMMANDS
+
+
+def _uses_only_supported_commands(label: str) -> bool:
+    """True when every backslash command inside every ``$...$`` region of
+    `label` is in `SUPPORTED_MATHTEXT_COMMANDS`. Text OUTSIDE `$...$` is
+    never scanned -- a stray backslash there is the caller's problem, not
+    this gate's (and richtext.ts itself only ever considers commands inside
+    math regions). Assumes a balanced (even) unescaped-`$` count, as
+    guaranteed by `safe_mathtext_label` calling this only after that check.
+    """
+    segments = _UNESCAPED_DOLLAR.split(label)
+    for i, segment in enumerate(segments):
+        if i % 2 == 0:
+            continue  # literal text outside $...$
+        for m in _COMMAND.finditer(segment):
+            if m.group(1) not in SUPPORTED_MATHTEXT_COMMANDS:
+                return False
+    return True
+
+
+@lru_cache(maxsize=1)
+def _parser() -> Any:
+    """The mathtext trial parser (cached -- construction is not free)."""
+    from matplotlib.mathtext import MathTextParser
+
+    return MathTextParser("agg")
+
+
+def safe_mathtext_label(label: str) -> str:
+    """Return ``label`` unchanged when it renders safely; else de-math it.
+
+    - No ``$`` at all: fast path, returned as-is (byte-identical to today).
+    - Odd count of unescaped ``$``: matplotlib already treats the whole
+      string as literal text -- returned as-is.
+    - Balanced ``$...$`` regions using only commands the frontend's
+      richtext.ts subset also accepts (`SUPPORTED_MATHTEXT_COMMANDS`), AND
+      that trial-parse successfully with matplotlib's mathtext parser ->
+      unchanged (mathtext renders it at export, matching the screen).
+      Otherwise (an out-of-subset command, e.g. ``\\frac``/``\\sqrt``/
+      ``\\sum``, OR a parse failure even within the subset, e.g. unbalanced
+      braces) -> every unescaped ``$`` is escaped to ``\\$`` so matplotlib
+      renders the literal string (dollars visible) instead of raising at
+      savefig time OR silently rendering richer math than the screen ever
+      showed.
+    """
+    if not label or "$" not in label:
+        return label
+    n_math = len(_UNESCAPED_DOLLAR.findall(label))
+    if n_math == 0 or n_math % 2 == 1:
+        # Zero unescaped $ (all \$-escaped) or an odd count: matplotlib
+        # already renders the whole string as literal text -- leave it be.
+        return label
+    if not _uses_only_supported_commands(label):
+        return _UNESCAPED_DOLLAR.sub(r"\\$", label)
+    try:
+        _parser().parse(label)
+    except Exception:  # ANY parse failure means "render literal", never raise
+        return _UNESCAPED_DOLLAR.sub(r"\\$", label)
+    return label

{quantized_lab-0.8.0 → quantized_lab-0.9.0}/src/quantized/calc/figure_overrides.py

@@ -17,6 +17,7 @@ from collections.abc import Mapping
 from typing import Any
 
 from quantized.calc.figure_labels import safe_mathtext_label
+from quantized.calc.figure_shapes import _apply_shapes, _validate_shapes
 
 __all__ = ["_apply_overrides", "_validate_overrides"]
 
@@ -63,6 +64,7 @@ def _validate_overrides(ov: Mapping[str, Any]) -> None:
             if prev_hi is not None and lo < prev_hi:
                 raise ValueError("x_breaks entries must be sorted and non-overlapping")
             prev_hi = hi
+    _validate_shapes(ov.get("shapes"))
 
 
 def _apply_overrides(
@@ -142,6 +144,23 @@ def _apply_overrides(
             # pixel-identical placement between screen and export.
             ann_kw["xycoords"] = "figure fraction"
             y = 1.0 - y
+        frame = ann.get("frame")
+        if frame:
+            # MAIN #27 "text box": a bbox behind the annotation text. `pad`
+            # (screen CSS px around the measured text) has no exact
+            # matplotlib equivalent (`boxstyle="square,pad=N"`'s pad is in
+            # font-size units, not px) -- divided by a fixed factor so the
+            # box reads as padded rather than pixel-identical, the same
+            # "Origin-parity-in-spirit, not pixel-identical" caveat the
+            # page-anchor y-flip above documents. fc/ec default to a plain
+            # white-card-on-black-border look (independent of the screen's
+            # own dark-canvas ink default -- publication export is white-bg).
+            ann_kw["bbox"] = dict(
+                boxstyle=f"square,pad={float(frame.get('pad', 4)) / 4.0}",
+                fc=frame.get("fill") or "white",
+                ec=frame.get("stroke") or "black",
+                alpha=frame.get("opacity", 1.0),
+            )
         ax.annotate(
             safe_mathtext_label(str(ann.get("text", ""))),
             xy=(x, y),
@@ -157,3 +176,8 @@ def _apply_overrides(
             top=None if margins.get("top") is None else 1.0 - float(margins["top"]),
             bottom=margins.get("bottom"),
         )
+
+    # MAIN #27: shapes paint LAST -- on top of everything else this sweep
+    # drew (annotations included), matching export intent: shapes mark up
+    # the finished figure.
+    _apply_shapes(fig, ax, ov.get("shapes"))

quantized_lab-0.9.0/src/quantized/calc/figure_shapes.py

@@ -0,0 +1,153 @@
+"""Drawn-shape overrides (MAIN #27) -- export parity for the screen's
+``lib/uplotShapes.ts``. Split out of ``figure_overrides.py`` purely to stay
+under each module's line-count discipline (same reasoning as
+``figure_labels.py`` / ``figure_break.py``) -- the behavioural contract is
+still ``figure_overrides``'s; ``_apply_overrides`` calls ``_apply_shapes``
+as its last step, AFTER the annotation sweep, so shapes paint on TOP of
+everything else the override sweep drew (annotations included) -- matching
+export intent: shapes mark up the finished figure. Pure layer: mapping in ->
+mutates the passed matplotlib Figure/Axes, no return value.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Any, Literal
+
+from matplotlib.lines import Line2D
+from matplotlib.patches import Ellipse, FancyArrowPatch, Rectangle
+
+__all__ = ["_apply_shapes", "_validate_shapes"]
+
+_SHAPE_KINDS = frozenset({"arrow", "line", "rect", "ellipse"})
+
+# Default whole-shape opacity (fill AND stroke, ONE knob) mirroring the
+# screen's `defaultShapeOpacity` (lib/uplotShapes.ts): 1 for line/arrow, 0.35
+# for rect/ellipse (a freshly drawn box reads as visibly translucent OVER
+# the data it marks).
+_DEFAULT_OPACITY = {"arrow": 1.0, "line": 1.0, "rect": 0.35, "ellipse": 0.35}
+_DEFAULT_WIDTH = 1.5
+_DEFAULT_STROKE = "black"
+
+
+def _validate_shapes(shapes: Sequence[Mapping[str, Any]] | None) -> None:
+    """Raise ``ValueError`` on a malformed shape (bad kind, non-finite
+    coords); a shape with an unknown/missing key inside is otherwise
+    tolerant (unknown keys ignored), mirroring ``_validate_overrides``."""
+    if not shapes:
+        return
+    for sh in shapes:
+        kind = sh.get("kind")
+        if kind not in _SHAPE_KINDS:
+            raise ValueError(f"shape kind must be one of {sorted(_SHAPE_KINDS)}")
+        for key in ("x1", "y1", "x2", "y2"):
+            v = sh.get(key)
+            if not isinstance(v, (int, float)) or isinstance(v, bool):
+                raise ValueError(f"shape {key} must be a number")
+
+
+def _shape_endpoints(
+    sh: Mapping[str, Any], ax: Any, fig: Any
+) -> tuple[tuple[float, float], tuple[float, float], Any]:
+    """(p1, p2, transform) for one shape, resolving its anchor -- DATA (the
+    default: ``ax.transData``, applied implicitly by omitting ``transform``
+    and adding via ``ax.add_patch``/``ax.add_line``) or PAGE (explicit
+    ``fig.transFigure``, Y FLIPPED -- canvas y grows downward, matplotlib
+    figure fraction grows upward -- the SAME convention
+    ``_apply_overrides``'s page-anchored annotation uses)."""
+    x1, y1 = float(sh["x1"]), float(sh["y1"])
+    x2, y2 = float(sh["x2"]), float(sh["y2"])
+    if sh.get("anchor") == "page":
+        return (x1, 1.0 - y1), (x2, 1.0 - y2), fig.transFigure
+    return (x1, y1), (x2, y2), ax.transData
+
+
+def _apply_shapes(fig: Any, ax: Any, shapes: Sequence[Mapping[str, Any]] | None) -> None:
+    """Draw MAIN #27 shapes (arrow/line/rect/ellipse). Arrows use
+    ``FancyArrowPatch``; plain lines ``Line2D``; rect/ellipse the matching
+    matplotlib patch with ``alpha`` -- all added via ``ax.add_patch``/
+    ``ax.add_line`` (data-anchored, the default -- no explicit ``transform``
+    needed there; matplotlib resolves an artist added this way against
+    ``ax.transData``) or with an EXPLICIT ``transform=fig.transFigure`` for
+    a page-anchored shape (``ax.add_patch``/``add_line`` never override an
+    already-set transform -- verified empirically, see the porting notes).
+    """
+    if not shapes:
+        return
+    for sh in shapes:
+        kind = sh.get("kind")
+        if kind not in _SHAPE_KINDS:
+            continue
+        p1, p2, transform = _shape_endpoints(sh, ax, fig)
+        stroke = sh.get("stroke") or _DEFAULT_STROKE
+        # `is not None` (not `or`): an explicit `width: 0` is falsy in Python
+        # and `... or _DEFAULT_WIDTH` was silently replacing it with the
+        # default (1.5) -- unlike the correct `opacity` idiom two lines below.
+        width = float(sh["width"]) if sh.get("width") is not None else _DEFAULT_WIDTH
+        dash: Literal["-", "--"] = "--" if sh.get("dash") else "-"
+        opacity = sh.get("opacity")
+        opacity = float(opacity) if opacity is not None else _DEFAULT_OPACITY[kind]
+        fill = sh.get("fill") or stroke
+        patch: Any
+
+        if kind == "arrow":
+            patch = FancyArrowPatch(
+                p1,
+                p2,
+                transform=transform,
+                arrowstyle="-|>",
+                mutation_scale=12 + width * 4,
+                # matplotlib's FancyArrowPatch default shrinkA/shrinkB=2pt
+                # insets BOTH ends from the given points (meant for
+                # "annotate near, not touching, an object") -- WYSIWYG with
+                # the screen's canvas draw (no shrink at all) needs the
+                # endpoints to land EXACTLY where dragged.
+                shrinkA=0,
+                shrinkB=0,
+                color=stroke,
+                linewidth=width,
+                linestyle=dash,
+                alpha=opacity,
+            )
+            ax.add_patch(patch)
+        elif kind == "line":
+            line = Line2D(
+                [p1[0], p2[0]],
+                [p1[1], p2[1]],
+                transform=transform,
+                color=stroke,
+                linewidth=width,
+                linestyle=dash,
+                alpha=opacity,
+            )
+            ax.add_line(line)
+        elif kind == "rect":
+            x0, x1v = min(p1[0], p2[0]), max(p1[0], p2[0])
+            y0, y1v = min(p1[1], p2[1]), max(p1[1], p2[1])
+            patch = Rectangle(
+                (x0, y0),
+                x1v - x0,
+                y1v - y0,
+                transform=transform,
+                edgecolor=stroke,
+                facecolor=fill,
+                linewidth=width,
+                linestyle=dash,
+                alpha=opacity,
+            )
+            ax.add_patch(patch)
+        else:  # ellipse
+            cx, cy = (p1[0] + p2[0]) / 2, (p1[1] + p2[1]) / 2
+            w, h = abs(p2[0] - p1[0]), abs(p2[1] - p1[1])
+            patch = Ellipse(
+                (cx, cy),
+                w,
+                h,
+                transform=transform,
+                edgecolor=stroke,
+                facecolor=fill,
+                linewidth=width,
+                linestyle=dash,
+                alpha=opacity,
+            )
+            ax.add_patch(patch)