mplcairo 0.4

Unix

The following additional dependencies are required:

• a C++ compiler with C++17 support, e.g. GCC≥7.2 or Clang≥5.0.

• cairo and FreeType headers, and pkg-config information to locate them.

  If using conda, they can be installed using

  conda install -y -c conda-forge pycairo pkg-config

  as pycairo (also a dependency) depends on cairo, which depends on freetype. Note that cairo and pkg-config from the anaconda channel will not work.

  On Linux, they can also be installed with your distribution’s package manager (Arch: cairo, Debian/Ubuntu: libcairo2-dev, Fedora: cairo-devel).

Raqm (≥0.2) headers are also needed, but will be automatically downloaded if not found.

Windows

The following additional dependencies are required:

• VS2019 (The exact minimum version is unknown, but it is known that mplcairo fails to build on the Azure vs2017-win2016 agent and requires the windows-2019 agent.)

• cairo headers and import and dynamic libraries (cairo.lib and cairo.dll) with FreeType support. Note that this excludes, in particular, most Anaconda and conda-forge builds: they do not include FreeType support.

  The currently preferred solution is to get the headers e.g. from a Linux distribution package, the DLL from Christoph Gohlke’s pycairo build, and generate the import library oneself using dumpbin and lib.

  Alternatively, very recent conda-forge builds (≥1.16.0 build 1005) do include FreeType support. In order to use them, the include path needs to be modified as described below. (This is currently intentionally disabled by default to avoid confusing errors if the cairo build is too old.)

• FreeType headers and import and dynamic libraries (freetype.lib and freetype.dll), which can be retrieved from https://github.com/ubawurinna/freetype-windows-binaries, or alternatively using conda:

  conda install -y freetype

The (standard) CL and LINK environment variables (which always get prepended respectively to the invocations of the compiler and the linker) should be set as follows:

set CL=/IC:\path\to\dir\containing\cairo.h /IC:\same\for\ft2build.h
set LINK=/LIBPATH:C:\path\to\dir\containing\cairo.lib /LIBPATH:C:\same\for\freetype.lib

In particular, in order to use a conda-forge cairo (as described above), {sys.prefix}\Library\include\cairo needs to be added to the include path.

Moreover, we also need to find cairo.dll and freetype.dll and copy them next to mplcairo’s extension module. As the dynamic libraries are typically found next to import libraries, we search the /LIBPATH: entries in the LINK environment variable and copy the first cairo.dll and freetype.dll found there.

The script tools/build-windows-wheel.py automates the retrieval of the cairo (assuming that a Gohlke pycairo is already installed) and FreeType dlls, and the wheel build.

Antialiasing

The artist antialiasing property can be set to any of the cairo_antialias_t enum values, or True (the default) or False (which is synonym to NONE).

Setting antialiasing to True uses FAST antialiasing for lines thicker than 1/3px and BEST for lines thinner than that: for lines thinner than 1/3px, the former leads to artefacts such as lines disappearing in certain sections (see e.g. test_cycles.test_property_collision_plot after forcing the antialiasing to FAST). The threshold of 1/3px was determined empirically, see examples/thin_line_antialiasing.py.

Note that in order to set the lines.antialiased or patch.antialiased rcparams to a cairo_antialias_t enum value, it is necessary to bypass rcparam validation, using, e.g.

dict.__setitem__(plt.rcParams, "lines.antialiased", antialias_t.FAST)

The text.antialiased rcparam can likewise be set to any cairo_antialias_t enum value, or True (the default, which maps to SUBPIXEL — GRAY is not sufficient to benefit from Raqm’s subpixel positioning; see also cairo issue #152) or False (which maps to NONE).

Note that in rare cases, FAST antialiasing can trigger a “double free or corruption” bug in cairo (#44). If you hit this problem, consider using BEST or NONE antialiasing (depending on your quality and speed requirements).

Fast drawing

For fast drawing of path with many segments, the agg.path.chunksize rcparam should be set to e.g. 1000 (see examples/time_drawing_per_element.py for the determination of this value); this causes longer paths to be split into individually rendered sections of 1000 segments each (directly rendering longer paths appears to have slightly superlinear complexity).

Simplification threshold

The path.simplify_threshold rcparam is used to control the accuracy of marker stamping, down to an arbitrarily chosen threshold of 1/16px. If the threshold is set to a lower value, the exact (slower) marker drawing path will be used. Marker stamping is also implemented for scatter plots (which can have multiple colors). Likewise, markers of different sizes get mapped into markers of discretized sizes, with an error bounded by the threshold.

NOTE: pcolor and mplot3d’s plot_surface display some artifacts where the facets join each other. This is because these functions internally use a PathCollection; this triggers the approximate stamping, and even without it (by setting path.simplify_threshold to zero), cairo’s rasterization of the edge between the facets is poor. pcolormesh (which internally uses a QuadMesh) should generally be preferred over pcolor anyways. plot_surface could likewise instead represent the surface using QuadMesh, which is drawn without such artefacts.

Font formats and features

In order to use a specific font that Matplotlib may be unable to use, pass a filename directly:

from matplotlib.font_manager import FontProperties
fig.text(.5, .5, "hello, world",
         fontproperties=FontProperties(fname="/path/to/font.ttf"))

or more simply, with Matplotlib≥3.3:

from pathlib import Path
fig.text(.5, .5, "hello, world", font=Path("/path/to/font.ttf"))

mplcairo still relies on Matplotlib’s font cache, so fonts unsupported by Matplotlib remain unavailable by other means.

For TTC fonts (and, more generally, font formats that include multiple font faces in a single file), the nth font (n≥0) can be selected by appending #n to the filename (e.g., "/path/to/font.ttc#1").

OpenType font features can be selected by appending |feature,... to the filename, followed by a HarfBuzz feature string (e.g., "/path/to/font.otf|frac,onum"); see examples/opentype_features.py.

The syntaxes for selecting TTC subfonts and OpenType font features are experimental and may change, especially if such features are implemented in Matplotlib itself.

Color fonts (e.g. emojis) are handled, but emojis that rely on ligatures (1, 2) run into limitations of HarfBuzz and are currently rendered correctly only if they are the only glyph in the rendered string.

Note that Matplotlib’s (default) Agg backend will handle most single-face monochrome fonts equally well (ultimately, both backends relies on FreeType for rasterization). It is Matplotlib’s vector backends (PS, PDF, and, for pfb fonts, SVG) that do not support these fonts, whereas mplcairo support these fonts in all output formats.

Multi-page output

Matplotlib’s PdfPages class is deeply tied with the builtin backend_pdf (in fact, it cannot even be used with Matplotlib’s own cairo backend). Instead, use mplcairo.multipage.MultiPage for multi-page PDF and PS output. The API is similar:

from mplcairo.multipage import MultiPage

fig1 = ...
fig2 = ...
with MultiPage(path_or_stream, metadata=...) as mp:
    mp.savefig(fig1)
    mp.savefig(fig2)

See the class’ docstring for additional information.

cairo-script output

Setting the MPLCAIRO_SCRIPT_SURFACE environment variable before mplcairo is imported to vector or raster allows one to save figures (with savefig) in the .cairoscript format, which is a “native script that matches the cairo drawing model”. The value of the variable determines the rendering path used (e.g., whether marker stamping is used at all). This may be helpful for troubleshooting purposes.

Note that this may crash the process after the file is written, due to cairo issue #277.

Markers at Bézier control points

draw_markers draws a marker at each control point of the given path, which is the documented behavior, even though all builtin renderers only draw markers at straight or Bézier segment ends.