matplotlib.mathtext¶mathtext is a module for parsing a subset of the
TeX math syntax and drawing them to a matplotlib backend.
For a tutorial of its usage see Writing mathematical expressions. This document is primarily concerned with implementation details.
The module uses pyparsing to parse the TeX expression.
The Bakoma distribution of the TeX Computer Modern fonts, and STIX fonts are supported. There is experimental support for using arbitrary fonts, but results may vary without proper tweaking and metrics for those fonts.
matplotlib.mathtext.Accent(c, state, math=True)¶Bases: matplotlib.mathtext.Char
The font metrics need to be dealt with differently for accents, since they are already offset correctly from the baseline in TrueType fonts.
grow()¶render(x, y)¶Render the character to the canvas.
shrink()¶matplotlib.mathtext.AutoHeightChar(c, height, depth, state, always=False, factor=None)¶Bases: matplotlib.mathtext.Hlist
AutoHeightChar will create a character as close to the
given height and depth as possible. When using a font with
multiple height versions of some characters (such as the BaKoMa
fonts), the correct glyph will be selected, otherwise this will
always just return a scaled version of the glyph.
matplotlib.mathtext.AutoWidthChar(c, width, state, always=False, char_class=<class 'matplotlib.mathtext.Char'>)¶Bases: matplotlib.mathtext.Hlist
AutoWidthChar will create a character as close to the
given width as possible. When using a font with multiple width
versions of some characters (such as the BaKoMa fonts), the
correct glyph will be selected, otherwise this will always just
return a scaled version of the glyph.
matplotlib.mathtext.BakomaFonts(*args, **kwargs)¶Bases: matplotlib.mathtext.TruetypeFonts
Use the Bakoma TrueType fonts for rendering.
Symbols are strewn about a number of font files, each of which has its own proprietary 8-bit encoding.
alias = '\\]'¶get_sized_alternatives_for_symbol(fontname, sym)¶target = ']'¶matplotlib.mathtext.Box(width, height, depth)¶Bases: matplotlib.mathtext.Node
Represents any node with a physical location.
grow()¶render(x1, y1, x2, y2)¶shrink()¶matplotlib.mathtext.Char(c, state, math=True)¶Bases: matplotlib.mathtext.Node
Represents a single character. Unlike TeX, the font information
and metrics are stored with each Char to make it easier
to lookup the font metrics when needed. Note that TeX boxes have
a width, height, and depth, unlike Type1 and Truetype which use a
full bounding box and an advance in the x-direction. The metrics
must be converted to the TeX way, and the advance (if different
from width) must be converted into a Kern node when the
Char is added to its parent Hlist.
get_kerning(next)¶Return the amount of kerning between this and the given
character. Called when characters are strung together into
Hlist to create Kern nodes.
grow()¶is_slanted()¶render(x, y)¶Render the character to the canvas
shrink()¶matplotlib.mathtext.ComputerModernFontConstants¶Bases: matplotlib.mathtext.FontConstantsBase
delta = 0.075¶delta_integral = 0.3¶delta_slanted = 0.3¶script_space = 0.075¶sub1 = 0.2¶sub2 = 0.3¶subdrop = 0.2¶sup1 = 0.45¶matplotlib.mathtext.DejaVuFonts(*args, **kwargs)¶Bases: matplotlib.mathtext.UnicodeFonts
use_cmex = False¶matplotlib.mathtext.DejaVuSansFontConstants¶matplotlib.mathtext.DejaVuSansFonts(*args, **kwargs)¶Bases: matplotlib.mathtext.DejaVuFonts
A font handling class for the DejaVu Sans fonts
If a glyph is not found it will fallback to Stix Sans
matplotlib.mathtext.DejaVuSerifFontConstants¶matplotlib.mathtext.DejaVuSerifFonts(*args, **kwargs)¶Bases: matplotlib.mathtext.DejaVuFonts
A font handling class for the DejaVu Serif fonts
If a glyph is not found it will fallback to Stix Serif
matplotlib.mathtext.Error(msg)¶Helper class to raise parser errors.
matplotlib.mathtext.Fil¶Bases: matplotlib.mathtext.Glue
matplotlib.mathtext.Fill¶Bases: matplotlib.mathtext.Glue
matplotlib.mathtext.Filll¶Bases: matplotlib.mathtext.Glue
matplotlib.mathtext.FontConstantsBase¶Bases: object
A set of constants that controls how certain things, such as sub- and superscripts are laid out. These are all metrics that can’t be reliably retrieved from the font metrics in the font itself.
delta = 0.025¶delta_integral = 0.1¶delta_slanted = 0.2¶script_space = 0.05¶sub1 = 0.3¶sub2 = 0.5¶subdrop = 0.4¶sup1 = 0.7¶matplotlib.mathtext.Fonts(default_font_prop, mathtext_backend)¶Bases: object
An abstract base class for a system of fonts to use for mathtext.
The class must be able to take symbol keys and font file names and return the character metrics. It also delegates to a backend class to do the actual drawing.
default_font_prop: A
FontProperties object to use
for the default non-math font, or the base font for Unicode
(generic) font rendering.
mathtext_backend: A subclass of MathTextBackend
used to delegate the actual rendering.
destroy()¶Fix any cyclical references before the object is about to be destroyed.
get_kern(font1, fontclass1, sym1, fontsize1, font2, fontclass2, sym2, fontsize2, dpi)¶Get the kerning distance for font between sym1 and sym2.
fontX: one of the TeX font names:
tt, it, rm, cal, sf, bf or default/regular (non-math)
fontclassX: TODO
symX: a symbol in raw TeX form. e.g., ‘1’, ‘x’ or ‘sigma’
fontsizeX: the fontsize in points
dpi: the current dots-per-inch
get_metrics(font, font_class, sym, fontsize, dpi, math=True)¶font: one of the TeX font names:
tt, it, rm, cal, sf, bf or default/regular (non-math)
font_class: TODO
sym: a symbol in raw TeX form. e.g., ‘1’, ‘x’ or ‘sigma’
fontsize: font size in points
dpi: current dots-per-inch
math: whether sym is a math character
Returns an object with the following attributes:
- advance: The advance distance (in points) of the glyph.
- height: The height of the glyph in points.
- width: The width of the glyph in points.
- xmin, xmax, ymin, ymax - the ink rectangle of the glyph
- iceberg - the distance from the baseline to the top of the glyph. This corresponds to TeX’s definition of “height”.
get_results(box)¶Get the data needed by the backend to render the math expression. The return value is backend-specific.
get_sized_alternatives_for_symbol(fontname, sym)¶Override if your font provides multiple sizes of the same symbol. Should return a list of symbols matching sym in various sizes. The expression renderer will select the most appropriate size for a given situation from this list.
get_underline_thickness(font, fontsize, dpi)¶Get the line thickness that matches the given font. Used as a base unit for drawing lines such as in a fraction or radical.
get_used_characters()¶Get the set of characters that were used in the math expression. Used by backends that need to subset fonts so they know which glyphs to include.
get_xheight(font, fontsize, dpi)¶Get the xheight for the given font and fontsize.
render_glyph(ox, oy, facename, font_class, sym, fontsize, dpi)¶Draw a glyph at
- ox, oy: position
- facename: One of the TeX face names
- font_class:
- sym: TeX symbol name or single character
- fontsize: fontsize in points
- dpi: The dpi to draw at.
render_rect_filled(x1, y1, x2, y2)¶Draw a filled rectangle from (x1, y1) to (x2, y2).
set_canvas_size(w, h, d)¶Set the size of the buffer used to render the math expression. Only really necessary for the bitmap backends.
matplotlib.mathtext.Glue(glue_type, copy=False)¶Bases: matplotlib.mathtext.Node
Most of the information in this object is stored in the underlying
GlueSpec class, which is shared between multiple glue objects. (This
is a memory optimization which probably doesn’t matter anymore, but it’s
easier to stick to what TeX does.)
grow()¶shrink()¶matplotlib.mathtext.GlueSpec(width=0.0, stretch=0.0, stretch_order=0, shrink=0.0, shrink_order=0)¶Bases: object
See Glue.
copy()¶factory(glue_type)¶matplotlib.mathtext.HCentered(elements)¶Bases: matplotlib.mathtext.Hlist
A convenience class to create an Hlist whose contents are
centered within its enclosing box.
matplotlib.mathtext.Hbox(width)¶Bases: matplotlib.mathtext.Box
A box with only width (zero height and depth).
matplotlib.mathtext.Hlist(elements, w=0.0, m='additional', do_kern=True)¶Bases: matplotlib.mathtext.List
A horizontal list of boxes.
hpack(w=0.0, m='additional')¶The main duty of hpack() is to compute the dimensions of
the resulting boxes, and to adjust the glue if one of those
dimensions is pre-specified. The computed sizes normally
enclose all of the material inside the new box; but some items
may stick out if negative glue is used, if the box is
overfull, or if a \vbox includes other boxes that have
been shifted left.
- w: specifies a width
- m: is either ‘exactly’ or ‘additional’.
Thus, hpack(w, 'exactly') produces a box whose width is
exactly w, while hpack(w, 'additional') yields a box
whose width is the natural width plus w. The default values
produce a box with the natural width.
kern()¶Insert Kern nodes between Char nodes to set
kerning. The Char nodes themselves determine the
amount of kerning they need (in get_kerning()),
and this function just creates the linked list in the correct
way.
matplotlib.mathtext.Hrule(state, thickness=None)¶Bases: matplotlib.mathtext.Rule
Convenience class to create a horizontal rule.
matplotlib.mathtext.Kern(width)¶Bases: matplotlib.mathtext.Node
A Kern node has a width field to specify a (normally
negative) amount of spacing. This spacing correction appears in
horizontal lists between letters like A and V when the font
designer said that it looks better to move them closer together or
further apart. A kern node can also appear in a vertical list,
when its width denotes additional spacing in the vertical
direction.
depth = 0¶grow()¶height = 0¶shrink()¶matplotlib.mathtext.List(elements)¶Bases: matplotlib.mathtext.Box
A list of nodes (either horizontal or vertical).
grow()¶shrink()¶matplotlib.mathtext.MathTextParser(output)¶Bases: object
Create a MathTextParser for the given backend output.
get_depth(texstr, dpi=120, fontsize=14)¶Returns the offset of the baseline from the bottom of the image in pixels.
parse(s, dpi=72, prop=None)¶Parse the given math expression s at the given dpi. If
prop is provided, it is a
FontProperties object
specifying the “default” font to use in the math expression,
used for all non-math text.
The results are cached, so multiple calls to parse()
with the same expression should be fast.
to_mask(texstr, dpi=120, fontsize=14)¶Returns a tuple (array, depth)
- array is an NxM uint8 alpha ubyte mask array of rasterized tex.
- depth is the offset of the baseline from the bottom of the image in pixels.
to_png(filename, texstr, color='black', dpi=120, fontsize=14)¶Writes a tex expression to a PNG file.
Returns the offset of the baseline from the bottom of the image in pixels.
Returns the offset of the baseline from the bottom of the image in pixels.
to_rgba(texstr, color='black', dpi=120, fontsize=14)¶Returns a tuple (array, depth)
- array is an NxM uint8 alpha ubyte mask array of rasterized tex.
- depth is the offset of the baseline from the bottom of the image in pixels.
matplotlib.mathtext.MathTextWarning¶Bases: Warning
matplotlib.mathtext.MathtextBackend¶Bases: object
The base class for the mathtext backend-specific code. The
purpose of MathtextBackend subclasses is to interface
between mathtext and a specific matplotlib graphics backend.
Subclasses need to override the following:
And optionally, if you need to use a FreeType hinting style:
get_hinting_type()¶Get the FreeType hinting type to use with this particular backend.
get_results(box)¶Return a backend-specific tuple to return to the backend after all processing is done.
render_glyph(ox, oy, info)¶Draw a glyph described by info to the reference point (ox, oy).
render_rect_filled(x1, y1, x2, y2)¶Draw a filled black rectangle from (x1, y1) to (x2, y2).
set_canvas_size(w, h, d)¶Dimension the drawing canvas
matplotlib.mathtext.MathtextBackendAgg¶Bases: matplotlib.mathtext.MathtextBackend
Render glyphs and rectangles to an FTImage buffer, which is later transferred to the Agg image by the Agg backend.
get_hinting_type()¶get_results(box, used_characters)¶render_glyph(ox, oy, info)¶render_rect_filled(x1, y1, x2, y2)¶set_canvas_size(w, h, d)¶matplotlib.mathtext.MathtextBackendBitmap¶Bases: matplotlib.mathtext.MathtextBackendAgg
get_results(box, used_characters)¶matplotlib.mathtext.MathtextBackendCairo¶Bases: matplotlib.mathtext.MathtextBackend
Store information to write a mathtext rendering to the Cairo backend.
get_results(box, used_characters)¶render_glyph(ox, oy, info)¶render_rect_filled(x1, y1, x2, y2)¶matplotlib.mathtext.MathtextBackendPath¶Bases: matplotlib.mathtext.MathtextBackend
Store information to write a mathtext rendering to the text path machinery.
get_results(box, used_characters)¶render_glyph(ox, oy, info)¶render_rect_filled(x1, y1, x2, y2)¶matplotlib.mathtext.MathtextBackendPdf¶Bases: matplotlib.mathtext.MathtextBackend
Store information to write a mathtext rendering to the PDF backend.
get_results(box, used_characters)¶render_glyph(ox, oy, info)¶render_rect_filled(x1, y1, x2, y2)¶matplotlib.mathtext.MathtextBackendPs¶Bases: matplotlib.mathtext.MathtextBackend
Store information to write a mathtext rendering to the PostScript backend.
get_results(box, used_characters)¶render_glyph(ox, oy, info)¶render_rect_filled(x1, y1, x2, y2)¶matplotlib.mathtext.MathtextBackendSvg¶Bases: matplotlib.mathtext.MathtextBackend
Store information to write a mathtext rendering to the SVG backend.
get_results(box, used_characters)¶render_glyph(ox, oy, info)¶render_rect_filled(x1, y1, x2, y2)¶matplotlib.mathtext.NegFil¶Bases: matplotlib.mathtext.Glue
matplotlib.mathtext.NegFill¶Bases: matplotlib.mathtext.Glue
matplotlib.mathtext.NegFilll¶Bases: matplotlib.mathtext.Glue
matplotlib.mathtext.Node¶Bases: object
A node in the TeX box model
get_kerning(next)¶grow()¶Grows one level larger. There is no limit to how big something can get.
render(x, y)¶shrink()¶Shrinks one level smaller. There are only three levels of sizes, after which things will no longer get smaller.
matplotlib.mathtext.Parser¶Bases: object
This is the pyparsing-based parser for math expressions. It
actually parses full strings containing math expressions, in
that raw text may also appear outside of pairs of $.
The grammar is based directly on that in TeX, though it cuts a few corners.
State(font_output, font, font_class, fontsize, dpi)¶Bases: object
Stores the state of the parser.
States are pushed and popped from a stack as necessary, and the “current” state is always at the top of the stack.
copy()¶font¶Parser.accent(s, loc, toks)¶Parser.auto_delim(s, loc, toks)¶Parser.binom(s, loc, toks)¶Parser.c_over_c(s, loc, toks)¶Parser.customspace(s, loc, toks)¶Parser.end_group(s, loc, toks)¶Parser.font(s, loc, toks)¶Parser.frac(s, loc, toks)¶Parser.function(s, loc, toks)¶Parser.genfrac(s, loc, toks)¶Parser.group(s, loc, toks)¶Parser.is_between_brackets(s, loc)¶Parser.is_dropsub(nucleus)¶Parser.is_overunder(nucleus)¶Parser.is_slanted(nucleus)¶Parser.main(s, loc, toks)¶Parser.math(s, loc, toks)¶Parser.math_string(s, loc, toks)¶Parser.non_math(s, loc, toks)¶Parser.operatorname(s, loc, toks)¶Parser.overline(s, loc, toks)¶Parser.parse(s, fonts_object, fontsize, dpi)¶Parse expression s using the given fonts_object for output, at the given fontsize and dpi.
Returns the parse tree of Node instances.
Parser.required_group(s, loc, toks)¶Parser.simple_group(s, loc, toks)¶Parser.snowflake(s, loc, toks)¶Parser.space(s, loc, toks)¶Parser.sqrt(s, loc, toks)¶Parser.stackrel(s, loc, toks)¶Parser.start_group(s, loc, toks)¶Parser.subsuper(s, loc, toks)¶Parser.symbol(s, loc, toks)¶Parser.unknown_symbol(s, loc, toks)¶matplotlib.mathtext.Rule(width, height, depth, state)¶Bases: matplotlib.mathtext.Box
A Rule node stands for a solid black rectangle; it has
width, depth, and height fields just as in an
Hlist. However, if any of these dimensions is inf, the
actual value will be determined by running the rule up to the
boundary of the innermost enclosing box. This is called a “running
dimension.” The width is never running in an Hlist; the
height and depth are never running in a Vlist.
render(x, y, w, h)¶matplotlib.mathtext.STIXFontConstants¶Bases: matplotlib.mathtext.FontConstantsBase
delta = 0.05¶delta_integral = 0.3¶delta_slanted = 0.3¶script_space = 0.1¶sub2 = 0.6¶sup1 = 0.8¶matplotlib.mathtext.STIXSansFontConstants¶Bases: matplotlib.mathtext.FontConstantsBase
delta_integral = 0.3¶delta_slanted = 0.6¶script_space = 0.05¶sup1 = 0.8¶matplotlib.mathtext.Ship¶Bases: object
Once the boxes have been set up, this sends them to output. Since
boxes can be inside of boxes inside of boxes, the main work of
Ship is done by two mutually recursive routines,
hlist_out() and vlist_out(), which traverse the
Hlist nodes and Vlist nodes inside of horizontal
and vertical boxes. The global variables used in TeX to store
state as it processes have become member variables here.
clamp(value)¶hlist_out(box)¶vlist_out(box)¶matplotlib.mathtext.SsGlue¶Bases: matplotlib.mathtext.Glue
matplotlib.mathtext.StandardPsFonts(default_font_prop)¶Bases: matplotlib.mathtext.Fonts
Use the standard postscript fonts for rendering to backend_ps
Unlike the other font classes, BakomaFont and UnicodeFont, this one requires the Ps backend.
basepath = '/tmp/mpl_clean/lib/python3.6/site-packages/matplotlib/mpl-data/fonts/afm'¶fontmap = {'cal': 'pzcmi8a', 'rm': 'pncr8a', 'tt': 'pcrr8a', 'it': 'pncri8a', 'sf': 'phvr8a', 'bf': 'pncb8a', None: 'psyr'}¶get_kern(font1, fontclass1, sym1, fontsize1, font2, fontclass2, sym2, fontsize2, dpi)¶get_underline_thickness(font, fontsize, dpi)¶get_xheight(font, fontsize, dpi)¶matplotlib.mathtext.StixFonts(*args, **kwargs)¶Bases: matplotlib.mathtext.UnicodeFonts
A font handling class for the STIX fonts.
In addition to what UnicodeFonts provides, this class:
cm_fallback = False¶get_sized_alternatives_for_symbol(fontname, sym)¶use_cmex = False¶matplotlib.mathtext.StixSansFonts(*args, **kwargs)¶Bases: matplotlib.mathtext.StixFonts
A font handling class for the STIX fonts (that uses sans-serif characters by default).
matplotlib.mathtext.SubSuperCluster¶Bases: matplotlib.mathtext.Hlist
SubSuperCluster is a sort of hack to get around that fact
that this code do a two-pass parse like TeX. This lets us store
enough information in the hlist itself, namely the nucleus, sub-
and super-script, such that if another script follows that needs
to be attached, it can be reconfigured on the fly.
matplotlib.mathtext.TruetypeFonts(default_font_prop, mathtext_backend)¶Bases: matplotlib.mathtext.Fonts
A generic base class for all font setups that use Truetype fonts (through FT2Font).
destroy()¶get_kern(font1, fontclass1, sym1, fontsize1, font2, fontclass2, sym2, fontsize2, dpi)¶get_underline_thickness(font, fontsize, dpi)¶get_xheight(fontname, fontsize, dpi)¶matplotlib.mathtext.UnicodeFonts(*args, **kwargs)¶Bases: matplotlib.mathtext.TruetypeFonts
An abstract base class for handling Unicode fonts.
While some reasonably complete Unicode fonts (such as DejaVu) may work in some situations, the only Unicode font I’m aware of with a complete set of math symbols is STIX.
This class will “fallback” on the Bakoma fonts when a required symbol can not be found in the font.
get_sized_alternatives_for_symbol(fontname, sym)¶use_cmex = True¶matplotlib.mathtext.VCentered(elements)¶Bases: matplotlib.mathtext.Hlist
A convenience class to create a Vlist whose contents are
centered within its enclosing box.
matplotlib.mathtext.Vbox(height, depth)¶Bases: matplotlib.mathtext.Box
A box with only height (zero width).
matplotlib.mathtext.Vlist(elements, h=0.0, m='additional')¶Bases: matplotlib.mathtext.List
A vertical list of boxes.
vpack(h=0.0, m='additional', l=inf)¶The main duty of vpack() is to compute the dimensions of
the resulting boxes, and to adjust the glue if one of those
dimensions is pre-specified.
- h: specifies a height
- m: is either ‘exactly’ or ‘additional’.
- l: a maximum height
Thus, vpack(h, 'exactly') produces a box whose height is
exactly h, while vpack(h, 'additional') yields a box
whose height is the natural height plus h. The default
values produce a box with the natural width.
matplotlib.mathtext.Vrule(state)¶Bases: matplotlib.mathtext.Rule
Convenience class to create a vertical rule.
matplotlib.mathtext.get_unicode_index(symbol[, bool]) → integer¶Return the integer index (from the Unicode table) of symbol. symbol can be a single unicode character, a TeX command (i.e. r’pi’), or a Type1 symbol name (i.e. ‘phi’). If math is False, the current symbol should be treated as a non-math symbol.
matplotlib.mathtext.math_to_image(s, filename_or_obj, prop=None, dpi=None, format=None)¶Given a math expression, renders it in a closely-clipped bounding box to an image file.
matplotlib.mathtext.unichr_safe(index)¶Return the Unicode character corresponding to the index, or the replacement character if this is a narrow build of Python and the requested character is outside the BMP.