Skip to content

armgit / manim

Public Imported from GitHub
0

A community-maintained Python framework for creating mathematical animations.

Preserve layout of MathTypst capture groups (#4960)

Benjamin Hackleb56221f9629
diff --git a/manim/mobject/text/typst_mobject.py b/manim/mobject/text/typst_mobject.py
index b2e5aeb79..3220d6548 100644
--- a/manim/mobject/text/typst_mobject.py
+++ b/manim/mobject/text/typst_mobject.py
@@ -123,6 +123,7 @@ __all__ = [
]
import re
+from collections.abc import Iterator
from pathlib import Path
from typing import Any, Self, cast
from xml.etree import ElementTree as ET
@@ -137,8 +138,6 @@ from manim.mobject.types.vectorized_mobject import VGroup, VMobject
from manim.utils.color import BLACK, ParsableManimColor
from manim.utils.typst_file_writing import typst_to_svg_file
-_MANIMGRP_PREAMBLE = "#let manimgrp(lbl, body) = [#box(body) #label(lbl)]"
-
# Pattern for the label part of {{ content : label }}.
# The label must be a valid Typst label identifier.
_LABEL_RE = re.compile(r"^(.*)\s*:\s*([a-zA-Z_][a-zA-Z0-9_-]*)\s*$", re.DOTALL)
@@ -148,6 +147,128 @@ _DUPLICATE_LABEL_SUFFIX = "__manim_typst_dup_"
# underlines, etc.) visually match the weight of TeX-derived geometry more
# closely after import into Manim's pixel-based stroke model.
_TYPST_SVG_STROKE_WIDTH_SCALE = 0.5
+_SVG_LEAF_TAGS = {
+ "circle",
+ "ellipse",
+ "image",
+ "line",
+ "path",
+ "polygon",
+ "polyline",
+ "rect",
+ "text",
+ "use",
+}
+
+
+def _manimgrp_preamble(target: str | None) -> str:
+ """Return a layout-transparent Typst capture helper.
+
+ The final render uses ``none`` as the target and therefore returns every
+ group body unchanged. Probe renders target one label at a time and use
+ Typst's layout-preserving ``hide`` element to remove just that group's SVG
+ leaves.
+ """
+ target_value = "none" if target is None else f'"{target}"'
+ return (
+ f"#let manimgrp(lbl, body) = if lbl == {target_value} "
+ "{ hide(body) } else { body }"
+ )
+
+
+def _svg_tag_name(element: ET.Element) -> str:
+ """Return an XML element's local tag name."""
+ if not isinstance(element.tag, str):
+ return ""
+ return element.tag.rsplit("}", 1)[-1]
+
+
+def _iter_svg_leaves(
+ parent: ET.Element,
+ transform: se.Matrix | None = None,
+ inside_defs: bool = False,
+) -> Iterator[tuple[ET.Element, int, ET.Element, se.Matrix]]:
+ """Yield rendered SVG leaves with their parent and effective transform."""
+ if transform is None:
+ transform = se.Matrix()
+
+ for index, element in enumerate(parent):
+ tag = _svg_tag_name(element)
+ element_inside_defs = inside_defs or tag == "defs"
+ local_transform = (
+ se.Matrix(element.get("transform"))
+ if element.get("transform") is not None
+ else se.Matrix()
+ )
+ effective_transform = transform * local_transform
+
+ if not element_inside_defs and tag in _SVG_LEAF_TAGS:
+ yield parent, index, element, effective_transform
+
+ yield from _iter_svg_leaves(
+ element,
+ effective_transform,
+ element_inside_defs,
+ )
+
+
+def _svg_leaf_signatures(svg_file: Path) -> list[tuple[Any, ...]]:
+ """Return stable signatures for rendered SVG leaves in drawing order."""
+ root = ET.parse(svg_file).getroot()
+ signatures: list[tuple[Any, ...]] = []
+
+ for _, _, element, transform in _iter_svg_leaves(root):
+ attributes = tuple(
+ sorted(
+ (key, value)
+ for key, value in element.attrib.items()
+ if key != "transform"
+ )
+ )
+ matrix = tuple(
+ round(value, 12)
+ for value in (
+ transform.a,
+ transform.b,
+ transform.c,
+ transform.d,
+ transform.e,
+ transform.f,
+ )
+ )
+ text = tuple(element.itertext())
+ signatures.append((_svg_tag_name(element), attributes, text, matrix))
+
+ return signatures
+
+
+def _hidden_leaf_indices(
+ visible: list[tuple[Any, ...]],
+ probe: list[tuple[Any, ...]],
+) -> set[int]:
+ """Return visible leaf indices removed from a layout-preserving probe.
+
+ A valid ``hide`` probe is the final SVG leaf sequence with zero or more
+ entries deleted. Matching the probe as a subsequence handles repeated
+ glyphs by retaining their drawing order and effective positions.
+ """
+ hidden: set[int] = set()
+ probe_index = 0
+
+ for visible_index, signature in enumerate(visible):
+ if probe_index < len(probe) and signature == probe[probe_index]:
+ probe_index += 1
+ else:
+ hidden.add(visible_index)
+
+ if probe_index != len(probe):
+ raise ValueError(
+ "The MathTypst grouping probe changed visible SVG geometry instead of "
+ "only hiding captured leaves. A custom Typst show rule for `hide` may "
+ "be interfering with subexpression selection."
+ )
+
+ return hidden
class Typst(SVGMobject):
@@ -240,6 +361,11 @@ class Typst(SVGMobject):
self._baseline_tracked_submobjects: list[VMobject] = []
self._stroke_width_tracked_submobjects: list[VMobject] = []
self._label_aliases: dict[str, list[str]] = {}
+ self._svg_leaf_labels: dict[int, list[str]] = getattr(
+ self,
+ "_svg_leaf_labels",
+ {},
+ )
file_name = typst_to_svg_file(
typst_code,
@@ -499,36 +625,56 @@ class Typst(SVGMobject):
# -- SVG post-processing -------------------------------------------------
def modify_xml_tree(self, element_tree: ET.ElementTree) -> ET.ElementTree:
- """Convert ``data-typst-label`` attributes to ``id`` before parsing.
-
- Typst's SVG renderer emits ``data-typst-label`` on ``<g>`` elements
- that carry a label (created via ``#box(body) <label>``). The
- ``svgelements`` library propagates custom ``data-*`` attributes from
- parent groups to all children, making them unusable as unique group
- keys. ``id`` attributes, on the other hand, are *not* inherited.
-
- This method walks the XML tree and promotes every
- ``data-typst-label`` to ``id`` (on ``<g>`` elements only), so that
- :meth:`~.SVGMobject.get_mobjects_from` can pick them up via its
- existing ``id``-based grouping logic.
+ """Add Manim group IDs to Typst SVG elements before parsing.
+
+ Ordinary Typst labels are promoted from ``data-typst-label`` to ``id``.
+ :class:`MathTypst` capture groups additionally provide a leaf-index to
+ label mapping obtained from layout-preserving ``hide`` probes. Each
+ captured leaf is wrapped in one or more identified SVG groups, allowing
+ nested captures without altering the final Typst layout.
"""
- # Let the base class inject default style wrappers first.
+ label_counts: dict[str, int] = {}
+
+ def next_svg_id(label: str) -> str:
+ count = label_counts.get(label, 0)
+ label_counts[label] = count + 1
+ if count == 0:
+ return label
+ return f"{label}{_DUPLICATE_LABEL_SUFFIX}{count}"
+
+ if self._svg_leaf_labels:
+ root = element_tree.getroot()
+ assert root is not None
+ for leaf_index, (parent, index, element, _) in enumerate(
+ list(_iter_svg_leaves(root))
+ ):
+ wrapped = element
+ for label in reversed(self._svg_leaf_labels.get(leaf_index, [])):
+ namespace = (
+ wrapped.tag.partition("}")[0] + "}"
+ if "}" in wrapped.tag
+ else ""
+ )
+ group = ET.Element(
+ f"{namespace}g",
+ {"id": next_svg_id(label)},
+ )
+ group.append(wrapped)
+ wrapped = group
+ parent[index] = wrapped
+
+ # Let the base class inject default style wrappers after capture leaves
+ # have been grouped in the original SVG namespace.
element_tree = super().modify_xml_tree(element_tree)
- # Walk all elements regardless of namespace — ElementTree
- # qualifies tags with the namespace URI, so a bare ``"g"``
- # won't match ``{http://www.w3.org/2000/svg}g``.
- label_counts: dict[str, int] = {}
+ # ElementTree qualifies SVG tags with a namespace URI, so walk all
+ # elements rather than matching a bare ``g`` tag.
for element in element_tree.iter():
- label = element.get("data-typst-label")
- if label is not None:
- count = label_counts.get(label, 0)
- label_counts[label] = count + 1
- svg_id = label
- if count > 0:
- svg_id = f"{label}{_DUPLICATE_LABEL_SUFFIX}{count}"
- element.set("id", svg_id)
- del element.attrib["data-typst-label"]
+ typst_label = element.get("data-typst-label")
+ if typst_label is None:
+ continue
+ element.set("id", next_svg_id(typst_label))
+ del element.attrib["data-typst-label"]
return element_tree
@@ -537,16 +683,15 @@ class Typst(SVGMobject):
def select(self, key: str | int) -> VGroup:
"""Select a labeled sub-expression.
- Labels are created in the Typst source either manually via the
- ``manimgrp`` helper or automatically through the ``{{ }}``
- double-brace notation in :class:`MathTypst`.
+ Labels are created either directly in Typst markup or through the
+ ``{{ }}`` double-brace notation in :class:`MathTypst`.
Parameters
----------
key
- A label name (``str``) matching a ``data-typst-label`` in the
- SVG, or an integer index into the auto-numbered ``{{ }}``
- groups (``_grp-0``, ``_grp-1``, …).
+ A label name (``str``) available in the rendered SVG, or an
+ integer index into the auto-numbered ``{{ }}`` groups
+ (``_grp-0``, ``_grp-1``, …).
Returns
-------
@@ -591,10 +736,7 @@ class Typst(SVGMobject):
return self._select_label(key)
def _user_label_keys(self) -> list[str]:
- """Return the label keys that were created from ``data-typst-label``
- attributes (filtering out internal Typst group IDs and auto-numbered
- groups).
- """
+ """Return user-facing label keys, excluding internal SVG group IDs."""
return list(self._label_aliases)
# -- color handling ------------------------------------------------------
@@ -625,13 +767,19 @@ class MathTypst(Typst):
(``$ ... $`` with surrounding spaces).
Supports the ``{{ ... }}`` double-brace notation for grouping
- sub-expressions. Each ``{{ content }}`` is wrapped in a labeled
- ``manimgrp`` call so that the resulting SVG contains identifiable
- groups accessible via :meth:`~.Typst.select`.
+ sub-expressions. The final expression is rendered without a layout
+ wrapper; additional layout-preserving ``hide`` probes map each capture
+ to SVG leaves accessible via :meth:`~.Typst.select`.
Groups can optionally be given explicit labels:
- ``{{ content : label }}``. Without a label, groups are
- auto-numbered (``_grp-0``, ``_grp-1``, …).
+ ``{{ content : label }}``. Without a label, groups are
+ auto-numbered (``_grp-0``, ``_grp-1``, …). Groups may be nested; an inner
+ group's SVG leaves are then selectable through both labels.
+
+ .. note::
+
+ Custom Typst show rules targeting ``hide`` are not supported together
+ with ``{{ ... }}`` capture groups.
Parameters
----------
@@ -668,19 +816,52 @@ class MathTypst(Typst):
def __init__(self, math_expression: str, **kwargs: Any):
processed, labels = self._preprocess_groups(math_expression)
self._group_labels = labels
-
- # Inject the manimgrp helper when groups are present.
- if labels:
- preamble = kwargs.get("typst_preamble", "")
- if _MANIMGRP_PREAMBLE not in preamble:
- preamble = (
- f"{_MANIMGRP_PREAMBLE}\n{preamble}"
- if preamble
- else _MANIMGRP_PREAMBLE
+ typst_code = f"$ {processed} $"
+ distinct_labels = list(dict.fromkeys(labels))
+
+ if distinct_labels:
+ user_preamble = kwargs.get("typst_preamble", "")
+ font_paths = kwargs.get("font_paths")
+ final_preamble = _manimgrp_preamble(None)
+ if user_preamble:
+ final_preamble = f"{final_preamble}\n{user_preamble}"
+
+ final_svg = typst_to_svg_file(
+ typst_code,
+ preamble=final_preamble,
+ font_paths=font_paths,
+ )
+ visible_leaves = _svg_leaf_signatures(final_svg)
+ leaf_labels: dict[int, list[str]] = {}
+
+ for label in distinct_labels:
+ probe_preamble = _manimgrp_preamble(label)
+ if user_preamble:
+ probe_preamble = f"{probe_preamble}\n{user_preamble}"
+ probe_svg = typst_to_svg_file(
+ typst_code,
+ preamble=probe_preamble,
+ font_paths=font_paths,
)
- kwargs["typst_preamble"] = preamble
+ try:
+ hidden_indices = _hidden_leaf_indices(
+ visible_leaves,
+ _svg_leaf_signatures(probe_svg),
+ )
+ except ValueError as error:
+ raise ValueError(
+ f"Could not map MathTypst group {label!r} to SVG leaves. "
+ f"{error}"
+ ) from error
+ for leaf_index in sorted(hidden_indices):
+ leaf_labels.setdefault(leaf_index, []).append(label)
- super().__init__(f"$ {processed} $", **kwargs)
+ self._svg_leaf_labels = leaf_labels
+ kwargs["typst_preamble"] = final_preamble
+
+ super().__init__(typst_code, **kwargs)
+ for label in distinct_labels:
+ self._label_aliases.setdefault(label, [])
# -- double-brace preprocessor -------------------------------------------
@@ -698,121 +879,119 @@ class MathTypst(Typst):
tuple[str, list[str]]
The processed expression and an ordered list of group labels.
"""
- result: list[str] = []
labels: list[str] = []
auto_index = 0
- i = 0
- n = len(math_expr)
- outer_in_string = False
- outer_bracket_depth = 0
-
- while i < n:
- ch = math_expr[i]
-
- # Track string literals at the outer level.
- if outer_in_string:
- result.append(ch)
- if ch == "\\" and i + 1 < n:
- result.append(math_expr[i + 1])
- i += 2
+
+ def process(expression: str) -> str:
+ nonlocal auto_index
+ result: list[str] = []
+ i = 0
+ n = len(expression)
+ in_string = False
+ bracket_depth = 0
+
+ while i < n:
+ ch = expression[i]
+
+ if in_string:
+ result.append(ch)
+ if ch == "\\" and i + 1 < n:
+ result.append(expression[i + 1])
+ i += 2
+ continue
+ if ch == '"':
+ in_string = False
+ i += 1
continue
if ch == '"':
- outer_in_string = False
- i += 1
- continue
- if ch == '"':
- outer_in_string = True
- result.append(ch)
- i += 1
- continue
+ in_string = True
+ result.append(ch)
+ i += 1
+ continue
- # Track [...] content blocks at the outer level.
- if ch == "[":
- outer_bracket_depth += 1
- result.append(ch)
- i += 1
- continue
- if ch == "]" and outer_bracket_depth > 0:
- outer_bracket_depth -= 1
- result.append(ch)
- i += 1
- continue
- if outer_bracket_depth > 0:
- result.append(ch)
- i += 1
- continue
+ if ch == "[":
+ bracket_depth += 1
+ result.append(ch)
+ i += 1
+ continue
+ if ch == "]" and bracket_depth > 0:
+ bracket_depth -= 1
+ result.append(ch)
+ i += 1
+ continue
+ if bracket_depth > 0:
+ result.append(ch)
+ i += 1
+ continue
+
+ if i + 1 >= n or ch != "{" or expression[i + 1] != "{":
+ result.append(ch)
+ i += 1
+ continue
- # Look for opening {{ (not a single {)
- if i + 1 < n and ch == "{" and math_expr[i + 1] == "{":
- i += 2 # skip {{
+ group_start = i
+ i += 2
content_start = i
depth = 1
- in_string = False
- bracket_depth = 0
+ group_in_string = False
+ group_bracket_depth = 0
while i < n and depth > 0:
- ch = math_expr[i]
-
- if in_string:
+ ch = expression[i]
+ if group_in_string:
if ch == "\\" and i + 1 < n:
i += 2
continue
if ch == '"':
- in_string = False
+ group_in_string = False
i += 1
continue
-
if ch == '"':
- in_string = True
+ group_in_string = True
i += 1
continue
-
if ch == "[":
- bracket_depth += 1
+ group_bracket_depth += 1
i += 1
continue
- if ch == "]" and bracket_depth > 0:
- bracket_depth -= 1
+ if ch == "]" and group_bracket_depth > 0:
+ group_bracket_depth -= 1
i += 1
continue
- if bracket_depth > 0:
+ if group_bracket_depth > 0:
i += 1
continue
-
- if ch == "{" and i + 1 < n and math_expr[i + 1] == "{":
+ if ch == "{" and i + 1 < n and expression[i + 1] == "{":
depth += 1
i += 2
continue
- if ch == "}" and i + 1 < n and math_expr[i + 1] == "}":
+ if ch == "}" and i + 1 < n and expression[i + 1] == "}":
depth -= 1
if depth == 0:
- content = math_expr[content_start:i]
- i += 2 # skip }}
+ content = expression[content_start:i]
+ i += 2
break
i += 2
continue
-
i += 1
else:
- # Unclosed {{ — emit literally and stop.
- result.append("{{")
- result.append(math_expr[content_start:])
- return "".join(result), labels
-
- # Check for optional `: label` suffix.
- m = _LABEL_RE.match(content)
- if m is not None:
- body = m.group(1).strip()
- label = m.group(2)
+ result.append(expression[group_start:])
+ return "".join(result)
+
+ match = _LABEL_RE.match(content)
+ if match is not None:
+ body = match.group(1).strip()
+ label = match.group(2)
else:
body = content.strip()
label = f"_grp-{auto_index}"
auto_index += 1
+ # Record the outer capture before recursively processing its
+ # body, preserving source opening order for nested groups.
labels.append(label)
- result.append(f'manimgrp("{label}", {body})')
- else:
- result.append(math_expr[i])
- i += 1
+ result.append(f'manimgrp("{label}", {process(body)})')
+
+ return "".join(result)
- return "".join(result), labels
+ return process(math_expr), labels
diff --git a/tests/module/mobject/text/test_typst_mobject.py b/tests/module/mobject/text/test_typst_mobject.py
index 1ac379df7..903cb4643 100644
--- a/tests/module/mobject/text/test_typst_mobject.py
+++ b/tests/module/mobject/text/test_typst_mobject.py
@@ -283,6 +283,51 @@ def test_mathtypst_double_brace_mixed_named_auto(config):
assert len(eq.select(0)) == 1
+def test_mathtypst_groups_preserve_math_layout(config):
+ """Capture groups do not alter display math styling or spacing."""
+ expression = r"integral_0^infinity e^(-x^2) dif x = sqrt(pi)/2"
+ plain = MathTypst(expression, use_svg_cache=False)
+ grouped = MathTypst(
+ r"{{ integral_0^infinity e^(-x^2) dif x : integral }}"
+ r" = {{ sqrt(pi)/2 : result }}",
+ use_svg_cache=False,
+ )
+
+ assert len(plain) == len(grouped) == 15
+ assert np.isclose(plain.width, grouped.width)
+ assert np.isclose(plain.height, grouped.height)
+ assert all(
+ np.allclose(plain_part.points, grouped_part.points)
+ for plain_part, grouped_part in zip(plain, grouped, strict=True)
+ )
+ assert len(grouped.select("integral")) == 9
+ assert len(grouped.select("result")) == 5
+
+
+def test_mathtypst_nested_double_brace_groups(config):
+ """Nested captures select both the inner and containing expressions."""
+ eq = MathTypst(
+ "{{ a + {{ b : inner }} + c : outer }}",
+ use_svg_cache=False,
+ )
+
+ assert eq._group_labels == ["outer", "inner"]
+ assert len(eq.select("outer")) == 5
+ assert len(eq.select("inner")) == 1
+ assert eq.select("inner")[0] in eq.select("outer")
+
+
+def test_mathtypst_duplicate_capture_labels(config):
+ """Disjoint captures with one label are selected as a union."""
+ eq = MathTypst(
+ "{{ a : picked }} + a + {{ a : picked }}",
+ use_svg_cache=False,
+ )
+
+ assert len(eq.select("picked")) == 2
+ assert eq.select("picked")[0] is not eq.select("picked")[1]
+
+
def test_mathtypst_no_braces_no_preamble(config):
"""Without {{ }}, the manimgrp preamble is not injected."""
eq = MathTypst("a + b", use_svg_cache=False)
@@ -311,6 +356,16 @@ def test_mathtypst_preprocessor_skips_content_blocks():
assert processed.count("manimgrp") == 1
+def test_mathtypst_preprocessor_processes_nested_groups():
+ """Nested {{ }} groups are recursively converted in source order."""
+ processed, labels = MathTypst._preprocess_groups(
+ "{{ a + {{ b : inner }} + c : outer }}"
+ )
+
+ assert labels == ["outer", "inner"]
+ assert processed == ('manimgrp("outer", a + manimgrp("inner", b) + c)')
+
+
# -- integration tests for existing APIs ------------------------------------