/
texmanager.py
368 lines (329 loc) · 14.9 KB
/
texmanager.py
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
r"""
Support for embedded TeX expressions in Matplotlib.
Requirements:
* LaTeX.
* \*Agg backends: dvipng>=1.6.
* PS backend: PSfrag, dvips, and Ghostscript>=9.0.
* PDF and SVG backends: if LuaTeX is present, it will be used to speed up some
post-processing steps, but note that it is not used to parse the TeX string
itself (only LaTeX is supported).
To enable TeX rendering of all text in your Matplotlib figure, set
:rc:`text.usetex` to True.
TeX and dvipng/dvips processing results are cached
in ~/.matplotlib/tex.cache for reuse between sessions.
`TexManager.get_rgba` can also be used to directly obtain raster output as RGBA
NumPy arrays.
"""
import functools
import hashlib
import logging
import os
from pathlib import Path
import subprocess
from tempfile import TemporaryDirectory
import numpy as np
import matplotlib as mpl
from matplotlib import _api, cbook, dviread
_log = logging.getLogger(__name__)
def _usepackage_if_not_loaded(package, *, option=None):
"""
Output LaTeX code that loads a package (possibly with an option) if it
hasn't been loaded yet.
LaTeX cannot load twice a package with different options, so this helper
can be used to protect against users loading arbitrary packages/options in
their custom preamble.
"""
option = f"[{option}]" if option is not None else ""
return (
r"\makeatletter"
r"\@ifpackageloaded{%(package)s}{}{\usepackage%(option)s{%(package)s}}"
r"\makeatother"
) % {"package": package, "option": option}
class TexManager:
"""
Convert strings to dvi files using TeX, caching the results to a directory.
Repeated calls to this constructor always return the same instance.
"""
texcache = os.path.join(mpl.get_cachedir(), 'tex.cache')
_grey_arrayd = {}
_font_families = ('serif', 'sans-serif', 'cursive', 'monospace')
_font_preambles = {
'new century schoolbook': r'\renewcommand{\rmdefault}{pnc}',
'bookman': r'\renewcommand{\rmdefault}{pbk}',
'times': r'\usepackage{mathptmx}',
'palatino': r'\usepackage{mathpazo}',
'zapf chancery': r'\usepackage{chancery}',
'cursive': r'\usepackage{chancery}',
'charter': r'\usepackage{charter}',
'serif': '',
'sans-serif': '',
'helvetica': r'\usepackage{helvet}',
'avant garde': r'\usepackage{avant}',
'courier': r'\usepackage{courier}',
# Loading the type1ec package ensures that cm-super is installed, which
# is necessary for Unicode computer modern. (It also allows the use of
# computer modern at arbitrary sizes, but that's just a side effect.)
'monospace': r'\usepackage{type1ec}',
'computer modern roman': r'\usepackage{type1ec}',
'computer modern sans serif': r'\usepackage{type1ec}',
'computer modern typewriter': r'\usepackage{type1ec}',
}
_font_types = {
'new century schoolbook': 'serif',
'bookman': 'serif',
'times': 'serif',
'palatino': 'serif',
'zapf chancery': 'cursive',
'charter': 'serif',
'helvetica': 'sans-serif',
'avant garde': 'sans-serif',
'courier': 'monospace',
'computer modern roman': 'serif',
'computer modern sans serif': 'sans-serif',
'computer modern typewriter': 'monospace',
}
grey_arrayd = _api.deprecate_privatize_attribute("3.5")
font_family = _api.deprecate_privatize_attribute("3.5")
font_families = _api.deprecate_privatize_attribute("3.5")
font_info = _api.deprecate_privatize_attribute("3.5")
@functools.lru_cache() # Always return the same instance.
def __new__(cls):
Path(cls.texcache).mkdir(parents=True, exist_ok=True)
return object.__new__(cls)
@_api.deprecated("3.6")
def get_font_config(self):
preamble, font_cmd = self._get_font_preamble_and_command()
# Add a hash of the latex preamble to fontconfig so that the
# correct png is selected for strings rendered with same font and dpi
# even if the latex preamble changes within the session
preambles = preamble + font_cmd + self.get_custom_preamble()
return hashlib.md5(preambles.encode('utf-8')).hexdigest()
@classmethod
def _get_font_family_and_reduced(cls):
"""Return the font family name and whether the font is reduced."""
ff = mpl.rcParams['font.family']
ff_val = ff[0].lower() if len(ff) == 1 else None
if len(ff) == 1 and ff_val in cls._font_families:
return ff_val, False
elif len(ff) == 1 and ff_val in cls._font_preambles:
return cls._font_types[ff_val], True
else:
_log.info('font.family must be one of (%s) when text.usetex is '
'True. serif will be used by default.',
', '.join(cls._font_families))
return 'serif', False
@classmethod
def _get_font_preamble_and_command(cls):
requested_family, is_reduced_font = cls._get_font_family_and_reduced()
preambles = {}
for font_family in cls._font_families:
if is_reduced_font and font_family == requested_family:
preambles[font_family] = cls._font_preambles[
mpl.rcParams['font.family'][0].lower()]
else:
for font in mpl.rcParams['font.' + font_family]:
if font.lower() in cls._font_preambles:
preambles[font_family] = \
cls._font_preambles[font.lower()]
_log.debug(
'family: %s, font: %s, info: %s',
font_family, font,
cls._font_preambles[font.lower()])
break
else:
_log.debug('%s font is not compatible with usetex.',
font)
else:
_log.info('No LaTeX-compatible font found for the %s font'
'family in rcParams. Using default.',
font_family)
preambles[font_family] = cls._font_preambles[font_family]
# The following packages and commands need to be included in the latex
# file's preamble:
cmd = {preambles[family]
for family in ['serif', 'sans-serif', 'monospace']}
if requested_family == 'cursive':
cmd.add(preambles['cursive'])
cmd.add(r'\usepackage{type1cm}')
preamble = '\n'.join(sorted(cmd))
fontcmd = (r'\sffamily' if requested_family == 'sans-serif' else
r'\ttfamily' if requested_family == 'monospace' else
r'\rmfamily')
return preamble, fontcmd
@classmethod
def get_basefile(cls, tex, fontsize, dpi=None):
"""
Return a filename based on a hash of the string, fontsize, and dpi.
"""
src = cls._get_tex_source(tex, fontsize) + str(dpi)
return os.path.join(
cls.texcache, hashlib.md5(src.encode('utf-8')).hexdigest())
@classmethod
def get_font_preamble(cls):
"""
Return a string containing font configuration for the tex preamble.
"""
font_preamble, command = cls._get_font_preamble_and_command()
return font_preamble
@classmethod
def get_custom_preamble(cls):
"""Return a string containing user additions to the tex preamble."""
return mpl.rcParams['text.latex.preamble']
@classmethod
def _get_tex_source(cls, tex, fontsize):
"""Return the complete TeX source for processing a TeX string."""
font_preamble, fontcmd = cls._get_font_preamble_and_command()
baselineskip = 1.25 * fontsize
return "\n".join([
r"\documentclass{article}",
r"% Pass-through \mathdefault, which is used in non-usetex mode",
r"% to use the default text font but was historically suppressed",
r"% in usetex mode.",
r"\newcommand{\mathdefault}[1]{#1}",
font_preamble,
r"\usepackage[utf8]{inputenc}",
r"\DeclareUnicodeCharacter{2212}{\ensuremath{-}}",
r"% geometry is loaded before the custom preamble as ",
r"% convert_psfrags relies on a custom preamble to change the ",
r"% geometry.",
r"\usepackage[papersize=72in, margin=1in]{geometry}",
cls.get_custom_preamble(),
r"% Use `underscore` package to take care of underscores in text.",
r"% The [strings] option allows to use underscores in file names.",
_usepackage_if_not_loaded("underscore", option="strings"),
r"% Custom packages (e.g. newtxtext) may already have loaded ",
r"% textcomp with different options.",
_usepackage_if_not_loaded("textcomp"),
r"\pagestyle{empty}",
r"\begin{document}",
r"% The empty hbox ensures that a page is printed even for empty",
r"% inputs, except when using psfrag which gets confused by it.",
r"% matplotlibbaselinemarker is used by dviread to detect the",
r"% last line's baseline.",
rf"\fontsize{{{fontsize}}}{{{baselineskip}}}%",
r"\ifdefined\psfrag\else\hbox{}\fi%",
rf"{{\obeylines{fontcmd} {tex}}}%",
r"\special{matplotlibbaselinemarker}%",
r"\end{document}",
])
@classmethod
def make_tex(cls, tex, fontsize):
"""
Generate a tex file to render the tex string at a specific font size.
Return the file name.
"""
texfile = cls.get_basefile(tex, fontsize) + ".tex"
Path(texfile).write_text(cls._get_tex_source(tex, fontsize),
encoding='utf-8')
return texfile
@classmethod
def _run_checked_subprocess(cls, command, tex, *, cwd=None):
_log.debug(cbook._pformat_subprocess(command))
try:
report = subprocess.check_output(
command, cwd=cwd if cwd is not None else cls.texcache,
stderr=subprocess.STDOUT)
except FileNotFoundError as exc:
raise RuntimeError(
'Failed to process string with tex because {} could not be '
'found'.format(command[0])) from exc
except subprocess.CalledProcessError as exc:
raise RuntimeError(
'{prog} was not able to process the following string:\n'
'{tex!r}\n\n'
'Here is the full command invocation and its output:\n\n'
'{format_command}\n\n'
'{exc}\n\n'.format(
prog=command[0],
format_command=cbook._pformat_subprocess(command),
tex=tex.encode('unicode_escape'),
exc=exc.output.decode('utf-8', 'backslashreplace'))
) from None
_log.debug(report)
return report
@classmethod
def make_dvi(cls, tex, fontsize):
"""
Generate a dvi file containing latex's layout of tex string.
Return the file name.
"""
basefile = cls.get_basefile(tex, fontsize)
dvifile = '%s.dvi' % basefile
if not os.path.exists(dvifile):
texfile = Path(cls.make_tex(tex, fontsize))
# Generate the dvi in a temporary directory to avoid race
# conditions e.g. if multiple processes try to process the same tex
# string at the same time. Having tmpdir be a subdirectory of the
# final output dir ensures that they are on the same filesystem,
# and thus replace() works atomically. It also allows referring to
# the texfile with a relative path (for pathological MPLCONFIGDIRs,
# the absolute path may contain characters (e.g. ~) that TeX does
# not support.)
with TemporaryDirectory(dir=Path(dvifile).parent) as tmpdir:
cls._run_checked_subprocess(
["latex", "-interaction=nonstopmode", "--halt-on-error",
f"../{texfile.name}"], tex, cwd=tmpdir)
(Path(tmpdir) / Path(dvifile).name).replace(dvifile)
return dvifile
@classmethod
def make_png(cls, tex, fontsize, dpi):
"""
Generate a png file containing latex's rendering of tex string.
Return the file name.
"""
basefile = cls.get_basefile(tex, fontsize, dpi)
pngfile = '%s.png' % basefile
# see get_rgba for a discussion of the background
if not os.path.exists(pngfile):
dvifile = cls.make_dvi(tex, fontsize)
cmd = ["dvipng", "-bg", "Transparent", "-D", str(dpi),
"-T", "tight", "-o", pngfile, dvifile]
# When testing, disable FreeType rendering for reproducibility; but
# dvipng 1.16 has a bug (fixed in f3ff241) that breaks --freetype0
# mode, so for it we keep FreeType enabled; the image will be
# slightly off.
if (getattr(mpl, "_called_from_pytest", False) and
mpl._get_executable_info("dvipng").raw_version != "1.16"):
cmd.insert(1, "--freetype0")
cls._run_checked_subprocess(cmd, tex)
return pngfile
@classmethod
def get_grey(cls, tex, fontsize=None, dpi=None):
"""Return the alpha channel."""
if not fontsize:
fontsize = mpl.rcParams['font.size']
if not dpi:
dpi = mpl.rcParams['savefig.dpi']
key = cls._get_tex_source(tex, fontsize), dpi
alpha = cls._grey_arrayd.get(key)
if alpha is None:
pngfile = cls.make_png(tex, fontsize, dpi)
rgba = mpl.image.imread(os.path.join(cls.texcache, pngfile))
cls._grey_arrayd[key] = alpha = rgba[:, :, -1]
return alpha
@classmethod
def get_rgba(cls, tex, fontsize=None, dpi=None, rgb=(0, 0, 0)):
r"""
Return latex's rendering of the tex string as an rgba array.
Examples
--------
>>> texmanager = TexManager()
>>> s = r"\TeX\ is $\displaystyle\sum_n\frac{-e^{i\pi}}{2^n}$!"
>>> Z = texmanager.get_rgba(s, fontsize=12, dpi=80, rgb=(1, 0, 0))
"""
alpha = cls.get_grey(tex, fontsize, dpi)
rgba = np.empty((*alpha.shape, 4))
rgba[..., :3] = mpl.colors.to_rgb(rgb)
rgba[..., -1] = alpha
return rgba
@classmethod
def get_text_width_height_descent(cls, tex, fontsize, renderer=None):
"""Return width, height and descent of the text."""
if tex.strip() == '':
return 0, 0, 0
dvifile = cls.make_dvi(tex, fontsize)
dpi_fraction = renderer.points_to_pixels(1.) if renderer else 1
with dviread.Dvi(dvifile, 72 * dpi_fraction) as dvi:
page, = dvi
# A total height (including the descent) needs to be returned.
return page.width, page.height + page.descent, page.descent