58.8.1 LaTeX Formula Visuals🔗ℹ

A formula Visual stores an immutable LaTeX mathematical snippet and explicit typesetting data. It implements gen:visual, gen:affine-visual, and gen:opacity-visual. Its raw structure constructor and internal transform and opacity fields are not public.

Formula model values are backend-independent. They do not contain Picts, PDF pages, Poppler values, process handles, or cached TeX results. The built-in adapter calls latex-pict only when a nonempty formula is rendered.

'inline

'display

'display-environment

The 'inline mode uses ordinary inline mathematics. The 'display mode uses display-style mathematics in a tight inline box. The 'display-environment mode uses a real LaTeX display environment, which can include wider horizontal margins.

source is a LaTeX mathematical snippet without surrounding dollar signs, \\( ... \\), or \\[ ... \\] delimiters. The selected mode supplies those delimiters. Formula source may contain carriage returns and newlines. It may also be empty. The constructor copies it into an immutable string.

The mode-to-typesetter mapping is:

The font-size value is measured in local world units before semantic scale is applied. The adapter asks latex-pict to typeset at its natural scale and then maps the selected document base of 10pt, 11pt, or 12pt to the requested world-unit size. When no standard size option is present, 10pt is assumed. Supplying more than one distinct standard size option is an error. Other document-class options and preamble commands may still change the formula’s visible metrics.

The complete visible height and width depend on the formula content. The constructor does not automatically separate two independent formula Visuals, so their rendered boxes can overlap when their anchors are placed too close together. Use visual-layout-box, visual-place-above, visual-place-below, or arrange-visuals-vertically when spacing must follow the actual rendered boxes.

preamble is inserted into the generated LaTeX document. The document-class-options and preview-options lists are passed in stored order. Their strings and preamble are copied into immutable storage. Option order is significant because a LaTeX document class or package may interpret options in order. The adapter passes these values and an extra typesetter scale of one explicitly, so process-wide latex-pict parameters do not silently change a formula Visual.

The alignment arguments select the left, center, or right horizontal point and the top, center, baseline, or bottom vertical point of the untransformed typeset Pict. That point is placed at center. Scale and rotation are then applied around the anchor.

Named parts in a formula-assembly can be styled with formula-style, formula-color, or formula-color-map. This is an assembly-level semantic operation: a bare latex-formula has no part namespace. The Pict and tagged-SVG adapters apply the selected colour at their own rendering boundaries rather than relying on a generic outer recolouring operation.

Generic lines, paths, and ordinary shape outlines use semantic axis ink by default; an explicit "black" remains literal black in every theme. Formula source is different: raw TeX and imported SVG can contain an author’s own black or multicolour paint, and the adapters cannot reliably distinguish that from implicit default ink without altering the artifact. They therefore preserve unstyled formula paint. Use the explicit formula styling operations with theme-foreground when a formula must follow a theme; selected formula parts continue to preserve all other source paint.

Rendering a nonempty formula requires the latex-pict package, a working pdflatex, Poppler, the requested document class, and every package named by the preamble. Model construction, scene sampling, and empty formula rendering do not run TeX. Exact output depends on those external tools and their installed versions. Formula source and preamble are trusted input; this library does not sandbox the TeX process.

58.8.2 Tagged Formula Layouts🔗ℹ

Fragments are deliberately explicit. Animate does not parse arbitrary TeX into tokens, so a fragment must be a valid piece of the complete math expression and must produce visible ink.

Construction runs the external latex and dvisvgm executables once. It wraps every fragment in a dvisvgm SVG group, measures the group, and returns an ordinary formula assembly whose parts render as the resulting SVG fragments. Those SVG fragments are renderer-cached, so sampling or rendering animation frames does not run TeX again. Both executables must be available on PATH when this constructor is called.

All keyword options have the same validation and semantic meaning as for latex-formula, except that Preview-package options and per-fragment anchors are not applicable to a formula whose layout is computed as one unit. The returned assembly can be moved, rotated, scaled, faded, addressed through nested part paths, and used with the normal formula-correspondence operations.

color-map maps declared fragment names to semantic colours. It is applied after the complete TeX layout and SVG crops have been created, so it does not alter kerning, scripts, or measurements. Every key must name a declared fragment.

math-tex records a canonical source string and a conservative token-to-rendered-part source map by default. Use formula-find or formula-source-select to query rendered source material by a literal string, regexp, source span, or occurrence. 'none is the explicit opt-out when no source queries are required. 'declared requires #:parts, a list of named source-part declarations; it maps only those author-declared ranges. The token scanner establishes safe TeX boundaries, not algebraic meaning or a complete TeX parse: user macros, category-code changes, and source that has no visible output may not be selectable.

The generated glyph parts retain the complete author TeX source, but their matching identity is the referenced dvisvgm path outline together with their typesetting options. Consequently, exact unchanged glyphs can match between two separately compiled expressions despite dvisvgm assigning different local font-definition ids on each compilation. Use tagged-formula or math-tex when several glyphs need one semantic identity: glyph leaves are not TeX tokens, a superscript or accent can contain several leaves, and repeated outlines match greedily in source order.

color-map maps generated names such as 'glyph-0 to semantic colours. Generated names are positional, so explicit tagged fragments are usually preferable for durable pedagogical styling.

58.8.3 Making latex-pict Available🔗ℹ

Use the same Racket installation for this library and for latex-pict. For example, to install the catalog package with Racket 9.3.0.2 on macOS:

For a local checkout, link the checkout with that same raco executable:

A one-command alternative is to add the checkout root to PLTCOLLECTS:

The trailing colon is significant. It keeps Racket’s ordinary collection paths after the added checkout. A package linked with one Racket installation is not automatically visible to another installation, so use matching racket and raco executables.