plotpress 0.23.2__py3-none-any.whl

plotpress/fonts/__init__.py

@@ -0,0 +1,51 @@
+"""Bundled font metrics.
+
+SVG-first rendering means we never rasterize glyphs -- the viewer's renderer
+does that from the ``<text>`` elements we emit. We only need *metrics* (glyph
+advance widths) to size the canvas and align tick/axis labels. Bundled width
+tables keep layout deterministic across machines without a font-file
+dependency.
+
+``text_width`` measures the base-14 metric families -- Helvetica, Times and
+Courier, each in regular / bold / italic / bold-italic -- plus DejaVu Sans.
+That covers the metric-compatible clones too: Arial and Liberation Sans are
+Helvetica, Liberation Serif and Tinos are Times, Liberation Mono and Cousine
+are Courier.
+
+Known limitation
+----------------
+Because layout happens before anything draws the glyphs, plotpress has to
+*predict* how wide text will be, from the bundled tables only:
+
+* **Families outside those groups are measured as Helvetica.** Verdana, Tahoma,
+  Arial Black and Arial Narrow have proprietary metrics that match nothing
+  bundled here, so they still render but their legend boxes and axis margins are
+  sized for Helvetica.
+* **Small sizes quantize.** Renderers round glyph advances to whole pixels, so
+  even a perfectly matched face drifts a few tenths of a percent at tick-label
+  sizes. This is inherent to laying out text you do not rasterize; it shows up
+  as a little slack in margins, never as overlap.
+
+Lifting the first limitation for arbitrary families means measuring real font
+files, which makes layout depend on which fonts happen to be installed -- the
+very thing these tables exist to avoid. It is therefore offered as an opt-in
+rather than refused: see :mod:`plotpress.fonts.installed` and
+``Style(measure_installed_fonts=True)``.
+
+Module layout
+-------------
+``families``
+    The single registry of font families: which width table measures a CSS
+    stack, and which files should draw it. Declared together so layout and the
+    raster backend cannot disagree about what a family is.
+``metrics``
+    The bundled width tables and :func:`text_width`. Generated -- see
+    ``tools/gen_font_metrics.py`` for the sources.
+``installed``
+    Opt-in measurement of the real font files on this machine.
+"""
+
+from .families import font_files, resolve_family
+from .metrics import text_width
+
+__all__ = ["font_files", "resolve_family", "text_width"]

plotpress/fonts/families.py

@@ -0,0 +1,192 @@
+"""The one place that knows about font families.
+
+Two consumers need to answer questions about a CSS font stack, and they must
+not disagree:
+
+* **layout** (``fonts.metrics``) asks *which width table describes this stack*,
+  because it sizes margins and legend boxes before anything is drawn;
+* **the raster backend** asks *which font file should draw these glyphs*,
+  because PNG export rasterizes them itself.
+
+Splitting those tables across two modules is how you get glyphs drawn from a
+face that does not match the space reserved for them. So a family is declared
+once here, with both answers attached, and the fallback chain is derived from
+the declaration rather than written out by hand.
+
+The derivation rule: a stack's candidate files always end with faces belonging
+to its own *metric* family. That is what keeps the fallback safe. DejaVu Serif
+is 29% wider than Times and DejaVu Sans is 14% wider than Helvetica, so putting
+either at the end of a chain whose layout was computed from Times or Helvetica
+metrics silently overflows every box on a machine that has no better face
+installed.
+"""
+
+from __future__ import annotations
+
+from collections import namedtuple
+
+# ``metrics`` is the key into the bundled width tables; ``regular``/``bold`` are
+# candidate file names for the raster backend, best first.
+_Family = namedtuple("_Family", "metrics regular bold")
+
+# Faces belonging to each metric family, in rough platform order (macOS,
+# Windows, Linux). Every one of these agrees with the width table it is filed
+# under, which is what makes them safe fallbacks.
+HELVETICA_FILES = (
+    "Helvetica.ttc", "Helvetica.ttf",
+    "arial.ttf", "Arial.ttf",
+    "LiberationSans-Regular.ttf",
+    "Arimo-Regular.ttf",
+)
+HELVETICA_FILES_BOLD = (
+    "Helvetica-Bold.ttf",
+    "arialbd.ttf", "Arial Bold.ttf",
+    "LiberationSans-Bold.ttf",
+    "Arimo-Bold.ttf",
+)
+TIMES_FILES = (
+    "Times New Roman.ttf", "times.ttf",
+    "LiberationSerif-Regular.ttf",
+    "Tinos-Regular.ttf",
+)
+TIMES_FILES_BOLD = (
+    "Times New Roman Bold.ttf", "timesbd.ttf",
+    "LiberationSerif-Bold.ttf",
+    "Tinos-Bold.ttf",
+)
+# DejaVu Sans Mono earns its place here: it advances 602/1000 em against
+# Courier's flat 600, so it is Courier-metric to within a third of a percent.
+# Its sans and serif siblings are not, and are deliberately absent elsewhere.
+COURIER_FILES = (
+    "Courier New.ttf", "cour.ttf",
+    "LiberationMono-Regular.ttf",
+    "Cousine-Regular.ttf",
+    "DejaVuSansMono.ttf",
+)
+COURIER_FILES_BOLD = (
+    "Courier New Bold.ttf", "courbd.ttf",
+    "LiberationMono-Bold.ttf",
+    "Cousine-Bold.ttf",
+    "DejaVuSansMono-Bold.ttf",
+)
+DEJAVU_FILES = ("DejaVuSans.ttf",)
+DEJAVU_FILES_BOLD = ("DejaVuSans-Bold.ttf",)
+
+_METRIC_FILES = {
+    "helvetica": (HELVETICA_FILES, HELVETICA_FILES_BOLD),
+    "times": (TIMES_FILES, TIMES_FILES_BOLD),
+    "courier": (COURIER_FILES, COURIER_FILES_BOLD),
+    "dejavu sans": (DEJAVU_FILES, DEJAVU_FILES_BOLD),
+}
+
+DEFAULT_METRIC_FAMILY = "helvetica"
+
+_FAMILIES = {
+    # -- Helvetica and its metric-compatible clones -----------------------
+    "helvetica": _Family("helvetica", HELVETICA_FILES, HELVETICA_FILES_BOLD),
+    "helvetica neue": _Family("helvetica", ("HelveticaNeue.ttc",),
+                              ("HelveticaNeue-Bold.ttf",)),
+    "arial": _Family("helvetica", ("arial.ttf", "Arial.ttf"),
+                     ("arialbd.ttf", "Arial Bold.ttf")),
+    "liberation sans": _Family("helvetica", ("LiberationSans-Regular.ttf",),
+                               ("LiberationSans-Bold.ttf",)),
+    "arimo": _Family("helvetica", ("Arimo-Regular.ttf",), ("Arimo-Bold.ttf",)),
+    "nimbus sans": _Family("helvetica", ("NimbusSans-Regular.otf",),
+                           ("NimbusSans-Bold.otf",)),
+    "sans-serif": _Family("helvetica", HELVETICA_FILES, HELVETICA_FILES_BOLD),
+
+    # -- Times and its metric-compatible clones ---------------------------
+    "times": _Family("times", TIMES_FILES, TIMES_FILES_BOLD),
+    "times new roman": _Family("times", ("Times New Roman.ttf", "times.ttf"),
+                               ("Times New Roman Bold.ttf", "timesbd.ttf")),
+    "liberation serif": _Family("times", ("LiberationSerif-Regular.ttf",),
+                                ("LiberationSerif-Bold.ttf",)),
+    "tinos": _Family("times", ("Tinos-Regular.ttf",), ("Tinos-Bold.ttf",)),
+    "nimbus roman": _Family("times", ("NimbusRoman-Regular.otf",),
+                            ("NimbusRoman-Bold.otf",)),
+    "serif": _Family("times", TIMES_FILES, TIMES_FILES_BOLD),
+
+    # -- Courier and its metric-compatible clones -------------------------
+    "courier": _Family("courier", COURIER_FILES, COURIER_FILES_BOLD),
+    "courier new": _Family("courier", ("Courier New.ttf", "cour.ttf"),
+                           ("Courier New Bold.ttf", "courbd.ttf")),
+    "liberation mono": _Family("courier", ("LiberationMono-Regular.ttf",),
+                               ("LiberationMono-Bold.ttf",)),
+    "cousine": _Family("courier", ("Cousine-Regular.ttf",), ("Cousine-Bold.ttf",)),
+    "nimbus mono": _Family("courier", ("NimbusMonoPS-Regular.otf",),
+                           ("NimbusMonoPS-Bold.otf",)),
+    "monospace": _Family("courier", COURIER_FILES, COURIER_FILES_BOLD),
+
+    # -- DejaVu -----------------------------------------------------------
+    "dejavu sans": _Family("dejavu sans", DEJAVU_FILES, DEJAVU_FILES_BOLD),
+
+    # -- Declared, but not measurable -------------------------------------
+    # Proprietary metrics that match no bundled table, so layout measures them
+    # as Helvetica -- see the limitations docs. They are listed anyway so PNG
+    # export can still draw their real glyphs where the system has them; the
+    # derivation rule then tails the chain with Helvetica-metric faces rather
+    # than with whatever happens to look similar.
+    "verdana": _Family("helvetica", ("verdana.ttf", "Verdana.ttf"),
+                       ("verdanab.ttf", "Verdana Bold.ttf")),
+    "tahoma": _Family("helvetica", ("tahoma.ttf", "Tahoma.ttf"),
+                      ("tahomabd.ttf", "Tahoma Bold.ttf")),
+    "arial narrow": _Family("helvetica", ("ARIALN.TTF", "Arial Narrow.ttf"),
+                            ("ARIALNB.TTF", "Arial Narrow Bold.ttf")),
+    "arial black": _Family("helvetica", ("ariblk.ttf", "Arial Black.ttf"), ()),
+}
+
+
+def _names(family):
+    """The stack, lowercased and unquoted, in order."""
+    return [n.strip().strip("'\"").lower()
+            for n in (family or "").split(",") if n.strip()]
+
+
+def resolve_family(family):
+    """The metric family describing the first recognized name in a CSS stack.
+
+    Unknown names are skipped, so a stack naming an unmeasurable face first
+    still finds a measurable fallback behind it. A stack with no recognized
+    name at all resolves to Helvetica, which is what layout has always assumed.
+    """
+    for name in _names(family):
+        entry = _FAMILIES.get(name)
+        if entry is not None:
+            return entry.metrics
+    return DEFAULT_METRIC_FAMILY
+
+
+def font_files(family, bold=False):
+    """Candidate font files for a CSS stack, best first.
+
+    The chain is: the faces each named family actually is, then the faces of
+    the metric family layout measured it with, then -- for a bold request --
+    the same chain at regular weight, since the right glyphs at the wrong
+    weight beat the wrong glyphs entirely.
+
+    It ends with the Helvetica faces as a last resort. For a non-Helvetica
+    metric family that is a compromise rather than a match: it keeps a machine
+    with no serif or mono face installed rendering, but Helvetica glyphs are
+    wider than the Times metrics the layout used, so text can overflow. It
+    still beats Pillow's built-in bitmap default, which is both wider and
+    unscalable.
+    """
+    out = []
+
+    def add(names):
+        for f in names:
+            if f not in out:
+                out.append(f)
+
+    for name in _names(family):
+        entry = _FAMILIES.get(name)
+        if entry is not None:
+            add(entry.bold if bold else entry.regular)
+
+    regular_files, bold_files = _METRIC_FILES[resolve_family(family)]
+    add(bold_files if bold else regular_files)
+    if bold:
+        add(font_files(family, bold=False))
+    add(HELVETICA_FILES_BOLD if bold else ())
+    add(HELVETICA_FILES)
+    return out

plotpress/fonts/installed.py

@@ -0,0 +1,82 @@
+"""Opt-in measurement of the fonts actually installed on this machine.
+
+Off by default, and deliberately so. plotpress's bundled width tables exist to
+make layout *deterministic*: the same script produces the same margins on every
+machine, because it never asks the machine anything. Turning this on trades that
+guarantee for fidelity, and it is a real trade -- a figure laid out here may not
+match one laid out on a colleague's box, or on CI.
+
+Turn it on when the fidelity is worth more than the reproducibility: you are
+setting ``Style.font_family`` to a face plotpress cannot measure (Verdana,
+Tahoma, Arial Black, Arial Narrow) and you would rather have correct margins on
+your own machine than portable ones.
+
+    fig, ax = plotpress.subplots(
+        style=plotpress.Style(font_family="Verdana, sans-serif",
+                               measure_installed_fonts=True))
+
+Implementation note: this needs no new dependency. Pillow is already required
+for PNG export, it already resolves a bare font file name against the system
+font directories, and it already measures glyph advances -- the same machinery
+the raster backend draws with. Reusing it is what keeps layout and PNG output
+agreeing about what a face is: both go through
+:func:`plotpress.fonts.families.font_files`.
+"""
+
+from __future__ import annotations
+
+# Measured once at a large em square and scaled down, rather than at each label's
+# real size: advances are linear in size, so one probe serves every size, and a
+# big probe makes per-glyph integer rounding negligible.
+_PROBE_EM = 1000
+
+_ASCII = [chr(c) for c in range(32, 127)]
+
+_table_cache = {}
+
+
+def installed_table(family, bold=False, italic=False):
+    """``{char: advance per 1000 em}`` from a real font file, or ``None``.
+
+    Returns ``None`` -- meaning "fall back to the bundled tables" -- when no
+    candidate file resolves, or when Pillow was built without FreeType and so
+    cannot open a scalable face at all.
+
+    ``italic`` is accepted for signature parity with the bundled path but does
+    not select a different file: the family registry tracks weight, not slant,
+    since nothing in the default styling draws italic.
+    """
+    key = (family, bool(bold))
+    if key in _table_cache:
+        return _table_cache[key]
+
+    table = _measure(family, bool(bold))
+    _table_cache[key] = table
+    return table
+
+
+def _measure(family, bold):
+    try:
+        from PIL import ImageFont
+    except ImportError:                      # pragma: no cover - Pillow is required
+        return None
+
+    from .families import font_files
+
+    for name in font_files(family, bold):
+        try:
+            font = ImageFont.truetype(name, _PROBE_EM)
+        except (OSError, ImportError):
+            # Not installed here, or this Pillow has no FreeType. Either way the
+            # next candidate might still work.
+            continue
+        try:
+            return {ch: font.getlength(ch) for ch in _ASCII}
+        except (OSError, ValueError):        # pragma: no cover - malformed face
+            continue
+    return None
+
+
+def clear_cache():
+    """Forget measured faces. Only useful in tests, or if fonts change on disk."""
+    _table_cache.clear()

plotpress/fonts/metrics.py

@@ -0,0 +1,265 @@
+"""Advance-width tables for the fonts plotpress can measure.
+
+GENERATED by ``tools/gen_font_metrics.py`` -- do not edit by hand.
+
+Only the metric matters for layout: we place ``<text>`` and let the renderer
+draw glyphs. ``text_width`` estimates a string's rendered width so labels can be
+centered / right-aligned and margins sized.
+
+Widths are in 1/1000 em. Sources are the URW base-14 clones (metric-compatible
+with Adobe Helvetica / Times / Courier) and the DejaVu Sans TTFs; see the
+generator for why they are read by glyph name rather than by character code.
+
+Which table describes a given CSS font stack is decided in ``families.py``,
+alongside which files should draw it -- one declaration, so layout and the
+raster backend cannot disagree.
+"""
+
+from __future__ import annotations
+
+from .families import DEFAULT_METRIC_FAMILY, resolve_family
+
+_DEJAVU_SANS = {
+    ' ': 318, '!': 401, '"': 460, '#': 838, '$': 636, '%': 950, '&': 780, "'": 275,
+    '(': 390, ')': 390, '*': 500, '+': 838, ',': 318, '-': 361, '.': 318, '/': 337,
+    '0': 636, '1': 636, '2': 636, '3': 636, '4': 636, '5': 636, '6': 636, '7': 636,
+    '8': 636, '9': 636, ':': 337, ';': 337, '<': 838, '=': 838, '>': 838, '?': 531,
+    '@': 1000, 'A': 684, 'B': 686, 'C': 698, 'D': 770, 'E': 632, 'F': 575, 'G': 775,
+    'H': 752, 'I': 295, 'J': 295, 'K': 656, 'L': 557, 'M': 863, 'N': 748, 'O': 787,
+    'P': 603, 'Q': 787, 'R': 695, 'S': 635, 'T': 611, 'U': 732, 'V': 684, 'W': 989,
+    'X': 685, 'Y': 611, 'Z': 685, '[': 390, '\\': 337, ']': 390, '^': 838, '_': 500,
+    '`': 500, 'a': 613, 'b': 635, 'c': 550, 'd': 635, 'e': 615, 'f': 352, 'g': 635,
+    'h': 634, 'i': 278, 'j': 278, 'k': 579, 'l': 278, 'm': 974, 'n': 634, 'o': 612,
+    'p': 635, 'q': 635, 'r': 411, 's': 521, 't': 392, 'u': 634, 'v': 592, 'w': 818,
+    'x': 592, 'y': 592, 'z': 525, '{': 636, '|': 337, '}': 636, '~': 838,
+}
+
+_DEJAVU_SANS_ITALIC = {
+    ' ': 318, '!': 401, '"': 460, '#': 838, '$': 636, '%': 950, '&': 780, "'": 275,
+    '(': 390, ')': 390, '*': 500, '+': 838, ',': 318, '-': 361, '.': 318, '/': 337,
+    '0': 636, '1': 636, '2': 636, '3': 636, '4': 636, '5': 636, '6': 636, '7': 636,
+    '8': 636, '9': 636, ':': 337, ';': 337, '<': 838, '=': 838, '>': 838, '?': 531,
+    '@': 1000, 'A': 684, 'B': 686, 'C': 698, 'D': 770, 'E': 632, 'F': 575, 'G': 775,
+    'H': 752, 'I': 295, 'J': 295, 'K': 656, 'L': 557, 'M': 863, 'N': 748, 'O': 787,
+    'P': 603, 'Q': 787, 'R': 695, 'S': 635, 'T': 611, 'U': 732, 'V': 684, 'W': 989,
+    'X': 685, 'Y': 611, 'Z': 685, '[': 390, '\\': 337, ']': 390, '^': 838, '_': 500,
+    '`': 500, 'a': 613, 'b': 635, 'c': 550, 'd': 635, 'e': 615, 'f': 352, 'g': 635,
+    'h': 634, 'i': 278, 'j': 278, 'k': 579, 'l': 278, 'm': 974, 'n': 634, 'o': 612,
+    'p': 635, 'q': 635, 'r': 411, 's': 521, 't': 392, 'u': 634, 'v': 592, 'w': 818,
+    'x': 592, 'y': 592, 'z': 525, '{': 636, '|': 337, '}': 636, '~': 838,
+}
+
+_DEJAVU_SANS_BOLD = {
+    ' ': 348, '!': 456, '"': 521, '#': 838, '$': 696, '%': 1002, '&': 872, "'": 306,
+    '(': 457, ')': 457, '*': 523, '+': 838, ',': 380, '-': 415, '.': 380, '/': 365,
+    '0': 696, '1': 696, '2': 696, '3': 696, '4': 696, '5': 696, '6': 696, '7': 696,
+    '8': 696, '9': 696, ':': 400, ';': 400, '<': 838, '=': 838, '>': 838, '?': 580,
+    '@': 1000, 'A': 774, 'B': 762, 'C': 734, 'D': 830, 'E': 683, 'F': 683, 'G': 821,
+    'H': 837, 'I': 372, 'J': 372, 'K': 775, 'L': 637, 'M': 995, 'N': 837, 'O': 850,
+    'P': 733, 'Q': 850, 'R': 770, 'S': 720, 'T': 682, 'U': 812, 'V': 774, 'W': 1103,
+    'X': 771, 'Y': 724, 'Z': 725, '[': 457, '\\': 365, ']': 457, '^': 838, '_': 500,
+    '`': 500, 'a': 675, 'b': 716, 'c': 593, 'd': 716, 'e': 678, 'f': 435, 'g': 716,
+    'h': 712, 'i': 343, 'j': 343, 'k': 665, 'l': 343, 'm': 1042, 'n': 712, 'o': 687,
+    'p': 716, 'q': 716, 'r': 493, 's': 595, 't': 478, 'u': 712, 'v': 652, 'w': 924,
+    'x': 645, 'y': 652, 'z': 582, '{': 712, '|': 365, '}': 712, '~': 838,
+}
+
+_DEJAVU_SANS_BOLD_ITALIC = {
+    ' ': 348, '!': 456, '"': 521, '#': 696, '$': 696, '%': 1002, '&': 872, "'": 306,
+    '(': 457, ')': 457, '*': 523, '+': 838, ',': 380, '-': 415, '.': 380, '/': 365,
+    '0': 696, '1': 696, '2': 696, '3': 696, '4': 696, '5': 696, '6': 696, '7': 696,
+    '8': 696, '9': 696, ':': 400, ';': 400, '<': 838, '=': 838, '>': 838, '?': 580,
+    '@': 1000, 'A': 774, 'B': 762, 'C': 734, 'D': 830, 'E': 683, 'F': 683, 'G': 821,
+    'H': 837, 'I': 372, 'J': 372, 'K': 775, 'L': 637, 'M': 995, 'N': 837, 'O': 850,
+    'P': 733, 'Q': 850, 'R': 770, 'S': 720, 'T': 682, 'U': 812, 'V': 774, 'W': 1103,
+    'X': 771, 'Y': 724, 'Z': 725, '[': 457, '\\': 365, ']': 457, '^': 838, '_': 500,
+    '`': 500, 'a': 675, 'b': 716, 'c': 593, 'd': 716, 'e': 678, 'f': 435, 'g': 716,
+    'h': 712, 'i': 343, 'j': 343, 'k': 665, 'l': 343, 'm': 1042, 'n': 712, 'o': 687,
+    'p': 716, 'q': 716, 'r': 493, 's': 595, 't': 478, 'u': 712, 'v': 652, 'w': 924,
+    'x': 645, 'y': 652, 'z': 582, '{': 712, '|': 365, '}': 712, '~': 838,
+}
+
+_HELVETICA = {
+    ' ': 278, '!': 278, '"': 355, '#': 556, '$': 556, '%': 889, '&': 667, "'": 191,
+    '(': 333, ')': 333, '*': 389, '+': 584, ',': 278, '-': 333, '.': 278, '/': 278,
+    '0': 556, '1': 556, '2': 556, '3': 556, '4': 556, '5': 556, '6': 556, '7': 556,
+    '8': 556, '9': 556, ':': 278, ';': 278, '<': 584, '=': 584, '>': 584, '?': 556,
+    '@': 1015, 'A': 667, 'B': 667, 'C': 722, 'D': 722, 'E': 667, 'F': 611, 'G': 778,
+    'H': 722, 'I': 278, 'J': 500, 'K': 667, 'L': 556, 'M': 833, 'N': 722, 'O': 778,
+    'P': 667, 'Q': 778, 'R': 722, 'S': 667, 'T': 611, 'U': 722, 'V': 667, 'W': 944,
+    'X': 667, 'Y': 667, 'Z': 611, '[': 278, '\\': 278, ']': 278, '^': 469, '_': 556,
+    '`': 333, 'a': 556, 'b': 556, 'c': 500, 'd': 556, 'e': 556, 'f': 278, 'g': 556,
+    'h': 556, 'i': 222, 'j': 222, 'k': 500, 'l': 222, 'm': 833, 'n': 556, 'o': 556,
+    'p': 556, 'q': 556, 'r': 333, 's': 500, 't': 278, 'u': 556, 'v': 500, 'w': 722,
+    'x': 500, 'y': 500, 'z': 500, '{': 334, '|': 260, '}': 334, '~': 584,
+}
+
+_HELVETICA_ITALIC = {
+    ' ': 278, '!': 278, '"': 355, '#': 556, '$': 556, '%': 889, '&': 667, "'": 191,
+    '(': 333, ')': 333, '*': 389, '+': 584, ',': 278, '-': 333, '.': 278, '/': 278,
+    '0': 556, '1': 556, '2': 556, '3': 556, '4': 556, '5': 556, '6': 556, '7': 556,
+    '8': 556, '9': 556, ':': 278, ';': 278, '<': 584, '=': 584, '>': 584, '?': 556,
+    '@': 1015, 'A': 667, 'B': 667, 'C': 722, 'D': 722, 'E': 667, 'F': 611, 'G': 778,
+    'H': 722, 'I': 278, 'J': 500, 'K': 667, 'L': 556, 'M': 833, 'N': 722, 'O': 778,
+    'P': 667, 'Q': 778, 'R': 722, 'S': 667, 'T': 611, 'U': 722, 'V': 667, 'W': 944,
+    'X': 667, 'Y': 667, 'Z': 611, '[': 278, '\\': 278, ']': 278, '^': 469, '_': 556,
+    '`': 333, 'a': 556, 'b': 556, 'c': 500, 'd': 556, 'e': 556, 'f': 278, 'g': 556,
+    'h': 556, 'i': 222, 'j': 222, 'k': 500, 'l': 222, 'm': 833, 'n': 556, 'o': 556,
+    'p': 556, 'q': 556, 'r': 333, 's': 500, 't': 278, 'u': 556, 'v': 500, 'w': 722,
+    'x': 500, 'y': 500, 'z': 500, '{': 334, '|': 260, '}': 334, '~': 584,
+}
+
+_HELVETICA_BOLD = {
+    ' ': 278, '!': 333, '"': 474, '#': 556, '$': 556, '%': 889, '&': 722, "'": 238,
+    '(': 333, ')': 333, '*': 389, '+': 584, ',': 278, '-': 333, '.': 278, '/': 278,
+    '0': 556, '1': 556, '2': 556, '3': 556, '4': 556, '5': 556, '6': 556, '7': 556,
+    '8': 556, '9': 556, ':': 333, ';': 333, '<': 584, '=': 584, '>': 584, '?': 611,
+    '@': 975, 'A': 722, 'B': 722, 'C': 722, 'D': 722, 'E': 667, 'F': 611, 'G': 778,
+    'H': 722, 'I': 278, 'J': 556, 'K': 722, 'L': 611, 'M': 833, 'N': 722, 'O': 778,
+    'P': 667, 'Q': 778, 'R': 722, 'S': 667, 'T': 611, 'U': 722, 'V': 667, 'W': 944,
+    'X': 667, 'Y': 667, 'Z': 611, '[': 333, '\\': 278, ']': 333, '^': 584, '_': 556,
+    '`': 333, 'a': 556, 'b': 611, 'c': 556, 'd': 611, 'e': 556, 'f': 333, 'g': 611,
+    'h': 611, 'i': 278, 'j': 278, 'k': 556, 'l': 278, 'm': 889, 'n': 611, 'o': 611,
+    'p': 611, 'q': 611, 'r': 389, 's': 556, 't': 333, 'u': 611, 'v': 556, 'w': 778,
+    'x': 556, 'y': 556, 'z': 500, '{': 389, '|': 280, '}': 389, '~': 584,
+}
+
+_HELVETICA_BOLD_ITALIC = {
+    ' ': 278, '!': 333, '"': 474, '#': 556, '$': 556, '%': 889, '&': 722, "'": 238,
+    '(': 333, ')': 333, '*': 389, '+': 584, ',': 278, '-': 333, '.': 278, '/': 278,
+    '0': 556, '1': 556, '2': 556, '3': 556, '4': 556, '5': 556, '6': 556, '7': 556,
+    '8': 556, '9': 556, ':': 333, ';': 333, '<': 584, '=': 584, '>': 584, '?': 611,
+    '@': 975, 'A': 722, 'B': 722, 'C': 722, 'D': 722, 'E': 667, 'F': 611, 'G': 778,
+    'H': 722, 'I': 278, 'J': 556, 'K': 722, 'L': 611, 'M': 833, 'N': 722, 'O': 778,
+    'P': 667, 'Q': 778, 'R': 722, 'S': 667, 'T': 611, 'U': 722, 'V': 667, 'W': 944,
+    'X': 667, 'Y': 667, 'Z': 611, '[': 333, '\\': 278, ']': 333, '^': 584, '_': 556,
+    '`': 333, 'a': 556, 'b': 611, 'c': 556, 'd': 611, 'e': 556, 'f': 333, 'g': 611,
+    'h': 611, 'i': 278, 'j': 278, 'k': 556, 'l': 278, 'm': 889, 'n': 611, 'o': 611,
+    'p': 611, 'q': 611, 'r': 389, 's': 556, 't': 333, 'u': 611, 'v': 556, 'w': 778,
+    'x': 556, 'y': 556, 'z': 500, '{': 389, '|': 280, '}': 389, '~': 584,
+}
+
+_TIMES = {
+    ' ': 250, '!': 333, '"': 408, '#': 500, '$': 500, '%': 833, '&': 778, "'": 180,
+    '(': 333, ')': 333, '*': 500, '+': 564, ',': 250, '-': 333, '.': 250, '/': 278,
+    '0': 500, '1': 500, '2': 500, '3': 500, '4': 500, '5': 500, '6': 500, '7': 500,
+    '8': 500, '9': 500, ':': 278, ';': 278, '<': 564, '=': 564, '>': 564, '?': 444,
+    '@': 921, 'A': 722, 'B': 667, 'C': 667, 'D': 722, 'E': 611, 'F': 556, 'G': 722,
+    'H': 722, 'I': 333, 'J': 389, 'K': 722, 'L': 611, 'M': 889, 'N': 722, 'O': 722,
+    'P': 556, 'Q': 722, 'R': 667, 'S': 556, 'T': 611, 'U': 722, 'V': 722, 'W': 944,
+    'X': 722, 'Y': 722, 'Z': 611, '[': 333, '\\': 278, ']': 333, '^': 469, '_': 500,
+    '`': 333, 'a': 444, 'b': 500, 'c': 444, 'd': 500, 'e': 444, 'f': 333, 'g': 500,
+    'h': 500, 'i': 278, 'j': 278, 'k': 500, 'l': 278, 'm': 778, 'n': 500, 'o': 500,
+    'p': 500, 'q': 500, 'r': 333, 's': 389, 't': 278, 'u': 500, 'v': 500, 'w': 722,
+    'x': 500, 'y': 500, 'z': 444, '{': 480, '|': 200, '}': 480, '~': 541,
+}
+
+_TIMES_ITALIC = {
+    ' ': 250, '!': 333, '"': 420, '#': 500, '$': 500, '%': 833, '&': 778, "'": 214,
+    '(': 333, ')': 333, '*': 500, '+': 675, ',': 250, '-': 333, '.': 250, '/': 278,
+    '0': 500, '1': 500, '2': 500, '3': 500, '4': 500, '5': 500, '6': 500, '7': 500,
+    '8': 500, '9': 500, ':': 333, ';': 333, '<': 675, '=': 675, '>': 675, '?': 500,
+    '@': 920, 'A': 611, 'B': 611, 'C': 667, 'D': 722, 'E': 611, 'F': 611, 'G': 722,
+    'H': 722, 'I': 333, 'J': 444, 'K': 667, 'L': 556, 'M': 833, 'N': 667, 'O': 722,
+    'P': 611, 'Q': 722, 'R': 611, 'S': 500, 'T': 556, 'U': 722, 'V': 611, 'W': 833,
+    'X': 611, 'Y': 556, 'Z': 556, '[': 389, '\\': 278, ']': 389, '^': 422, '_': 500,
+    '`': 333, 'a': 500, 'b': 500, 'c': 444, 'd': 500, 'e': 444, 'f': 278, 'g': 500,
+    'h': 500, 'i': 278, 'j': 278, 'k': 444, 'l': 278, 'm': 722, 'n': 500, 'o': 500,
+    'p': 500, 'q': 500, 'r': 389, 's': 389, 't': 278, 'u': 500, 'v': 444, 'w': 667,
+    'x': 444, 'y': 444, 'z': 389, '{': 400, '|': 275, '}': 400, '~': 541,
+}
+
+_TIMES_BOLD = {
+    ' ': 250, '!': 333, '"': 555, '#': 500, '$': 500, '%': 1000, '&': 833, "'": 278,
+    '(': 333, ')': 333, '*': 500, '+': 570, ',': 250, '-': 333, '.': 250, '/': 278,
+    '0': 500, '1': 500, '2': 500, '3': 500, '4': 500, '5': 500, '6': 500, '7': 500,
+    '8': 500, '9': 500, ':': 333, ';': 333, '<': 570, '=': 570, '>': 570, '?': 500,
+    '@': 930, 'A': 722, 'B': 667, 'C': 722, 'D': 722, 'E': 667, 'F': 611, 'G': 778,
+    'H': 778, 'I': 389, 'J': 500, 'K': 778, 'L': 667, 'M': 944, 'N': 722, 'O': 778,
+    'P': 611, 'Q': 778, 'R': 722, 'S': 556, 'T': 667, 'U': 722, 'V': 722, 'W': 1000,
+    'X': 722, 'Y': 722, 'Z': 667, '[': 333, '\\': 278, ']': 333, '^': 581, '_': 500,
+    '`': 333, 'a': 500, 'b': 556, 'c': 444, 'd': 556, 'e': 444, 'f': 333, 'g': 500,
+    'h': 556, 'i': 278, 'j': 333, 'k': 556, 'l': 278, 'm': 833, 'n': 556, 'o': 500,
+    'p': 556, 'q': 556, 'r': 444, 's': 389, 't': 333, 'u': 556, 'v': 500, 'w': 722,
+    'x': 500, 'y': 500, 'z': 444, '{': 394, '|': 220, '}': 394, '~': 520,
+}
+
+_TIMES_BOLD_ITALIC = {
+    ' ': 250, '!': 389, '"': 555, '#': 500, '$': 500, '%': 833, '&': 778, "'": 278,
+    '(': 333, ')': 333, '*': 500, '+': 570, ',': 250, '-': 333, '.': 250, '/': 278,
+    '0': 500, '1': 500, '2': 500, '3': 500, '4': 500, '5': 500, '6': 500, '7': 500,
+    '8': 500, '9': 500, ':': 333, ';': 333, '<': 570, '=': 570, '>': 570, '?': 500,
+    '@': 832, 'A': 667, 'B': 667, 'C': 667, 'D': 722, 'E': 667, 'F': 667, 'G': 722,
+    'H': 778, 'I': 389, 'J': 500, 'K': 667, 'L': 611, 'M': 889, 'N': 722, 'O': 722,
+    'P': 611, 'Q': 722, 'R': 667, 'S': 556, 'T': 611, 'U': 722, 'V': 667, 'W': 889,
+    'X': 667, 'Y': 611, 'Z': 611, '[': 333, '\\': 278, ']': 333, '^': 570, '_': 500,
+    '`': 333, 'a': 500, 'b': 500, 'c': 444, 'd': 500, 'e': 444, 'f': 333, 'g': 500,
+    'h': 556, 'i': 278, 'j': 278, 'k': 500, 'l': 278, 'm': 778, 'n': 556, 'o': 500,
+    'p': 500, 'q': 500, 'r': 389, 's': 389, 't': 278, 'u': 556, 'v': 444, 'w': 667,
+    'x': 500, 'y': 444, 'z': 389, '{': 348, '|': 220, '}': 348, '~': 570,
+}
+
+# Courier and its variants are monospaced: every ASCII glyph is 600/1000 em.
+_COURIER_ADVANCE = 600
+
+# Fallback for characters outside the tables -- anything non-ASCII, so degree
+# signs, Greek and micro. Each family uses its own digit advance: digits are a
+# single uniform width per family and sit mid-range, which makes them a better
+# stand-in than a constant borrowed from Helvetica.
+_DEFAULTS = {
+    "helvetica": 556,
+    "times": 500,
+    "dejavu sans": 636,
+}
+
+# (metric family, bold, italic) -> width table. Oblique/italic keys are present
+# for every family, so a lookup never has to fall back across a style boundary.
+_TABLES = {
+    ("helvetica", False, False): _HELVETICA,
+    ("helvetica", True, False): _HELVETICA_BOLD,
+    ("helvetica", False, True): _HELVETICA_ITALIC,
+    ("helvetica", True, True): _HELVETICA_BOLD_ITALIC,
+    ("times", False, False): _TIMES,
+    ("times", True, False): _TIMES_BOLD,
+    ("times", False, True): _TIMES_ITALIC,
+    ("times", True, True): _TIMES_BOLD_ITALIC,
+    ("dejavu sans", False, False): _DEJAVU_SANS,
+    ("dejavu sans", True, False): _DEJAVU_SANS_BOLD,
+    ("dejavu sans", False, True): _DEJAVU_SANS_ITALIC,
+    ("dejavu sans", True, True): _DEJAVU_SANS_BOLD_ITALIC,
+}
+
+def text_width(text, font_size, family=None, bold=False, italic=False,
+               measure_installed=False):
+    """Estimated rendered width of ``text`` in pixels at ``font_size`` px.
+
+    ``family`` is a CSS font stack; it is resolved to the nearest bundled
+    metric family. ``bold`` / ``italic`` select the matching face, which matters
+    because bold Helvetica runs several percent wider than regular.
+
+    ``measure_installed`` opts out of the bundled tables and measures the font
+    file actually present on this machine, which is more faithful for families
+    plotpress cannot otherwise measure but makes layout depend on what is
+    installed. It silently falls back to the bundled tables when no face
+    resolves. See :mod:`plotpress.fonts.installed`.
+    """
+    if measure_installed:
+        from .installed import installed_table
+
+        table = installed_table(family, bold, italic)
+        if table is not None:
+            default = table.get("0", _DEFAULTS[DEFAULT_METRIC_FAMILY])
+            units = 0
+            for ch in text:
+                units += table.get(ch, default)
+            return units / 1000.0 * font_size
+
+    resolved = resolve_family(family)
+    if resolved == "courier":
+        return len(text) * _COURIER_ADVANCE / 1000.0 * font_size
+    table = _TABLES[(resolved, bool(bold), bool(italic))]
+    default = _DEFAULTS[resolved]
+    units = 0
+    for ch in text:
+        units += table.get(ch, default)
+    return units / 1000.0 * font_size