gratinglab 0.3.4__tar.gz → 0.3.5__tar.gz

{gratinglab-0.3.4/src/gratinglab.egg-info → gratinglab-0.3.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gratinglab
-Version: 0.3.4
+Version: 0.3.5
 Summary: Open platform for diffraction grating groove metrology and efficiency analysis
 Author: Jake McCoy, Aditi Gangadharan
 License: BSD-3-Clause

{gratinglab-0.3.4 → gratinglab-0.3.5}/src/gratinglab/__init__.py

@@ -22,7 +22,7 @@ from .measured import MeasuredEfficiency, MeasurementProvenance
 from .resolution import ResolvingPower, resolving_power
 from .result import EfficiencyScan, OrderEfficiency, Provenance
 
-__version__ = "0.3.4"
+__version__ = "0.3.5"
 
 __all__ = [
     "Illumination",

{gratinglab-0.3.4 → gratinglab-0.3.5}/src/gratinglab/gui/mathtext.py

@@ -173,7 +173,12 @@ def strip_boxed(latex: str) -> str:
 
 
 def render_math_png(
-    latex: str, *, dpi: int = 140, color: str = "black"
+    latex: str,
+    *,
+    dpi: int = 140,
+    color: str = "black",
+    axis_pt: float | None = None,
+    min_height_pt: float = 0.0,
 ) -> bytes | None:
     r"""Rasterize a LaTeX string (no `$` delimiters) to PNG bytes.
 
@@ -192,6 +197,20 @@ def render_math_png(
     confirmed that mathtext's parser does not tolerate an embedded ``\n``. Any
     run of whitespace is therefore collapsed to a single space before parsing,
     which matches what plain LaTeX would do with the same source.
+
+    ``axis_pt`` is for an equation set inside a line of text. Qt places an
+    image aligned ``vertical-align: middle`` with its centre a quarter of the
+    font's x-height above the baseline, so given that height in points of the
+    10 pt render, space is added above or below until the image's centre lands
+    there exactly when the equation's own baseline sits on the text's. Without
+    it the image's bottom edge sits on the baseline, and every symbol with a
+    descender rides above the line.
+
+    That rule holds only for an image at least about three x-heights tall;
+    Qt sets a shorter one higher, by an amount that depends on its height
+    (measured with PySide6 6.11 on 2026-11-12, by scanning solid images from
+    8 to 32 px against a 14 px font). ``min_height_pt`` pads the image evenly
+    above and below up to that height, which keeps the centre where it was.
     """
     import io
     import re
@@ -205,7 +224,69 @@ def render_math_png(
 
     buffer = io.BytesIO()
     try:
-        math_to_image(f"${normalized}$", buffer, dpi=dpi, format="png", color=color)
+        if axis_pt is None:
+            math_to_image(f"${normalized}$", buffer, dpi=dpi, format="png", color=color)
+            return buffer.getvalue()
+        return _inline_png(normalized, dpi, color, axis_pt, min_height_pt)
     except ValueError:
         return None
+
+
+def _inline_png(
+    latex: str, dpi: int, color: str, axis_pt: float, min_height_pt: float
+) -> bytes:
+    """An inline equation as a transparent PNG, padded about its baseline.
+
+    The baseline is measured rather than taken from mathtext's box depth,
+    which is the layout box and not where the glyphs land: rasterised at
+    101 dpi the two differ by a pixel in either direction depending on the
+    expression. So the expression is rendered a second time with an upright
+    ``x`` after it, which sits on the baseline, and the bottom of that ``x``
+    is read off. The two renders share one vertical frame whenever the ``x``
+    is no taller and no deeper than the expression, which is any expression
+    holding a letter or digit; otherwise the box depth is used.
+    """
+    import io
+
+    import numpy as np
+    from matplotlib.colors import to_rgb
+    from matplotlib.image import imsave
+    from matplotlib.mathtext import MathTextParser
+
+    parser = MathTextParser("agg")
+    ink = np.asarray(parser.parse(f"${latex}$", dpi=dpi).image)
+    probe = parser.parse(f"${latex}" + r"\mathrm{x}$", dpi=dpi)
+    probe_ink = np.asarray(probe.image)
+    rows = ink.shape[0]
+    if probe_ink.shape[0] == rows:
+        # The rightmost couple of points of the x: its right leg ends on
+        # the baseline, and nothing of the expression reaches that far.
+        columns = np.flatnonzero(probe_ink.max(axis=0))
+        leg = probe_ink[:, columns[-1] - max(1, round(2 * dpi / 72)) + 1 : columns[-1] + 1]
+        baseline = int(np.flatnonzero(leg.max(axis=1) > 100)[-1]) + 1
+    else:
+        rendered = parser.parse(f"${latex}$", dpi=dpi)
+        baseline = int(rendered.height - rendered.depth) - 1
+
+    # Centre on the axis: (above - below) / 2 must equal the axis height.
+    scale = dpi / 72.0
+    above, below = float(baseline), float(rows - baseline)
+    excess = (above - below) - 2 * axis_pt * scale
+    if excess > 0:
+        below += excess
+    else:
+        above -= excess
+    short = min_height_pt * scale - (above + below)
+    if short > 0:
+        above += short / 2
+        below += short / 2
+    top = round(above) - baseline
+    bottom = round(below) - (rows - baseline)
+
+    alpha = np.pad(ink, ((top, bottom), (0, 0))).astype(float) / 255.0
+    rgba = np.empty(alpha.shape + (4,))
+    rgba[..., :3] = to_rgb(color)
+    rgba[..., 3] = alpha
+    buffer = io.BytesIO()
+    imsave(buffer, rgba, format="png")
     return buffer.getvalue()

{gratinglab-0.3.4 → gratinglab-0.3.5}/src/gratinglab/gui/qt/setup_tab.py

@@ -36,13 +36,12 @@ from PySide6.QtWidgets import (
     QLabel,
     QMessageBox,
     QPushButton,
-    QTextBrowser,
     QVBoxLayout,
     QWidget,
 )
 
 from ..docs import TheoryPage
-from .theory_viewer import render_into
+from .theory_viewer import ReadingBrowser, render_into
 
 #: What each reader's ``source`` string starts with, and what to cite for it.
 _CITATIONS = {
@@ -242,7 +241,7 @@ class SetupTab(QWidget):
 
     def __init__(self, parent: QWidget | None = None) -> None:
         super().__init__(parent)
-        self._browser = QTextBrowser()
+        self._browser = ReadingBrowser()
         self._browser.setOpenExternalLinks(False)
         self._browser.setOpenLinks(False)
         # Links leave for the system browser; the page itself never navigates.

gratinglab-0.3.5/src/gratinglab/gui/qt/theory_viewer.py

@@ -0,0 +1,210 @@
+"""The read-only viewer for one theory or reference page.
+
+The viewer is thin by design. :mod:`gratinglab.gui.richtext` turns the page
+into HTML and a list of rasterised equations, and this class only passes both
+to a `QTextBrowser`. Everything that could be wrong in a non-trivial way
+(table structure, escaping, math placement, the approximate-method banner) is
+decided and tested in that module, without a window.
+
+Images are registered with `QTextDocument.addResource` instead of being
+embedded as `data:` URIs, because `loadResource` does not handle `data:` by
+default. This also removes the least elegant detail of the Tk viewer: a list
+monkey-patched onto the window solely to keep `PhotoImage` objects alive
+against garbage collection while Tk was still displaying them.
+
+:class:`ReadingBrowser` is the page itself: a slightly larger font than the
+widgets around it, and a text column kept to a readable width and centred,
+so a wide window adds margin rather than longer lines. The math is sized
+from that font, so an equation in a sentence matches the words beside it.
+"""
+
+from __future__ import annotations
+
+from PySide6.QtCore import Qt, QUrl
+from PySide6.QtGui import (
+    QFontMetricsF,
+    QImage,
+    QTextBlockFormat,
+    QTextCursor,
+    QTextDocument,
+    QTextImageFormat,
+)
+from PySide6.QtWidgets import QTextBrowser, QVBoxLayout, QWidget
+
+from .. import richtext
+
+__all__ = ["ReadingBrowser", "TheoryViewer", "render_into"]
+
+#: Body text relative to the application font. The pages are long prose, and
+#: the 9 pt that suits a button is small for reading paragraphs of it.
+READING_SCALE = 1.15
+
+#: Widest the text column grows, in ems of the reading font: about 100
+#: characters of prose a line. A display equation wider than that widens the
+#: column to fit rather than scrolling sideways.
+READING_WIDTH_EMS = 50
+
+#: Space either side of the column, in pixels, when the window is narrower
+#: than the column.
+READING_MARGIN = 24
+
+#: Space around tables, which Qt otherwise sets flush against the paragraph
+#: above them.
+_STYLE = "table { margin-top: 6px; margin-bottom: 10px; } th { text-align: left; }"
+
+#: Extra space between lines, as a fraction of the font's pixel size. Added
+#: as a fixed distance rather than CSS ``line-height: 135%``, which scales
+#: each line's own height and so opens a wide gap around every line holding
+#: an equation.
+LEADING = 0.3
+
+
+class ReadingBrowser(QTextBrowser):
+    """A `QTextBrowser` laid out for reading a page rather than a log."""
+
+    def __init__(self, parent: QWidget | None = None) -> None:
+        super().__init__(parent)
+        font = self.font()
+        font.setPointSizeF(font.pointSizeF() * READING_SCALE)
+        self.setFont(font)
+        self.document().setDefaultFont(font)
+        self.document().setDefaultStyleSheet(_STYLE)
+        self._widest_image = 0.0
+
+    def resizeEvent(self, event) -> None:  # noqa: N802 - Qt's spelling
+        super().resizeEvent(event)
+        self._centre_column()
+
+    def pixel_size(self) -> float:
+        """The reading font's size in pixels.
+
+        From the point size and the screen's DPI rather than `QFontInfo`,
+        which reports the matched font and so reads near zero where no system
+        fonts are installed, as on the offscreen CI runs.
+        """
+        return self.font().pointSizeF() * self.logicalDpiY() / 72.0
+
+    def _centre_column(self) -> None:
+        column = max(self.pixel_size() * READING_WIDTH_EMS, self._widest_image)
+        spare = self.viewport().width() - column
+        side = max(READING_MARGIN, spare / 2)
+        root = self.document().rootFrame()
+        frame = root.frameFormat()
+        if frame.leftMargin() == side and frame.rightMargin() == side:
+            return
+        frame.setLeftMargin(side)
+        frame.setRightMargin(side)
+        frame.setTopMargin(READING_MARGIN / 2)
+        frame.setBottomMargin(READING_MARGIN)
+        root.setFrameFormat(frame)
+
+    def setHtml(self, text: str) -> None:  # noqa: N802 - Qt's spelling
+        # setHtml replaces the root frame's format along with the content.
+        super().setHtml(text)
+        leading = QTextBlockFormat()
+        leading.setLineHeight(
+            round(self.pixel_size() * LEADING),
+            QTextBlockFormat.LineHeightTypes.LineDistanceHeight.value,
+        )
+        cursor = QTextCursor(self.document())
+        cursor.select(QTextCursor.SelectionType.Document)
+        cursor.mergeBlockFormat(leading)
+        self._widest_image = _widest_image(self.document())
+        self._centre_column()
+
+
+def _widest_image(document: QTextDocument) -> float:
+    """The widest image in a document, in pixels, tables included."""
+    widest = 0.0
+    block = document.begin()
+    while block.isValid():
+        fragments = block.begin()
+        while not fragments.atEnd():
+            fmt = fragments.fragment().charFormat()
+            if fmt.isImageFormat():
+                widest = max(widest, QTextImageFormat(fmt).width())
+            fragments += 1
+        block = block.next()
+    return widest
+
+
+def render_into(
+    browser: QTextBrowser, page, *, device_pixel_ratio: float, text_color: str
+) -> None:
+    """Render a page into an existing `QTextBrowser`, images and all.
+
+    It is shared by :class:`TheoryViewer` and :class:`~.setup_tab.SetupTab`,
+    both of which show "one markdown-ish page, typeset, in a browser," and the
+    second use is what justified factoring this function out instead of
+    copying it.
+    """
+    font = browser.document().defaultFont()
+    pixels = font.pointSizeF() * browser.logicalDpiY() / 72.0
+    rendered = richtext.to_html(
+        page,
+        device_pixel_ratio=device_pixel_ratio,
+        color=text_color,
+        inline_dpi=richtext.math_dpi(pixels),
+        display_dpi=richtext.math_dpi(pixels, display=True),
+        **richtext.inline_metrics(pixels, QFontMetricsF(font).xHeight()),
+    )
+    document = browser.document()
+    for image in rendered.images:
+        document.addResource(
+            QTextDocument.ResourceType.ImageResource,
+            QUrl(image.key),
+            QImage.fromData(image.png, "PNG"),
+        )
+    browser.setHtml(rendered.html)
+
+
+class TheoryViewer(QWidget):
+    """One page, typeset."""
+
+    def __init__(self, page, parent: QWidget | None = None) -> None:
+        # A window in its own right rather than a modal dialog: reading the
+        # theory while adjusting the grating is the point.
+        super().__init__(parent)
+        self.setWindowFlag(Qt.WindowType.Window)
+        self.setWindowTitle(page.title)
+        self.resize(860, 720)
+
+        self._browser = ReadingBrowser()
+        self._browser.setOpenExternalLinks(False)
+        # Relative links between doc pages point at files on disk that this
+        # viewer has no route to open. Following them would empty the window.
+        self._browser.setOpenLinks(False)
+
+        layout = QVBoxLayout(self)
+        layout.setContentsMargins(0, 0, 0, 0)
+        layout.addWidget(self._browser)
+
+        self.set_page(page)
+        from . import theming
+
+        # Equations are images rasterised in the text colour, so a theme
+        # change re-renders the page rather than only repainting it.
+        theming.subscribe(self._on_theme)
+
+    def _on_theme(self, _theme) -> None:
+        # A bound method so Qt disconnects it with the window (see SetupTab).
+        self.set_page(self._page)
+
+    def set_page(self, page) -> None:
+        """Render a page into the browser, images and all."""
+        self._page = page
+        render_into(
+            self._browser,
+            page,
+            device_pixel_ratio=self.devicePixelRatioF(),
+            text_color=self._text_color(),
+        )
+
+    def _text_color(self) -> str:
+        """Rasterise math in the palette's own text colour.
+
+        Equations are images, so they do not follow a stylesheet the way the
+        surrounding prose does. Black math on a dark theme would be unreadable
+        only because its colour had been fixed at render time.
+        """
+        return self.palette().windowText().color().name()

{gratinglab-0.3.4 → gratinglab-0.3.5}/src/gratinglab/gui/richtext.py

@@ -60,6 +60,7 @@ __all__ = [
     "to_html",
     "png_size",
     "math_dpi",
+    "inline_metrics",
     "menu_label",
     "INLINE_DPI",
     "DISPLAY_DPI",
@@ -130,13 +131,23 @@ class _Collector:
     device_pixel_ratio: float
     color: str
     render: Callable[..., bytes | None]
+    axis_pt: float | None = None
+    min_height_pt: float = 0.0
     images: list[MathImage] = field(default_factory=list)
 
     def add(self, latex: str, *, display: bool) -> str:
         """Render one math span; return the HTML that stands for it."""
         base = self.display_dpi if display else self.inline_dpi
         dpi = max(1, round(base * self.device_pixel_ratio))
-        png = self.render(latex, dpi=dpi, color=self.color)
+        # Only inline math is set against a line of text. A display
+        # equation sits on its own line, so there is no baseline to meet.
+        centred = not display and self.axis_pt is not None
+        extra = (
+            {"axis_pt": self.axis_pt, "min_height_pt": self.min_height_pt}
+            if centred
+            else {}
+        )
+        png = self.render(latex, dpi=dpi, color=self.color, **extra)
 
         if png is None:
             delimiter = "$$" if display else "$"
@@ -156,7 +167,11 @@ class _Collector:
                 height=max(1, round(height / self.device_pixel_ratio)),
             )
         )
-        image = f'<img src="{key}" width="{self.images[-1].width}" height="{self.images[-1].height}">'
+        align = ' style="vertical-align:middle"' if centred else ""
+        image = (
+            f'<img src="{key}" width="{self.images[-1].width}" '
+            f'height="{self.images[-1].height}"{align}>'
+        )
         return f"<br>{image}<br>" if display else image
 
 
@@ -168,6 +183,8 @@ def render_markdown(
     device_pixel_ratio: float = 1.0,
     color: str = "black",
     render: Callable[..., bytes | None] | None = None,
+    axis_pt: float | None = None,
+    min_height_pt: float = 0.0,
 ) -> RichPage:
     """Convert markdown with `$...$` math to Qt-displayable HTML.
 
@@ -176,6 +193,11 @@ def render_markdown(
     ``None``. It defaults to a cached
     :func:`~gratinglab.gui.mathtext.render_math_png`. A page carries roughly
     forty equations, and the cache allows the viewer to reopen immediately.
+
+    ``axis_pt`` and ``min_height_pt`` put inline math on the text's
+    baseline; see :func:`~gratinglab.gui.mathtext.render_math_png` and
+    :func:`inline_metrics`. Left ``None``, an inline equation's bottom edge
+    sits on the baseline instead.
     """
     collector = _Collector(
         inline_dpi=inline_dpi,
@@ -183,6 +205,8 @@ def render_markdown(
         device_pixel_ratio=device_pixel_ratio,
         color=color,
         render=render if render is not None else _cached_render,
+        axis_pt=axis_pt,
+        min_height_pt=min_height_pt,
     )
     parts = [_block_html(block, collector) for block in _blocks(markdown)]
     return RichPage(html="\n".join(p for p in parts if p), images=tuple(collector.images))
@@ -439,6 +463,19 @@ def png_size(data: bytes) -> tuple[int, int] | None:
     )
 
 
+def inline_metrics(font_pixel_size: float, x_height: float) -> dict[str, float]:
+    """``axis_pt`` and ``min_height_pt`` for inline math beside this font.
+
+    Qt puts a middle-aligned image's centre a quarter of the x-height above
+    the baseline, provided the image is at least three x-heights tall. Both
+    are returned in points of the math render: mathtext renders at 10 pt and
+    :func:`math_dpi` scales that to the font's pixel size, so a pixel of the
+    text is ``10 / font_pixel_size`` points.
+    """
+    points = 10.0 / font_pixel_size
+    return {"axis_pt": x_height / 4.0 * points, "min_height_pt": 3.0 * x_height * points}
+
+
 def math_dpi(font_pixel_size: float, *, display: bool = False) -> int:
     """DPI at which mathtext output matches text of the given size.
 
@@ -464,9 +501,18 @@ def menu_label(title: str, suffix: str = "") -> str:
 
 
 @lru_cache(maxsize=512)
-def _cached_render(latex: str, *, dpi: int, color: str) -> bytes | None:
+def _cached_render(
+    latex: str,
+    *,
+    dpi: int,
+    color: str,
+    axis_pt: float | None = None,
+    min_height_pt: float = 0.0,
+) -> bytes | None:
     """Rasterise with caching.
 
     Without the cache, reopening the viewer would re-render every equation on
     the page, roughly forty of them, and more at 2x."""
-    return mathtext.render_math_png(latex, dpi=dpi, color=color)
+    return mathtext.render_math_png(
+        latex, dpi=dpi, color=color, axis_pt=axis_pt, min_height_pt=min_height_pt
+    )

gratinglab-0.3.5/src/gratinglab/io/__init__.py

@@ -0,0 +1,17 @@
+"""File formats other programs read or write.
+
+Each module handles one format, and nothing is imported here, so a caller
+names the module it wants (``from gratinglab.io.ggp import read_ggp``):
+
+``ggp``
+    PCGrate's ``.ggp`` groove profiles, read in all five border types and
+    written in the polygonal one.
+``boundary``
+    A measured groove profile saved with its period and provenance, as
+    gratinglab's own ``.json``, which reads back, or a write-only ``.csv``.
+    A ``.ggp`` cannot carry the period, which is why this exists beside it.
+``efficiency_table``
+    Efficiency tables exported by PCGrate-SX, read for comparison.
+``txl``
+    Raith ``.txl`` layouts of a grating, written for electron-beam writing.
+"""