Skip to main content

cellix_doc/
math.rs

1//! Typeset math, from pure Rust and fonts in the binary, so it works over SSH on a server
2//! with no TeX. A formula that won't parse is an error here and its source on the page.
3
4use std::cell::OnceCell;
5use std::collections::hash_map::DefaultHasher;
6use std::hash::{Hash, Hasher};
7use std::sync::Arc;
8
9use latex_rust::{
10    Dim, MathBox, MathFont, MathStyle, PngOptions, SvgOptions, latex_to_svg,
11    layout_with_em_size_pt, parse, render_png,
12};
13
14/// A typeset formula as coverage, so it can take the colour of the text around it.
15#[derive(Clone, Debug, PartialEq, Eq)]
16pub struct Formula {
17    pub id: u64,
18    pub width: u32,
19    pub height: u32,
20    /// Rows of pixels above the baseline.
21    pub baseline: u32,
22    pub alpha: Arc<Vec<u8>>,
23}
24
25thread_local! {
26    static FONT: OnceCell<Option<MathFont>> = const { OnceCell::new() };
27}
28
29fn with_font<T>(run: impl FnOnce(&MathFont) -> Result<T, String>) -> Result<T, String> {
30    FONT.with(|cell| {
31        let font = cell.get_or_init(|| MathFont::stix_two_math().ok());
32        run(font.as_ref().ok_or("the math font didn't load")?)
33    })
34}
35
36/// Environments that only number or wrap math, which the page has no use for.
37const WRAPPERS: [&str; 4] = ["equation", "equation*", "displaymath", "math"];
38
39/// Commands the engine doesn't have, as what it does. Longest names first where one is the
40/// start of another. The page is a preview, and a near match beats losing a whole display.
41const SUBSTITUTES: [(&str, &str); 24] = [
42    // In `\operatorname` a thin space prints as a comma, so these stay in math.
43    ("\\operatorname*{", "\\mathrm{"),
44    ("\\operatorname{arg\\,", "\\mathrm{arg\\,"),
45    ("\\argmin", "\\mathrm{arg\\,min}"),
46    ("\\argmax", "\\mathrm{arg\\,max}"),
47    ("\\bm{", "\\mathbf{"),
48    ("\\boldsymbol{", "\\mathbf{"),
49    ("\\mathds{", "\\mathbb{"),
50    ("\\coloneqq", ":="),
51    ("\\eqqcolon", "=:"),
52    ("\\varinjlim", "\\lim"),
53    ("\\varprojlim", "\\lim"),
54    ("\\xmapsto", "\\xrightarrow"),
55    ("\\llbracket", "[\\!["),
56    ("\\rrbracket", "]\\!]"),
57    ("\\bmod", "\\operatorname{mod}"),
58    ("\\qed", "\\square"),
59    ("\\middle", ""),
60    ("\\displaystyle", ""),
61    ("\\textstyle", ""),
62    ("\\nonumber", ""),
63    ("\\notag", ""),
64    ("{dcases}", "{cases}"),
65    ("{rcases}", "{cases}"),
66    ("{smallmatrix}", "{matrix}"),
67];
68
69/// Something unseen that reaches a script's depth below a row's own limits.
70const ROW_DEPTH: &str = "\\vphantom{\\underset{\\underset{x}{x}}{X}}";
71
72/// Operators whose limits stand under them in a display. The engine only does this for `\lim`.
73const UNDER: [&str; 8] = [
74    "\\max",
75    "\\min",
76    "\\sup",
77    "\\inf",
78    "\\limsup",
79    "\\liminf",
80    "\\mathrm{arg\\,min}",
81    "\\mathrm{arg\\,max}",
82];
83
84/// A script at the start of `text`: its text, and how far it runs.
85fn script(text: &str) -> Option<(&str, usize)> {
86    let mut chars = text.char_indices();
87    match chars.next()?.1 {
88        '{' => {
89            let mut depth = 0;
90            for (at, c) in text.char_indices() {
91                depth += match c {
92                    '{' => 1,
93                    '}' => -1,
94                    _ => 0,
95                };
96                if depth == 0 {
97                    return Some((&text[1..at], at + 1));
98                }
99            }
100            None
101        }
102        '\\' => {
103            let end = chars
104                .find(|(_, c)| !c.is_ascii_alphabetic())
105                .map_or(text.len(), |(at, _)| at);
106            Some((&text[..end], end))
107        }
108        c => Some((&text[..c.len_utf8()], c.len_utf8())),
109    }
110}
111
112/// Big operators, whose limits the engine only stacks by itself in a display.
113const BIG: [&str; 7] = [
114    "\\sum", "\\prod", "\\coprod", "\\int", "\\bigcup", "\\bigcap", "\\oint",
115];
116
117/// Sets `\sum\limits_{a}^{b}` as a stack, since the engine ignores the word for these.
118fn limits_asked_for(text: &str) -> String {
119    let mut out = String::with_capacity(text.len());
120    let mut rest = text;
121    while let Some(at) = rest.find('\\') {
122        out.push_str(&rest[..at]);
123        rest = &rest[at..];
124        let asked = BIG.iter().find_map(|name| {
125            let after = rest.strip_prefix(*name)?.trim_start();
126            Some((*name, after.strip_prefix("\\limits")?))
127        });
128        let Some((name, mut tail)) = asked else {
129            out.push('\\');
130            rest = &rest[1..];
131            continue;
132        };
133        let (mut under, mut over) = (None, None);
134        for _ in 0..2 {
135            let trimmed = tail.trim_start();
136            let slot = match trimmed.chars().next() {
137                Some('_') => &mut under,
138                Some('^') => &mut over,
139                _ => break,
140            };
141            let body = trimmed[1..].trim_start();
142            let Some((text, used)) = script(body) else {
143                break;
144            };
145            *slot = Some(text);
146            tail = &body[used..];
147        }
148        let mut stack = name.to_string();
149        if let Some(over) = over {
150            stack = format!("\\overset{{{over}}}{{{stack}}}");
151        }
152        if let Some(under) = under {
153            stack = format!("\\underset{{{under}}}{{{stack}}}");
154        }
155        out.push_str(&stack);
156        rest = tail;
157    }
158    out.push_str(rest);
159    out
160}
161
162/// Sets `\max_{x}` as a stack, so its limit stands under it the way TeX puts it.
163fn limits_under(text: &str) -> String {
164    let mut out = String::with_capacity(text.len());
165    let mut rest = text;
166    while let Some(at) = rest.find('\\') {
167        out.push_str(&rest[..at]);
168        rest = &rest[at..];
169        let found = UNDER.iter().find(|name| {
170            rest.strip_prefix(**name)
171                .is_some_and(|after| !after.starts_with(|c: char| c.is_ascii_alphabetic()))
172        });
173        let stacked = found.and_then(|name| {
174            let after = rest[name.len()..].trim_start();
175            let after = after.strip_prefix("\\limits").unwrap_or(after).trim_start();
176            let (under, used) = script(after.strip_prefix('_')?.trim_start())?;
177            let spaces = after.len() - 1 - after[1..].trim_start().len();
178            let tail = &after[1 + spaces + used..];
179            Some((format!("\\underset{{{under}}}{{{name}}}"), tail))
180        });
181        match stacked {
182            Some((stack, tail)) => {
183                out.push_str(&stack);
184                rest = tail;
185            }
186            None => {
187                let step = found.map_or(1, |name| name.len());
188                out.push_str(&rest[..step]);
189                rest = &rest[step..];
190            }
191        }
192    }
193    out.push_str(rest);
194    out
195}
196
197/// Takes `\name{...}` out of `text`, with `keep` deciding what stands in its place.
198fn strip_command(text: &mut String, name: &str, keep: bool) {
199    let open = format!("{name}{{");
200    while let Some(at) = text.find(&open) {
201        let start = at + open.len();
202        let mut depth = 1;
203        let mut end = None;
204        for (i, c) in text[start..].char_indices() {
205            match c {
206                '{' => depth += 1,
207                '}' => depth -= 1,
208                _ => {}
209            }
210            if depth == 0 {
211                end = Some(start + i);
212                break;
213            }
214        }
215        let Some(end) = end else {
216            return;
217        };
218        let inner = text[start..end].to_string();
219        text.replace_range(at..=end, if keep { &inner } else { "" });
220    }
221}
222
223/// What the math engine reads: `\label` has no picture, and `equation` only numbers.
224fn prepared(source: &str, display: bool) -> String {
225    let mut text = source.trim().to_string();
226    for name in WRAPPERS {
227        let (open, close) = (format!("\\begin{{{name}}}"), format!("\\end{{{name}}}"));
228        if let Some(inner) = text
229            .strip_prefix(&open)
230            .and_then(|t| t.strip_suffix(&close))
231        {
232            text = inner.trim().to_string();
233        }
234    }
235    // Numbers belong in the margin, where the page puts them.
236    strip_command(&mut text, "\\label", false);
237    strip_command(&mut text, "\\tag", false);
238    strip_command(&mut text, "\\tag*", false);
239    strip_command(&mut text, "\\smash", true);
240    strip_command(&mut text, "\\mathop", true);
241    strip_command(&mut text, "\\mathrel", true);
242    strip_command(&mut text, "\\mathbin", true);
243    for (from, to) in SUBSTITUTES {
244        text = text.replace(from, to);
245    }
246    // Numbered environments number themselves, and restart in every block, so they all go
247    // through the one that doesn't.
248    for name in [
249        "align", "gather", "multline", "alignat", "flalign", "eqnarray",
250    ] {
251        text = text
252            .replace(&format!("{{{name}*}}"), "{aligned}")
253            .replace(&format!("{{{name}}}"), "{aligned}");
254    }
255    let text = limits_asked_for(&text.replace("{gathered}", "{aligned}"));
256    let text = if display { limits_under(&text) } else { text };
257    if text.contains("{aligned}") {
258        roomy_rows(&text)
259    } else {
260        text
261    }
262}
263
264/// Gives a row with limits under it more depth, so they clear the next row's. The engine has
265/// no `\\\\[gap]`, but a row is as deep as whatever's in it, seen or not.
266fn roomy_rows(text: &str) -> String {
267    let rows: Vec<&str> = text.split("\\\\").collect();
268    let last = rows.len().saturating_sub(1);
269    let spaced = rows.iter().enumerate().map(|(index, row)| {
270        if index < last && row.contains("\\underset") {
271            format!("{row}{ROW_DEPTH}")
272        } else {
273            (*row).to_string()
274        }
275    });
276    spaced.collect::<Vec<_>>().join("\\\\")
277}
278
279/// Where each row of a display stands in its picture, as shares of its height, from what
280/// each row measures alone. None if one of them can't be set by itself.
281pub fn row_centres(rows: &[String], em: u32) -> Option<Vec<f32>> {
282    let mut heights = Vec::with_capacity(rows.len());
283    for row in rows {
284        let mut text = row.replace('&', " ");
285        for word in [
286            "\\begin{align*}",
287            "\\begin{align}",
288            "\\end{align*}",
289            "\\end{align}",
290        ] {
291            text = text.replace(word, " ");
292        }
293        for word in [
294            "\\begin{gather*}",
295            "\\begin{gather}",
296            "\\end{gather*}",
297            "\\end{gather}",
298        ] {
299            text = text.replace(word, " ");
300        }
301        heights.push(render(&text, true, em).ok()?.height as f32);
302    }
303    let total: f32 = heights.iter().sum();
304    let mut done = 0.0;
305    let centres = heights.iter().map(|height| {
306        let centre = (done + height / 2.0) / total.max(1.0);
307        done += height;
308        centre
309    });
310    Some(centres.collect())
311}
312
313fn pixels(dim: &Dim, em: u32) -> f64 {
314    let (top, bottom) = dim.as_ratio().unwrap_or((0, 1));
315    top as f64 / bottom.max(1) as f64 * em as f64
316}
317
318fn decode(bytes: &[u8]) -> Result<(u32, u32, Vec<u8>), String> {
319    let mut reader = png::Decoder::new(std::io::Cursor::new(bytes))
320        .read_info()
321        .map_err(|e| e.to_string())?;
322    let size = reader
323        .output_buffer_size()
324        .ok_or("the image is too large")?;
325    let mut buffer = vec![0; size];
326    let info = reader.next_frame(&mut buffer).map_err(|e| e.to_string())?;
327    let channels = info.color_type.samples();
328    let alpha = buffer[..info.buffer_size()]
329        .chunks_exact(channels)
330        .map(|p| p[channels - 1])
331        .collect();
332    Ok((info.width, info.height, alpha))
333}
334
335/// Typesets a formula with `em` pixels to the em.
336pub fn render(source: &str, display: bool, em: u32) -> Result<Formula, String> {
337    let text = prepared(source, display);
338    if text.is_empty() {
339        return Err("empty formula".to_string());
340    }
341    let ast = parse(&text).map_err(|e| e.to_string())?;
342    with_font(|font| {
343        let style = if display {
344            MathStyle::Display
345        } else {
346            MathStyle::Text
347        };
348        let size = Dim::from_i64(i64::from(em));
349        let tree: MathBox =
350            layout_with_em_size_pt(&ast, font, style, &size).map_err(|e| e.to_string())?;
351        // At 72 dpi a point is a pixel, so the em size is exact.
352        let mut options = PngOptions::new();
353        options.font_size_pt = size;
354        options.dpi = Dim::from_i64(72);
355        let bytes = render_png(&tree, font, &options).map_err(|e| e.to_string())?;
356        let (width, height, alpha) = decode(&bytes)?;
357        let mut hasher = DefaultHasher::new();
358        (&text, display, em).hash(&mut hasher);
359        Ok(Formula {
360            id: hasher.finish(),
361            width,
362            height,
363            baseline: pixels(&tree.height, em).round() as u32,
364            alpha: Arc::new(alpha),
365        })
366    })
367}
368
369/// A formula as self-contained SVG, for pages that leave Cellix.
370pub fn svg(source: &str, display: bool) -> Result<String, String> {
371    let text = prepared(source, display);
372    with_font(|font| {
373        let mut options = SvgOptions::new();
374        options.display = display;
375        let svg = latex_to_svg(&text, font, &options).map_err(|e| e.to_string())?;
376        // The XML header would land in the middle of a page.
377        Ok(svg
378            .find("<svg")
379            .map_or(svg.clone(), |at| svg[at..].to_string()))
380    })
381}
382
383#[cfg(test)]
384mod tests {
385    use super::*;
386
387    #[test]
388    fn limits_stand_under_operators_in_a_display() {
389        let beside = render(r"\max_{x \in X} f", false, 30).unwrap();
390        let under = render(r"\max_{x \in X} f", true, 30).unwrap();
391        assert!(under.height > beside.height + 10);
392        let wide = render(r"\argmin_{\theta} f + \min_x g + \max^2", true, 30).unwrap();
393        assert!(wide.height > beside.height + 10);
394        assert_eq!(
395            prepared(r"\max_{x}^2 \maximum", true),
396            r"\underset{x}{\max}^2 \maximum"
397        );
398        assert_eq!(prepared(r"\min\limits_a b", true), r"\underset{a}{\min} b");
399    }
400
401    #[test]
402    fn a_thin_space_in_an_operators_name_is_not_a_comma() {
403        let text = prepared(r"\operatorname{arg\,min} + \operatorname*{arg\,max}", false);
404        assert!(!text.contains("operatorname"), "{text}");
405    }
406
407    #[test]
408    fn rows_of_a_display_keep_clear_of_each_other() {
409        let plain = r"\begin{aligned} a &= \mathrm{x}_{y} \\ c &= d \end{aligned}";
410        let under = r"\begin{aligned} a &= \max_{y} \\ c &= d \end{aligned}";
411        assert!(!prepared(plain, true).contains("vphantom"));
412        assert!(prepared(under, true).contains("vphantom"));
413        let (low, high) = (
414            render(plain, true, 30).unwrap(),
415            render(under, true, 30).unwrap(),
416        );
417        assert!(high.height > low.height + 10);
418    }
419
420    #[test]
421    fn a_tall_row_takes_its_share_of_the_picture() {
422        let rows = vec![
423            r"\begin{align} a &= b".to_string(),
424            r"\sum_{i=1}^{n} c \end{align}".to_string(),
425        ];
426        let centres = row_centres(&rows, 30).unwrap();
427        assert!(centres[0] < 0.3, "{centres:?}");
428        assert!(centres[1] > 0.5, "{centres:?}");
429    }
430
431    #[test]
432    fn limits_asked_for_in_running_text_stand_over_and_under() {
433        assert_eq!(
434            prepared(r"\sum\limits_{i=1}^{n} x", false),
435            r"\underset{i=1}{\overset{n}{\sum}} x"
436        );
437        assert_eq!(
438            prepared(r"\prod\limits^2_a", false),
439            r"\underset{a}{\overset{2}{\prod}}"
440        );
441        let beside = render(r"\sum_{i=1}^n x", false, 30).unwrap();
442        let stacked = render(r"\sum\limits_{i=1}^n x", false, 30).unwrap();
443        assert!(stacked.height > beside.height + 8);
444    }
445
446    #[test]
447    fn asking_for_limits_never_breaks_a_formula() {
448        assert!(render(r"\sum\limits_{i=1}^n x", false, 30).is_ok());
449        assert!(render(r"\sum\nolimits_{i=1}^n x", true, 30).is_ok());
450    }
451
452    #[test]
453    fn a_formula_comes_out_as_real_coverage() {
454        let formula = render(r"\frac{a}{b} + \sum_{i=1}^{n} x_i^2", false, 22).unwrap();
455        assert!(formula.width > 22 && formula.height > 10);
456        assert_eq!(
457            formula.alpha.len(),
458            (formula.width * formula.height) as usize
459        );
460        assert!(formula.alpha.iter().any(|a| *a > 200), "ink");
461        assert!(formula.alpha.contains(&0), "and paper");
462        assert!(formula.baseline > 0 && formula.baseline < formula.height);
463    }
464
465    #[test]
466    fn display_math_stands_taller_than_inline() {
467        let text = r"\sum_{i=1}^{n} i";
468        let inline = render(text, false, 22).unwrap();
469        let display = render(text, true, 22).unwrap();
470        assert!(display.height > inline.height);
471    }
472
473    #[test]
474    fn scientific_environments_typeset() {
475        for source in [
476            r"\begin{align} a &= b \\ c &= d \end{align}",
477            r"\begin{equation} E = mc^2 \label{eq:e} \end{equation}",
478            r"\begin{pmatrix} 1 & 0 \\ 0 & 1 \end{pmatrix}",
479            r"f(x) = \begin{cases} 0 & x < 0 \\ 1 & x \ge 0 \end{cases}",
480            r"\int_0^\infty e^{-x^2}\,dx = \frac{\sqrt{\pi}}{2}",
481            r"\nabla \cdot \mathbf{E} = \frac{\rho}{\varepsilon_0}",
482        ] {
483            render(source, true, 22).unwrap_or_else(|e| panic!("{source}: {e}"));
484        }
485    }
486
487    #[test]
488    fn what_the_engine_lacks_has_a_stand_in() {
489        for source in [
490            r"\operatorname*{arg\,max}_x f(x)",
491            r"\argmin_{\theta} \mathcal{L}(\theta)",
492            r"\bm{x}^\top \mathds{1}",
493            r"a \coloneqq b",
494            r"\begin{dcases} a \\\\ b \end{dcases}",
495            r"x \bmod y",
496            r"\begin{align} a &= b \tag{2} \\\\ c &= d \notag \end{align}",
497        ] {
498            render(source, true, 22).unwrap_or_else(|e| panic!("{source}: {e}"));
499        }
500    }
501
502    #[test]
503    fn numbers_are_left_to_the_margin() {
504        assert_eq!(prepared(r"E = mc^2 \tag{2}", true).trim(), "E = mc^2");
505        assert!(prepared(r"\begin{align} a \end{align}", true).contains("{aligned}"));
506    }
507
508    #[test]
509    fn nonsense_is_an_error_not_a_picture() {
510        assert!(render(r"\frac{", false, 22).is_err());
511        assert!(render("  ", false, 22).is_err());
512    }
513
514    #[test]
515    fn svg_stands_alone() {
516        assert!(svg("x^2", false).unwrap().starts_with("<svg"));
517    }
518}