Add a last resort font for missing glyphs

Author: QuLogic

Diff for: .github/workflows/tests.yml

@@ -196,10 +196,10 @@ jobs:
             ~/.cache/matplotlib
             !~/.cache/matplotlib/tex.cache
             !~/.cache/matplotlib/test_cache
-          key: 5-${{ matrix.os }}-py${{ matrix.python-version }}-mpl-${{ github.ref }}-${{ github.sha }}
+          key: 6-${{ matrix.os }}-py${{ matrix.python-version }}-mpl-${{ github.ref }}-${{ github.sha }}
           restore-keys: |
-            5-${{ matrix.os }}-py${{ matrix.python-version }}-mpl-${{ github.ref }}-
-            5-${{ matrix.os }}-py${{ matrix.python-version }}-mpl-
+            6-${{ matrix.os }}-py${{ matrix.python-version }}-mpl-${{ github.ref }}-
+            6-${{ matrix.os }}-py${{ matrix.python-version }}-mpl-
 
       - name: Install Python dependencies
         run: |

Diff for: LICENSE/LICENSE_LAST_RESORT_FONT

@@ -0,0 +1,97 @@
+Last Resort High-Efficiency Font License
+========================================
+
+This Font Software is licensed under the SIL Open Font License,
+Version 1.1.
+
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font
+creation efforts of academic and linguistic communities, and to
+provide a free and open framework in which fonts may be shared and
+improved in partnership with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply to
+any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software
+components as distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to,
+deleting, or substituting -- in part or in whole -- any of the
+components of the Original Version, by changing formats or by porting
+the Font Software to a new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed,
+modify, redistribute, and sell modified and unmodified copies of the
+Font Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components, in
+Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the
+corresponding Copyright Holder. This restriction only applies to the
+primary font name as presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created using
+the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.
+
+SPDX-License-Identifier: OFL-1.1

Diff for: doc/conf.py

@@ -102,6 +102,14 @@ def _parse_skip_subdirs_file():
 # usage in the gallery.
 warnings.filterwarnings('error', append=True)
 
+# Warnings for missing glyphs occur during `savefig`, and would cause any such plot to
+# not be created. Because the exception occurs in savefig, there is no way for the plot
+# itself ignore these warning locally, so we must do so globally.
+warnings.filterwarnings('default', category=UserWarning,
+                        message=r'Glyph \d+ \(.+\) missing from font\(s\)')
+warnings.filterwarnings('default', category=UserWarning,
+                        message=r'Matplotlib currently does not support .+ natively\.')
+
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [

Diff for: doc/users/next_whats_new/last_resort_font.rst

@@ -0,0 +1,40 @@
+Missing glyphs use Last Resort font
+-----------------------------------
+
+Most fonts do not have 100% character coverage, and will fall back to a "not found"
+glyph for characters that are not provided. Often, this glyph will be minimal (e.g., the
+default DejaVu Sans "not found" glyph is just a rectangle.) Such minimal glyphs provide
+no context as to the characters that are missing.
+
+Now, missing glyphs will fall back to the `Last Resort font
+<https://github.com/unicode-org/last-resort-font>`__ produced by the Unicode Consortium.
+This special-purpose font provides glyphs that represent types of Unicode characters.
+These glyphs show a representative character from the missing Unicode block, and at
+larger sizes, more context to help determine which character and font are needed.
+
+To disable this fallback behaviour, set :rc:`font.enable_last_resort` to ``False``.
+
+.. plot::
+    :alt: An example of missing glyph behaviour, the first glyph from Bengali script,
+        second glyph from Hiragana, and the last glyph from the Unicode Private Use
+        Area. Multiple lines repeat the text with increasing font size from top to
+        bottom.
+
+    text_raw = r"'\N{Bengali Digit Zero}\N{Hiragana Letter A}\ufdd0'"
+    text = eval(text_raw)
+    sizes = [
+        (0.85, 8),
+        (0.80, 10),
+        (0.75, 12),
+        (0.70, 16),
+        (0.63, 20),
+        (0.55, 24),
+        (0.45, 32),
+        (0.30, 48),
+        (0.10, 64),
+    ]
+
+    fig = plt.figure()
+    fig.text(0.01, 0.90, f'Input: {text_raw}')
+    for y, size in sizes:
+        fig.text(0.01, y, f'{size}pt:{text}', fontsize=size)

Diff for: lib/matplotlib/font_manager.py

@@ -1065,7 +1065,7 @@ class FontManager:
     # Increment this version number whenever the font cache data
     # format or behavior has changed and requires an existing font
     # cache files to be rebuilt.
-    __version__ = 390
+    __version__ = '3.11.0a1'
 
     def __init__(self, size=None, weight='normal'):
         self._version = self.__version__
@@ -1546,19 +1546,39 @@ def is_opentype_cff_font(filename):
 
 
 @lru_cache(64)
-def _get_font(font_filepaths, hinting_factor, *, _kerning_factor, thread_id):
+def _get_font(font_filepaths, hinting_factor, *, _kerning_factor, thread_id,
+              enable_last_resort):
     first_fontpath, *rest = font_filepaths
-    return ft2font.FT2Font(
+    fallback_list = [
+        ft2font.FT2Font(fpath, hinting_factor, _kerning_factor=_kerning_factor)
+        for fpath in rest
+    ]
+    last_resort_path = _cached_realpath(
+        cbook._get_data_path('fonts', 'ttf', 'LastResortHE-Regular.ttf'))
+    try:
+        last_resort_index = font_filepaths.index(last_resort_path)
+    except ValueError:
+        last_resort_index = -1
+        # Add Last Resort font so we always have glyphs regardless of font, unless we're
+        # already in the list.
+        if enable_last_resort:
+            fallback_list.append(
+                ft2font.FT2Font(last_resort_path, hinting_factor,
+                                _kerning_factor=_kerning_factor,
+                                _warn_if_used=True))
+            last_resort_index = len(fallback_list)
+    font = ft2font.FT2Font(
         first_fontpath, hinting_factor,
-        _fallback_list=[
-            ft2font.FT2Font(
-                fpath, hinting_factor,
-                _kerning_factor=_kerning_factor
-            )
-            for fpath in rest
-        ],
+        _fallback_list=fallback_list,
         _kerning_factor=_kerning_factor
     )
+    # Ensure we are using the right charmap for the Last Resort font; FreeType picks the
+    # Unicode one by default, but this exists only for Windows, and is empty.
+    if last_resort_index == 0:
+        font.set_charmap(0)
+    elif last_resort_index > 0:
+        fallback_list[last_resort_index - 1].set_charmap(0)
+    return font
 
 
 # FT2Font objects cannot be used across fork()s because they reference the same
@@ -1611,7 +1631,8 @@ def get_font(font_filepaths, hinting_factor=None):
         hinting_factor,
         _kerning_factor=mpl.rcParams['text.kerning_factor'],
         # also key on the thread ID to prevent segfaults with multi-threading
-        thread_id=threading.get_ident()
+        thread_id=threading.get_ident(),
+        enable_last_resort=mpl.rcParams['font.enable_last_resort'],
     )
 
 

Diff for: lib/matplotlib/font_manager.pyi

@@ -87,7 +87,7 @@ def json_dump(data: FontManager, filename: str | Path | os.PathLike) -> None: ..
 def json_load(filename: str | Path | os.PathLike) -> FontManager: ...
 
 class FontManager:
-    __version__: int
+    __version__: str
     default_size: float | None
     defaultFamily: dict[str, str]
     afmlist: list[FontEntry]

Diff for: lib/matplotlib/mpl-data/fonts/ttf/LastResortHE-Regular.ttf

@@ -278,6 +278,11 @@
 #font.fantasy:    Chicago, Charcoal, Impact, Western, xkcd script, fantasy
 #font.monospace:  DejaVu Sans Mono, Bitstream Vera Sans Mono, Computer Modern Typewriter, Andale Mono, Nimbus Mono L, Courier New, Courier, Fixed, Terminal, monospace
 
+## If font.enable_last_resort is True, then Unicode Consortium's Last Resort
+## font will be appended to all font selections. This ensures that there will
+## always be a glyph displayed.
+#font.enable_last_resort: true
+
 
 ## ***************************************************************************
 ## * TEXT                                                                    *

Diff for: lib/matplotlib/mpl-data/matplotlibrc

@@ -1035,6 +1035,7 @@ def _convert_validator_spec(key, conv):
     "boxplot.meanprops.linewidth":       validate_float,
 
     ## font props
+    "font.enable_last_resort":     validate_bool,
     "font.family":     validate_stringlist,  # used by text object
     "font.style":      validate_string,
     "font.variant":    validate_string,