|
matplotlib backends
The matplotlib core graphics routines interact with an abstract renderer and graphics context to allow device independent ouput. Currently, output to pygtk, wxPython, Tkinter, postscript, pdf, svg, agg (antigrain geometry) and Cairo are supported. With not too much effort, you can port matplotlib to your favorite display. If you are interested in porting to one of these platforms, please contact the matplotlib-devel mailing list.Comparison of backends
The following table enumerates the capabilities of the different backends.
| output formats | rotated text | mathtext | usetex | alpha-blending |
arbitrary clipping (polar plots) |
images | |
| Agg | png, raw | X | X | X | X | X | X |
| Cairo | pdf, png,ps, svg, svgz | X | X | X | |||
| CocoaAgg | png, raw | X | X | X | X | X | X |
| Emf | emf | ? | ? | ? | ? | ? | |
| FltkAgg | png, raw | X | X | X | X | X | X |
| Gtk (Gdk) | jpeg, png, raw | X | X | ||||
| GtkAgg | jpeg, png, raw | X | X | X | X | X | X |
| GtkCairo | jpeg, pdf, png, ps, svg, svgz | X | X | X | |||
| X | X | X | X | X | X | ||
| Ps | eps,ps | X | X | X | X | ||
| QtAgg | png,raw | X | X | X | X | X | X |
| Qt4Agg | png,raw | X | X | X | X | X | X |
| Svg | svg, svgz | X | X | X | X | ||
| TkAgg | png,raw | X | X | X | X | X | X |
| Wx | bmp, jpeg, pcx, png, raw, tiff, xpm | ||||||
| WxAgg | png,raw | X | X | X | X | X | X |
In addition to these factors, there are other factors that may affect your backend selection:
- Scalability: For print, the ability to scale the image to any resolution is important. Postscript, Pdf and Svg are good candidates for this. Which will work best for you depends on the publication tools you are using.
- Speed: When running locally, the Agg-related backends are likely to be the fastest since most of Agg is renderered in C extension code, and most of the optimization effort has been dedicated to it. However, when running X11 remotely, the Gtk and Wx backends may be faster since they send high-level X commands over the network rather than pixel data.
- Interactivity: All of the GUI backends can be used interactively from a python shell (see interactive) but TkAgg is the hands-down winner here since it can be use from any python shell whereas the GTK and Wx backends require a GUI specific shell.
- Pretty widgets: If you want to embed matplotlib in an application and pretty GUIs are important to you, Wx, GTK, GTKAgg or GTKCairo are probably your best best. Tk and Fltk widgets are not visually stunning.
Choosing a backend
You can choose your default backend in the matplotlibrc file, using the 'backend' option. The default can be overridden from the command line prompt. This allows most if not all matplotlib scripts to generate output to any of the backends without any alterations. Following the lead of the matlab print command, the backend can be chosen from the command line with the -d flag, as in# the GUI backends > python subplot_demo.py -dGTK # GTK GUI with gdk drawing > python subplot_demo.py -dGTKAgg # GTK GUI with antigrain rendering > python subplot_demo.py -dGTKCairo # GTK GUI with Cairo rendering > python subplot_demo.py -dTkAgg # Tkinter GUI with antigrain rendering > python subplot_demo.py -dWX # WX backend > python subplot_demo.py -dWXAgg # WX GUI with antigrain rendering # The image backends, no window pops up; you must call savefig > python subplot_demo.py -dAgg # antigrain geometry backend image > python subplot_demo.py -dCairo # Cairo backend > python subplot_demo.py -dPS # postscript backend > python subplot_demo.py -dPDF # pdf backend > python subplot_demo.py -dSVG # SVG backendFor backends that do not have a GUI, no output will be produced unless a call to savefig is made. The recommended way to use the savefig function is to not give an extension. The backends will choose the proper extension. This allows you to write a single script and select the output format from the command line. So a script containing savefig('somefile') will create somefile.ps if called with -dPS and somefile.png if called with -dAgg, and so on.
Alternatively, you can select the backend renderer in your script by calling the matplotlib use function. At the top of your script (before you import matplotlib.pylab, just do, for example
import matplotlib
matplotlib.use('PS')
The current backend strings that are supported are
Agg, Cairo, FltkAgg, GTK, GTKAgg, GTKCairo, PS, PDF, SVG, TkAgg, WX, WXAgg, Template.
The default is GTKAgg. Template is a do nothing backend that serves as a
template for backend writers (volunteers welcome!).To get the most of your backend of choice, you may need to set an environment variable controlling the fonts; see fonts for more information.
Backend requirements
Each of the backends have a different set of requirements, listed below. All require numpy modules. Specific information for installing the other backends can be found on this page below or by clickingAgg
The antigrain geometry library is a platform independent library that provides efficient antialiased rendering with a vector model. Because it doesn't depend on a GUI framework, it is suitable for use in web application servers generating images for html inclusion or for generating images in batch scripts. Agg can also be embedded in GUI applications, as in the GTKAgg and TkAgg backends -- see setup.py
matplotlib includes its own copy of Agg. It does not need to be
installed separately, even if compiling matplotlib from source.
Cairo
Cairo is a vector graphics
library designed to provide high-quality display and print output.
It doesn't depend on a GUI framework and is suitable for use in web
application servers generating images for html inclusion or for generating
images in batch scripts. Cairo can also be embedded in GUI applications, as in
the GTKCairo backend
It requires pycairo version 0.5.0 or higher from
Cairo downloads
GTK
This was the first backend supported by matplotlib; it requires
- numpy
- GTK runtime
- pygtk version 2.0.0 or later
Windows GTK Quickstart
These install instructions will provide the GTK and GTKAgg backends on windows. If you encounter troubles, please see the FAQ- Install numpy. If you are using the enthought edition of python, you can skip this step.
- Install the GTK runtime (currently version 2.2.4.1). I recommend not using the default install location as it makes it difficult to set your path; use C:\GTk instead
- Install pygtk-2.2.0
- Modify your path. Check this FAQ entry for information on how to do this right.
- Install matplotlib using the windows installer on the download page
WX
Requires wxpython. Windows users may want to consider the enthought edition of python, which comes with wxpython and numpy built in, so matplotlib will work right out of the box. matplotlib under WX has been tested on linux, win32 and OSX.
WXAgg
Requires wxpython. Windows users
may want to consider the enthought edition of python,
which comes with wxpython and numpy built in, so matplotlib will
work right out of the box. matplotlib under WXAgg has been tested on
linux, win32 and OSX.
GTKAgg: GTK GUI with antigrain rendering
GTK has a very nice and portable widget set. The gdk drawing
commands, while fast, are somewhat limited. To overcome this
limitation, GTKAgg marries the widgets of GTK with the rendering of antigrain. You need the agg and gtk
prerequisites. Agg is builtin, so you only need to
install pygtk and the GTK runtime, as described in gtk.
GTKCairo
GTKCairo uses Cairo rendering from within the GTK GUI.
You need the Cairo and gtk
prerequisites.
Tkinter GUI backend
Todd Miller has written a backend for Tkinter that uses the agg
backend for rendering. To use Tkagg, you need to set the BUILD_TKAGG
flag in setup.py. The windows installer comes with TkAgg prebuilt.
See agg backend for more information on
agg rendering and fonts. NOTE: on at least some versions of redhat
linux, you must install a separate tkinter package, apparently
tkinter-2.2.2-26.i386.rpm on Red Hat 9 linux. Alternately, Python
built from source code (Python.org tarball, not the redhat SRPM)
includes Tkinter support by default on Red Hat Linux.
In general, TkAgg is known to work with
- python
- idle -n (set tk.PYTHONINSPECT : True in matplotlibrc
- IPython
- SciTE
- pythonw
- Pythonwin
- idle
I also looked into SciTE a little and discovered that it is related to Scintilla which in turn was derived from Pythonwin. scintilla This indicates to me that the same problem with Tkinter may be affecting both (SciTE and Pythonwin)... but I am out on a limb.
Postscript
The only requirement is numpy.
See the fonts page for more information
about getting the postscript backend setup for proper font rendering;
notably, you must make sure there are some '*.afm' files in your
AFMPATH if you want to use fonts other than the ones that
ship with matplotlib.
PDF
The only requirement is numpy.
SVG
The only requirement is numpy.