8000 Add font feature API to FontProperties and Text · matplotlib/matplotlib@ec912b1 · GitHub
[go: up one dir, main page]
Skip to content

Commit ec912b1

Browse files
QuLogicQuLogic
committed
Add font feature API to FontProperties and Text
Font features allow font designers to provide alternate glyphs or shaping within a single font. These features may be accessed via special tags corresponding to internal tables of glyphs. The mplcairo backend supports font features via an elaborate re-use of the font file path [1]. This commit adds the API to make this officially supported in the main user API. At this time, nothing in Matplotlib itself uses these settings, but they will have an effect with libraqm. [1] https://github.com/matplotlib/mplcairo/blob/v0.6.1/README.rst#font-formats-and-features
1 parent 0b7a88a commit ec912b1

File tree

12 files changed

+187
-3
lines changed

12 files changed

+187
-3
lines changed

‎doc/users/next_whats_new/font_features.rst‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
Specifying font feature tags
2+
----------------------------
3+
4+
OpenType fonts may support feature tags that specify alternate glyph shapes or
5+
substitions to be made optionally. The text API now supports setting a list of feature
6+
tags to be used with the associated font. Feature tags can be set/get with:
7+
8+
- `matplotlib.text.Text.set_fontfeatures` / `matplotlib.text.Text.get_fontfeatures`
9+
- `matplotlib.font_manager.FontProperties.set_features` /
10+
`matplotlib.font_manager.FontProperties.get_features`
11+
- Any API that creates a `.Text` object by passing the *fontfeatures* argument (e.g.,
12+
``plt.xlabel(..., fontfeatures=...)``)
13+
14+
Font feature strings are eventually passed to HarfBuzz, and so all `string formats
15+
supported by hb_feature_from_string()
16+
<https://harfbuzz.github.io/harfbuzz-hb-common.html#hb-feature-from-string>`__ are
17+
supported.
18+
19+
For example, the default font ``DejaVu Sans`` enables Standard Ligatures (the ``'liga'``
20+
tag) by default, and also provides optional Discretionary Ligatures (the ``dlig`` tag.)
21+
These may be toggled with ``+`` or ``-``.
22+
23+
.. plot::
24+
:include-source:
25+
26+
fig = plt.figure(figsize=(7, 3))
27+
28+
fig.text(0.5, 0.85, 'Ligatures', fontsize=40, horizontalalignment='center')
29+
30+
# Default has Standard Ligatures (liga).
31+
fig.text(0, 0.6, 'Default: fi ffi fl st', fontsize=40)
32+
33+
# Disable Standard Ligatures with -liga.
34+
fig.text(0, 0.35, 'Disabled: fi ffi fl st', fontsize=40,
35+
fontfeatures=['-liga'])
36+
37+
# Enable Discretionary Ligatures with dlig.
38+
fig.text(0, 0.1, 'Discretionary: fi ffi fl st', fontsize=40,
39+
fontfeatures=['dlig'])
40+
41+
Available font feature tags may be found at
42+
https://learn.microsoft.com/en-us/typography/opentype/spec/featurelist

‎lib/matplotlib/backends/_backend_pdf_ps.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -181,6 +181,7 @@ def _get_font_ttf(self, prop):
181181
font = font_manager.get_font(fnames)
182182
font.clear()
183183
font.set_size(prop.get_size_in_points(), 72)
184+
font.set_features(prop.get_features())
184185
return font
185186
except RuntimeError:
186187
logging.getLogger(__name__).warning(

‎lib/matplotlib/backends/backend_agg.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -253,6 +253,7 @@ def _prepare_font(self, font_prop):
253253
font.clear()
254254
size = font_prop.get_size_in_points()
255255
font.set_size(size, self.dpi)
256+
font.set_features(font_prop.get_features())
256257
return font
257258

258259
def points_to_pixels(self, points):

‎lib/matplotlib/font_manager.py‎

Lines changed: 48 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -536,7 +536,7 @@ def afmFontProperty(fontpath, font):
536536

537537
def _cleanup_fontproperties_init(init_method):
538538
"""
539-
A decorator to limit the call signature to single a positional argument
539+
A decorator to limit the call signature to a single positional argument
540540
or alternatively only keyword arguments.
541541
542542
We still accept but deprecate all other call signatures.
@@ -624,6 +624,13 @@ class FontProperties:
624624
Supported values are: 'dejavusans', 'dejavuserif', 'cm',
625625
'stix', 'stixsans' and 'custom'. Default: :rc:`mathtext.fontset`
626626
627+
- features: A list of advanced font feature tags to enable. Font features are a
628+
component of OpenType fonts that allows picking from multiple stylistic variations
629+
within a single font. This may include small caps, ligatures, alternate forms of
630+
commonly-confused glyphs (e.g., capital I vs. lower-case l), and various other
631+
options. A `list of feature tags may be found here
632+
<https://learn.microsoft.com/en-us/typography/opentype/spec/featurelist>`__.
633+
627634
Alternatively, a font may be specified using the absolute path to a font
628635
file, by using the *fname* kwarg. However, in this case, it is typically
629636
simpler to just pass the path (as a `pathlib.Path`, not a `str`) to the
@@ -657,7 +664,8 @@ class FontProperties:
657664
def __init__(self, family=None, style=None, variant=None, weight=None,
658665
stretch=None, size=None,
659666
fname=None, # if set, it's a hardcoded filename to use
660-
math_fontfamily=None):
667+
math_fontfamily=None,
668+
features=None):
661669
self.set_family(family)
662670
self.set_style(style)
663671
self.set_variant(variant)
@@ -666,6 +674,7 @@ def __init__(self, family=None, style=None, variant=None, weight=None,
666674
self.set_file(fname)
667675
self.set_size(size)
668676
self.set_math_fontfamily(math_fontfamily)
677+
self.set_features(features)
669678
# Treat family as a fontconfig pattern if it is the only parameter
670679
# provided. Even in that case, call the other setters first to set
671680
# attributes not specified by the pattern to the rcParams defaults.
@@ -705,7 +714,8 @@ def __hash__(self):
705714
self.get_stretch(),
706715
self.get_size(),
707716
self.get_file(),
708-
self.get_math_fontfamily())
717+
self.get_math_fontfamily(),
718+
self.get_features())
709719
return hash(l)
710720

711721
def __eq__(self, other):
@@ -952,6 +962,41 @@ def set_math_fontfamily(self, fontfamily):
952962
_api.check_in_list(valid_fonts, math_fontfamily=fontfamily)
953963
self._math_fontfamily = fontfamily
954964

965+
def get_features(self):
966+
"""Return a tuple of font feature tags to enable."""
967+
return self._features
968+
969+
def set_features(self, features):
970+
"""
971+
Set the font feature tags to enable on this font.
972+
973+
Parameters
974+
----------
975+
features : list[str]
976+
A list of feature tags to be used with the associated font. These strings
977+
are eventually passed to HarfBuzz, and so all `string formats supported by
978+
hb_feature_from_string()
979+
<https://harfbuzz.github.io/harfbuzz-hb-common.html#hb-feature-from-string>`__
980+
are supported.
981+
982+
For example, if your desired font includes Stylistic Sets which enable
983+
various typographic alternates including one that you do not wish to use
984+
(e.g., Contextual Ligatures), then you can pass the following to enable one
985+
and not the other::
986+
987+
fp.set_features([
988+
'ss01', # Use Stylistic Set 1.
989+
'-clig', # But disable Contextural Ligatures.
990+
])
991+
992+
Available font feature tags may be found at
993+
https://learn.microsoft.com/en-us/typography/opentype/spec/featurelist
994+
"""
995+
_api.check_isinstance((list, tuple, None), features=features)
996+
if features is not None:
997+
features = tuple(features)
998+
self._features = features
999+
9551000
def copy(self):
9561001
"""Return a copy of self."""
9571002
return copy.copy(self)

‎lib/matplotlib/font_manager.pyi‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,7 @@ class FontProperties:
5252
size: float | str | None = ...,
5353
fname: str | os.PathLike | Path | None = ...,
5454
math_fontfamily: str | None = ...,
55+
features: list[str] | None = ...,
5556
) -> None: ...
5657
def __hash__(self) -> int: ...
5758
def __eq__(self, other: object) -> bool: ...
@@ -76,6 +77,8 @@ class FontProperties:
7677
def set_fontconfig_pattern(self, pattern: str) -> None: ...
7778
def get_math_fontfamily(self) -> str: ...
7879
def set_math_fontfamily(self, fontfamily: str | None) -> None: ...
80+
def get_features(self) -> tuple[str, ...]: ...
81+
def set_features(self, features: list[str] | None) -> None: ...
7982
def copy(self) -> FontProperties: ...
8083
# Aliases
8184
set_name = set_family

‎lib/matplotlib/ft2font.pyi‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -234,6 +234,7 @@ class FT2Font(Buffer):
234234
def load_glyph(self, glyphindex: int, flags: LoadFlags = ...) -> Glyph: ...
235235
def select_charmap(self, i: int) -> None: ...
236236
def set_charmap(self, i: int) -> None: ...
237+
def set_features(self, features: tuple[str, ...]) -> None: ...
237238
def set_size(self, ptsize: float, dpi: float) -> None: ...
238239
def set_text(
239240
self, string: str, angle: float = ..., flags: LoadFlags = ...

‎lib/matplotlib/tests/test_ft2font.py‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -198,6 +198,19 @@ def test_ft2font_set_size():
198198
assert font.get_width_height() == tuple(pytest.approx(2 * x, 1e-1) for x in orig)
199199

200200

201+
def test_ft2font_features():
202+
# Smoke test that these are accepted as intended.
203+
file = fm.findfont('DejaVu Sans')
204+
font = ft2font.FT2Font(file)
205+
font.set_features(None) # unset
206+
font.set_features(['calt', 'dlig']) # list
207+
font.set_features(('calt', 'dlig')) # tuple
208+
with pytest.raises(TypeError):
209+
font.set_features(123)
210+
with pytest.raises(TypeError):
211+
font.set_features([123, 456])
212+
213+
201214
def test_ft2font_charmaps():
202215
def enc(name):
203216
# We don't expose the encoding enum from FreeType, but can generate it here.

‎lib/matplotlib/text.py‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -888,6 +888,16 @@ def get_fontweight(self):
888888
"""
889889
return self._fontproperties.get_weight()
890890

891+
def get_fontfeatures(self):
892+
"""
893+
Return a tuple of font feature tags to enable.
894+
895+
See Also
896+
--------
897+
.font_manager.FontProperties.get_features
898+
"""
899+
return self._fontproperties.get_features()
900+
891901
def get_stretch(self):
892902
"""
893903
Return the font stretch as a string or a number.
@@ -1198,6 +1208,39 @@ def set_fontstretch(self, stretch):
11981208
self._fontproperties.set_stretch(stretch)
11991209
self.stale = True
12001210

1211+
def set_fontfeatures(self, features):
1212+
"""
1213+
Set the feature tags to enable on the font.
1214+
1215+
Parameters
1216+
----------
1217+
features : list[str]
1218+
A list of feature tags to be used with the associated font. These strings
1219+
are eventually passed to HarfBuzz, and so all `string formats supported by
1220+
hb_feature_from_string()
1221+
<https://harfbuzz.github.io/harfbuzz-hb-common.html#hb-feature-from-string>`__
1222+
are supported.
1223+
1224+
For example, if your desired font includes Stylistic Sets which enable
1225+
various typographic alternates including one that you do not wish to use
1226+
(e.g., Contextual Ligatures), then you can pass the following to enable one
1227+
and not the other::
1228+
1229+
fp.set_features([
1230+
'ss01', # Use Stylistic Set 1.
1231+
'-clig', # But disable Contextural Ligatures.
1232+
])
1233+
1234+
Available font feature tags may be found at
1235+
https://learn.microsoft.com/en-us/typography/opentype/spec/featurelist
1236+
1237+
See Also
1238+
--------
1239+
.font_manager.FontProperties.set_features
1240+
"""
1241+
self._fontproperties.set_features(features)
1242+
self.stale = True
1243+
12011244
def set_position(self, xy):
12021245
"""
12031246
Set the (*x*, *y*) position of the text.

‎lib/matplotlib/textpath.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,7 @@ def _get_font(self, prop):
3434
filenames = _fontManager._find_fonts_by_props(prop)
3535
font = get_font(filenames)
3636
font.set_size(self.FONT_SCALE, self.DPI)
37+
font.set_features(prop.get_features())
3738
return font
3839

3940
def _get_hinting_flag(self):

‎src/ft2font.cpp‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -336,6 +336,11 @@ void FT2Font::set_size(double ptsize, double dpi)
336336
}
337337
}
338338

339+
void FT2Font::set_features(std::vector<std::string> features)
340+
{
341+
feature_tags = std::move(features);
342+
}
343+
339344
void FT2Font::set_charmap(int i)
340345
{
341346
if (i >= face->num_charmaps) {

0 commit comments

Comments
 (0)
0