Design: mathtext support

Decision

CurvedText accepts matplotlib mathtext ($...$) inside the label string. The label is tokenized into runs: plain-text runs keep the existing per-character placement exactly, and each math run is rendered by bending the glyph outlines of matplotlib’s own mathtext layout through the curve’s arc-length frame at draw time. There is no new public API: mathtext arrives through the existing text argument, and pos, anchor, offset, and the kwargs pass-through keep their meaning.

Two existing design invariants are preserved and remain load-bearing: all geometry is computed per draw in display space, and children are independent artists that the parent positions before they render (the zorder + 1 ordering).

Why bending, and what was rejected

Mathtext cannot survive the library’s per-character construction: splitting $\propto D$ into characters destroys the expression before matplotlib’s parser sees it. Four approaches were considered.

Unicode substitution. Translate math to Unicode characters (\propto to U+221D) and curve them as plain text. Rejected as a library mechanism: the coverage ceiling is hard (fractions, radicals, sized delimiters, most subscript letters have no Unicode form), mathtext styles variables in italic from the math font so substituted text renders visibly differently, and a library silently rewriting user content violates least surprise. It remains good user-side advice for simple symbols.

One rigid block per math run. Render each $...$ run as a single child Text artist, measured and rotated by the existing draw loop. About thirty lines of change and fully vector, but the run sits on its chord: on a curving section a long expression visibly detaches from the path. Kept as the mental fallback; not chosen.

Rigid per-glyph placement. Decompose the mathtext layout into glyphs and place each rigidly at its own arc position, rotated to the local tangent (the classic text-on-path treatment). Prototyping showed the structural flaw: composite constructs are drawn in two frames. A radical’s check mark is one rigid glyph while its overline is a rule box that must follow the curve; the junction error grows with curvature times the construct’s height, and the tallest constructs (radicals, big delimiters, fractions) are exactly where it shows. Repairing this requires grouping glyphs by parse-tree structure, which the public layout API does not expose. Rejected on complexity.

Bend everything through one frame (chosen). Map every outline control point and every rule box through the same curvilinear map

(u, v) -> curve(u) + (v - datum) * normal(u)

where u is arc length along the label and v is height above the baseline. Seams are impossible by construction because there is only one frame. The single failure mode is smooth distortion that grows with label height times curvature, and it degrades gracefully: prototypes remained readable with the fraction centered on a bend whose radius was comparable to the expression height, and were indistinguishable from straight typesetting at typical label-to-curvature ratios.

Mixed-string semantics

Plain runs and math runs deliberately use different placement at different scales of rigidity:

  • Plain characters stay rigid, each rotated to the tangent at its own arc midpoint. This is unchanged from the library without mathtext.

  • Math runs bend continuously through the frame.

The two regimes are consistent rather than conflicting: per-character rigid placement is the glyph-scale discretization of the same frame, so on a straight section they coincide exactly, and within the width of one glyph the difference is far below a pixel at any curvature where text is readable. Keeping plain runs as real Text artists also preserves font rendering (hinting, fallback) for the common case.

Architecture

All code lives in src/curved_text/_core.py.

  • _Run (NamedTuple: is_math, text) and _split_runs(text): a pure tokenizer mirroring matplotlib’s own rules. An odd count of unescaped $ means the whole string is one plain run; \$ in plain runs unescapes to $; empty plain runs between adjacent math runs are dropped; math runs keep their delimiters so they re-parse as written.

  • _CurveFrame: the display-space curve geometry (projected points, cumulative arc length) with a vectorized point-and-tangent lookup. It replaces the _point closure and keeps its clip-then-extrapolate semantics, so labels overrunning a curve end still ride the straight tangent extension. Shared by the per-character walk and by math runs.

  • _MathRun(matplotlib.text.Text): one child artist per math run. Subclassing Text inherits kwargs handling identically to sibling characters, and get_window_extent already measures mathtext, so the parent’s measurement loop has no special case. The subclass overrides draw:

    • _glyph_layout() calls TextToPath.get_glyphs_mathtext (public API) and memoizes one entry keyed on text and font properties. Glyph units are resolution independent; only the per-draw pixel scale varies.

    • _layout_path(renderer) builds the bent compound path in display pixels: outline vertices are scaled and offset to expression coordinates, straight segments longer than a few display pixels along the curve direction are subdivided (rule boxes such as fraction bars are the long ones), bezier control points are mapped directly (the same approximation vector editors use for path bending), and whitespace glyphs with empty outlines are skipped.

    • draw(renderer) fills the compound path with one renderer.draw_path call using the artist’s color and alpha, with clipping set through public GraphicsContext methods. With no frame assigned it draws nothing.

    • _set_frame(frame, s_left, offset_px) is the per-draw handoff the parent calls; it mutates the run and returns None.

  • CurvedText builds children from _split_runs (honoring parse_math; disabling it restores per-character behavior exactly), and its draw gains one branch in the cursor walk: math runs receive the frame instead of a position and rotation. The child list is named _segments, since elements are no longer all characters.

Vertical datum

A math run rides the curve on the surrounding text’s x-height line: datum = x_height / 2 above the baseline, measured from a plain lowercase reference at the run’s font size. This keeps the run’s main symbols level with neighbouring plain characters in a mixed label.

The earlier choice – the run’s own layout box center (height / 2 - depth) – was wrong for mixed labels: a superscript or tall delimiter inflates the box, so centering on it dropped the body below the plain characters. The x-height line is immune, because it does not depend on the run’s own extent. Pinned by two tests: a lowercase math symbol centers where the plain character does under va="center", and an exponent extends the run upward without moving its body.

Path effects

Keyword arguments reach every child, so path_effects flow to the per-character Text glyphs and to each _MathRun. Plain glyphs apply them through the base Text.draw; _MathRun.draw draws its own bent path, so it wraps the renderer in a PathEffectRenderer when effects are set. The effect strokes the bent outline, so a white withStroke casing follows the curved text and clears the lines a label crosses. This is the matplotlib-native idiom for a light, glyph-hugging casing.

Casing (box)

A path_effects stroke cannot give solid coverage under plain text: each character is its own artist that strokes then fills, so a wide neighbor stroke overwrites the previous glyph’s fill. The box parameter solves the full-coverage case with a different mechanism – a single Line2D casing following the offset curve across the label’s span, its linewidth set to the tallest glyph’s height, drawn as one fill so nothing cannibalizes. It is a child artist positioned per draw in CurvedText.draw, like the glyphs.

Layering is by zorder, applied once in __init__ and maintained by set_zorder: the container at z, the casing at z + 0.5, the glyphs at z + 1. The casing must sit above the container because the container’s draw is what positions it – a lower zorder would draw the casing before its geometry is set, leaving it stale or empty. It must sit below the glyphs so the text reads on top.

Behavior rules

  • parse_math=False (kwarg or rcParam) disables splitting entirely.

  • A string with an odd count of unescaped $ renders literally, character by character, as matplotlib itself would.

  • usetex is unsupported and documented as such. The run architecture accepts a TeX backend later through TextToPath.get_glyphs_tex without redesign.

  • Tall constructs degrade by vertical compression on the inside of bends; the docstring states this and leaves label-size-to-curvature judgment to the user.

Test pins

Beyond ports of the existing behavioral suite (ordering, offset, dpi invariance, overrun, idempotent redraw, degenerate curve, zorder, remove, fontsize pass-through), two tests carry the design:

  • Straight-line equivalence: the bent path of a math run on a straight horizontal curve matches matplotlib’s own rendering of the same string as a rigid Text. Pins datum, width, scale, and dpi handling at once.

  • Anti-rigidity: a math label spanning a wide circular arc keeps every path vertex within radius +/- half label height, a bound chord placement would violate. Pins that bending actually happens.

Deferred

  • Routing plain runs through the same outline pipeline would fix the per-character kerning loss but changes the rendering of every existing label; separate decision, tracked as a follow-up issue.

  • usetex support via get_glyphs_tex.

Ecosystem constraints

curved-text is listed in matplotlib’s third-party package registry (mpl-third-party). The implementation therefore uses public matplotlib API only, verifies the declared matplotlib floor in CI, and adds a non-blocking CI job against matplotlib pre-releases so upstream breakage surfaces here before users meet it.