LayMeshDocs
中文

Strings and mathematical formulas#

Purpose and concepts#

formula accepts LaTeX without dollar delimiters. Raw strings preserve backslashes. inline fits text lines; display uses standalone layout. math_font=ratex_katex is a predefined string alias.

Minimal complete example#

Run this file directly with laymesh validate or laymesh render; it contains its own canvas and required definitions.

Full source
formula.lay
# Minimal complete example: formulapage=canvas(size=(100mm,75mm),background="#ffffff")page.add(formula(r"E=mc^2",style=display,font_size=16pt,math_font=ratex_katex),offset=(8mm,8mm))

Preview

Background
Preparing preview…
Formula
Preparing preview…
Total —
Details

Not run yet

Measured in this browser; excludes debounce.

Edits stay on this page
Dependencies
  • examples/manual/formula.lay

Composition#

text(spans=[...]) combines spans and formulas. Embedded $...$ in ordinary text differs from explicit formula input; use raw/formatted strings deliberately when backslashes or substitutions are involved.

Preview

Background
Preparing preview…
Display formula
Preparing preview…
Total —
Details

Not run yet

Measured in this browser; excludes debounce.

Edits stay on this page
Dependencies
  • examples/gallery/typography/display-formula.lay

Common errors and limits#

The math engine rejects external resources, require and custom macros. Legacy mathjax font names warn and map to the current default. Formula colors support the same spaces as ordinary text.

Individual functions#

formula#

Create formula material from LaTeX without dollar delimiters, or a run in text. Raw strings preserve backslashes; style selects inline/display layout.

Returns: material

Required inputs: source.

Minimal complete source · Composition source · All parameters

Detailed behavior and further examples#

Ordinary and raw text#

lay
page = canvas(size=(150, 100))page.add(text("Energy $E=mc^2$", font_size=10), offset=(5, 5))page.add(text(r"Literal $E=mc^2$"), offset=(5, 20))page.add(formula(r"\frac{a}{b}", font_size=12), offset=(5, 35))

Write LaTeX backslashes directly inside math, for example axis(label="$\frac{\Delta E}{k_B T}$"). Single, double and triple-quoted multiline strings are supported. The r prefix preserves raw text and disables automatic math; explicit formula(r"…") still renders math. Resource paths never undergo math detection.

Interpolation#

lay
score = 0.975label = f"Fit: $R^2={score:.3f}$"literal = rf"Score {score:.2%}; literal $R^2$"

Braces accept DSL expressions. Numeric formatting supports common f, e, g, %, d, precision, signs and alignment. {{ and }} produce literal braces. rf interpolates without automatic math. Interpolation executes neither Python nor JavaScript.

Mixed content and inheritance#

In text(spans=[span("Ratio: "), formula(r"\frac{a}{b}")], font_size=12, color="#245447"), a formula without an explicit size or color inherits those of its text. An explicit span font list replaces its parent's list. By default, math uses the KaTeX formula fonts embedded by RaTeX; font_family controls ordinary text.

SVG/PDF formulas are vectors; SVG metadata retains LaTeX source. Formula errors carry source locations. RaTeX limitations apply: custom macro definitions and external-resource commands are unavailable. Python {{name}} binding applies only outside DSL strings and comments, so it does not replace these f-string contents.

Fonts · Parameters · Editors

workflow#

Complete sources and executable verification fixtures for this workflow are listed in the feature coverage map. Follow this page’s input conditions and limits when composing features.

OpenType math fonts (experimental)#

math_font also accepts an installed OpenType math font name or a font file path:

lay
page=canvas(size=(100mm,50mm))page.add(formula(r"\frac{a}{b}+\bm{\alpha}",math_font="XITS Math",font_size=16pt))

For reproducibility, use a file such as math_font="./fonts/XITSMath-Regular.otf". Paths belong to the defining module or LCSS stylesheet. The property inherits through canvas, text, span, and plot styles, including automatic $...$ math. Browser hosts must load the font bytes first. The backend reads glyph metrics, math constants, italic corrections, and stretch constructions from the selected font and exports vector outlines.

The current implementation covers mhchem ce/pu, prooftree, labelled arrows, middle, aligned equations/tags, array rules, overlap, braces, cancellation, and the ordinary math constructions. Historical verification recorded 15,448 layout checks over the fixed RaTeX 0.1.14 corpus and domain cases; all 91 chemistry, 22 physics, and 38 proof-tree examples render with four fonts and both styles. Parser/policy rejections are recorded separately. Missing glyphs use vector boxes and emit W_FONT, preserving the rest of the formula. Unavailable fonts or missing MATH tables return E_MATH_FONT; selected math faces never silently substitute another font. mathcal and mathscr currently share the Unicode script alphabet. The standalone XITS bold face has incomplete stretch coverage; regular XITS Math supports mathbf, boldsymbol, and bm. Horizontal arrows without valid assemblies extend the shaft region of the selected font's native outline; other finite constructions use their largest native variant. Use raw DSL strings for LaTeX, especially when chemistry contains embedded $...$ math.

Inner math alphabet commands override outer ones: \mathbf{\mathcal A} selects script A, while \mathcal{\mathbf A} selects bold roman A. Use \mathbf{A1} for bold letters/digits and \bm{\alpha x} for bold italic symbols. Script shapes and stroke weights vary with the selected font.

OpenType chemical bonds ~, ~-, ~--, ~=, and -~- use a compound construction based on the selected font's minus outline. Solid and dashed rows share their ink endpoints and thickness, and inherit the surrounding math size, script style and color. The geometry tests check endpoints directly, including bonds inside superscripts, nested subscripts and fractions.

See the editable comparison and verification instructions. The default remains ratex-katex; legacy mathjax-* names retain their compatibility mapping.

Formula text uses font_family; mathematical symbols use math_font:

lay
page=canvas(size=(140mm,50mm),math_font="XITS Math",font_family=["Noto Serif","Noto Serif CJK SC"])page.add(formula(r"\text{你好,世界!}\quad E=mc^2",font_size=16pt))

math_text_fallback=true is the default. Text in \text, scripts, chemical arrow annotations and proof trees is selected, shaped and measured before math placement. Runs retain ligatures, combining marks and bidirectional ordering, and export as vector outlines. \textbf and \textit select actual body-font styles; absent styles warn, and missing glyphs use vector boxes with W_FONT. Mathematical bold continues to use \mathbf / \bm.

Explicit text font lists are ordered and do not add system fonts implicitly. Paths are supported; native hosts can also use system families, while browser hosts must supply font files first. math_text_fallback=false disables body text fallback for math-font coverage checks. Every backend uses the same vector box for missing glyphs, including when an explicit text font list is exhausted. The box participates in layout and scales with scripts; W_FONT identifies the missing Unicode codepoints. Available glyphs and formula structure remain visible. Color bitmap emoji without exportable outlines also use boxes.