Add template and additional_preamble parameters to Tex

[YishiMichael]

Features added

Supports self-defined tex templates and temporary addition of preambles

Sometimes users may want to temporarily use tex commands from tex packages not included in tex template files by default. So I add support for it. This is inspired from Manim Community. For classes Tex, MTex, parameters template and additional_preamble are added. Example usages are shown below.

Demo

tex = Tex(
    "a^2 + b^2 = c^2",
    template="French Cursive"
)
self.add(tex)

Result

Demo

chem = TexText(
    "\\ce{Zn^2+ <=>[+ 2OH-][+ 2H+] "
    "$\\underset{\\text{amphoteres Hydroxid}}{\\ce{Zn(OH)2 v}}$ "
    "<=>[+ 2OH-][+ 2H+]"
    "$\\underset{\\text{Hydroxozikat}}{\\ce{[Zn(OH)4]^2-}}$}",
    template="empty",
    additional_preamble="\\usepackage{mhchem}"
).scale(0.7)
self.add(chem)

Result

Demo

textext = MTexText(
    "The quick brown fox jumps over the lazy dog.",
    template="French Cursive", isolate="brown"
)
textext.select_part("brown").set_fill(LIGHT_BROWN)
self.add(textext)

Result

58 tex templates in total are provided in manimlib/tex_templates.yml. Users may feel free to add whatever template they want to this file for own usage. These templates can simply be accessed by passing their names to template attribute. By default, template is an empty string, in which case manim will use the default template specified at style.tex_template in the configuration file. Currently this key replaces all 4 attributes under tex key. The original template files (tex_template.tex and ctex_template.tex) are now removed, and are now included as default and ctex for backward compatibility.

Users may add preambles specifically to a Tex or MTex instance via additional_preamble attribute, which is also an empty string by default.

Frankly speaking, I'm a bit worried if having so much packages imported in a tex file could cause side effects. For instance, the "\vdots" command doesn't show up in the final svg (not caused by questionable parsing of svgelements; even the path is not defined). This issue may be caused by the line "\usepackage[T1]{fontenc}" (which I'm not sure). The point is, I would suggest using a template with only a few elementary packages imported, and add packages for specific Tex instances. Manim Community is also concerned about such an issue (ManimCommunity/manim#2889). That's why basic, empty templates show up in the tex_templates.yml. I also collected all 52 templates from the Community Edition and sorted them alphabetically.

New protect attribute for StringMobject

Users may use protect attribute to specify some substrings that are not expected to be broken up.

Demo

protected_tex = MTex(
    "\\begin{bmatrix} a & b \\\\ - b & a \\end{bmatrix}",
    tex_to_color_map={"a": GREEN, "b": RED},
    protect="{bmatrix}"
)
self.add(protected_tex)

Result

In the demonstration above, without specifying protect="{bmatrix}", all of letter bs (including ones in the word bmatrix) will be isolated. In fact, MTex can automatically handle most cases --- it protects all substrings matched by the regex expression \\([a-zA-Z]+|.). The case above is tricky so that we shall tackle it manually. Sidenote, this attribute only prevents from cutting halfway at protected spans, so isolating "\\begin{bmatrix}" in the example above is still allowed (but nobody will do so, unless on purpose).

protect attribute should be of type Selector, the same as isolate.

Add back disable_ligatures attribute in MarkupText and Text

For backward compatibility. Default to be True.

Features removed

Removes is_markup attribute for MarkupText and Text

This attribute is not expected to be altered up to the class --- so why not remove it?

No longer allows passing in a 2-tuple to tex_template attribute in MTex

This feature was originally added in #1795 in order to escape isolating substrings in, e.g., \begin{table}{ccc}, \end{table} (which cannot be solved by passing tex_environment="table"). Now we can make use of protect attribute to overcome this problem in an elegant way.

No longer adjusts spans in StringMobject

In the previous implementation, I designed an algorithm to handle spans pointing to crazy substrings, like "a{b". From now on, such spans will receive warnings and will no longer be adjusted. Similarly, partly overlapping substrings now lead to warnings instead of exceptions.

Issues fixed

#1760 After using math font package in tex_template of ManimGL, the TexText cannot displayed correctly

This issue is caused since svgelements cannot parse use elements whose referred elements are defined afterwards. This is fixed by expanding all use elements in svg before parsing.

#1792 Cannot show text in Ubuntu20.04

Text uses the line_height attribute to control the line spacing, which requires pango with version >=1.50. The version of pango is now checked to decide whether to insert this attribute.

#1848 Fix: can't parse <u>Boolean Operation</u>

Fixed passingly in the refactory.

#1850 ValueError: Invalid markup string - when entering characters in Interactive mode

The font_size attribute in a markup tag can only be integers. This issue is fixed by inserting a round function.

Other bugs

MTex.get_part_by_tex and Text.get_part_by_text miss **kwargs when passing attributes.

manimlib/animation/indication.py file misses imports from manimlib.constants.

Proposed changes

• M manimlib/animation/indication.py: Add missed imports.
• M manimlib/animation/transform_matching_parts.py: Refactor TransformMatchingStrings.
• M manimlib/default_config.yml: Add tex_template attribute; remove tex items.
• M manimlib/mobject/svg/mtex_mobject.py: Add template, additional_preamble attributes; refactor MTex according to StringMobject.
• M manimlib/mobject/svg/string_mobject.py: Refactor StringMobject.
• M manimlib/mobject/svg/svg_mobject.py: Expand use elements beforehand; use hash_string function.
• M manimlib/mobject/svg/tex_mobject.py: Add template, additional_preamble attributes.
• M manimlib/mobject/svg/text_mobject.py: Remove is_markup attribute; refactor Text according to StringMobject.
• A manimlib/tex_templates.yml: Add preambles of tex templates.
• R manimlib/tex_templates/.: Remove tex template files.
• M manimlib/utils/init_config.py: Alter according to default_config.yml.
• M manimlib/utils/simple_functions.py: Add hash_string function.
• M manimlib/utils/tex_file_writing.py: Make manim able to generate tex files based on specific preamble; remove tex_hash function.

[TonyCrane]

LGTM. But we'd better add a new example about Tex and TexText in example_scenes.py. And it's better to add a new page to the docs to introduce these full features of them.

[YishiMichael]

Recently the issue concerned with <use> tags in SVGMobject has been handled in the latest version of svgelements. Issue #1760 is now fixed. So I removed the process that expands all elements referenced by <use>, and add the version limitation of svgelements.

[3b1b]

Looks good to me.

If possible in the future (and I fully recognize the hypocrisy in this), it's better to split up conceptually distinct changes into multiple different PRs, e.g. the introduction of templates vs. the various issues fixed.