Skip to content

Fix mathtext font fallback for glyphs missing from math fonts#31766

Open
1wos wants to merge 1 commit into
matplotlib:mainfrom
1wos:mathtext-cjk-fallback
Open

Fix mathtext font fallback for glyphs missing from math fonts#31766
1wos wants to merge 1 commit into
matplotlib:mainfrom
1wos:mathtext-cjk-fallback

Conversation

@1wos
Copy link
Copy Markdown

@1wos 1wos commented May 28, 2026

PR summary

Closes #29173.

CJK characters render correctly in regular text but are replaced by a ¤
placeholder when they appear inside a math expression ($...$). The cause is
that mathtext has no glyph-level font fallback: when a character is missing from
the math font (and the STIX/Bakoma math fallbacks), UnicodeFonts._get_glyph
returns a dummy glyph, whereas regular text walks the font's fallback chain.

This change makes _get_glyph search the configured text fonts and their
fallback chain (the same ones regular text uses, ending in the Last Resort font)
before falling back to the dummy glyph. The search only runs when the glyph is
missing, so text that already renders is unaffected. The FT2Font fallback list is
exposed to Python as a private FT2Font._fallbacks property to support this.

With a CJK font configured, CJK characters render in math just like in regular
text; otherwise they fall back to the Last Resort font instead of the dummy.

import matplotlib.pyplot as plt
plt.rcParams["font.family"] = "Arial Unicode MS"  # any CJK-capable font
plt.text(0.5, 0.5, r"$\alpha + 中文 + 한글 + \beta$")
plt.show()

AI Disclosure

I used generative AI (Claude) to help dig through the font code and draft the
implementation, tests, and this description. I reported the issue, decided on the
approach, and reviewed and tested everything locally.

PR checklist

Search the font's fallback chain before substituting a dummy glyph, so that e.g. CJK characters in math expressions render like they do in regular text.

Closes matplotlib#29173
@github-actions
Copy link
Copy Markdown

Thank you for opening your first PR into Matplotlib!

If you have not heard from us in a week or so, please leave a new comment below and that should bring it to our attention. Most of our reviewers are volunteers and sometimes things fall through the cracks. We also ask that you please finish addressing any review comments on this PR and wait for it to be merged (or closed) before opening a new one, as it can be a valuable learning experience to go through the review process.

You can also join us on discourse chat for real-time discussion.

For details on testing, writing docs, and our review process, please see the developer guide.
Please let us know if (and how) you use AI, it will help us give you better feedback on your PR.

We strive to be a welcoming and open project. Please follow our Code of Conduct.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

Status: No status

Development

Successfully merging this pull request may close these issues.

[Bug]: Font fallback issue with CJK characters in text containing math formulas

1 participant