matplotlib Code

371 lines (273 with data), 14.1 kB

@header@ 

<h2>matplotlib backends</h2>

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, gdmodule,
libart/paint, svg, agg (antigrain geometry) and Cairo are supported.  With
not too much effort, you can port matplotlib to your favorite display;
high on my list of priorities are PDF and PIL.  If you are interested
in porting to one of these platforms, please contact me!<p>

For a summary of the comparative strengths and features of the various
backends, see <a href=faq.html#WHICHBACKEND>which backend should I
use?</a>.  This page describes how to install and use each backend.<p>
 
You can choose your default backend in the <a
href=matplotlibrc>matplotlibrc</a> file. The default can be
overridden from the command line prompt.  This allows most if not all
matplotlib scripts can generate output to any of the backends without
any alterations.  Following the lead of the matlab <tt>print</tt>
command, the backend can be chosen from the command line with the
<tt>-d</tt> flag, as in

<pre>
# 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 -dSVG     # SVG backend
> python subplot_demo.py -dGD      # GD backend
> python subplot_demo.py -dPaint   # Paint backend
> python subplot_demo.py -dEMF     # EMF backend
</pre>


For backends that do not have a GUI, no output will be produced unless
a call to <a href=matplotlib.pylab.html#-savefig>savefig</a> 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 <tt>savefig('somefile')</tt>
will create <tt>somefile.ps</tt> if called with <tt>-dPS</tt> and
<tt>somefile.png</tt> if called with <tt>-dGD</tt>, and so on.<p>

Alternatively, you can select the backend renderer in your script by
calling the matplotlib <a href=matplotlib.pylab.html#-use>use</a>
function.  At the top of your script (before you <tt>import
matplotlib.pylab</tt>, just do, for example

<pre>
import matplotlib
matplotlib.use('PS')
</pre>

The current backend strings that are supported are 
<a
href=matplotlib.backends.backend_agg.html>Agg</a>, <a
href=matplotlib.backends.backend_cairo.html>Cairo</a>, <a
href=matplotlib.backends.backend_gtk.html>GTK</a>, <a
href=matplotlib.backends.backend_gtkagg.html>GTKAgg</a>, <a
href=matplotlib.backends.backend_gtkcairo.html>GTKCairo</a>, <a
href=matplotlib.backends.backend_ps.html>PS</a>, <a
href=matplotlib.backends.backend_tkagg.html>TkAgg</a>, <a
href=matplotlib.backends.backend_wx.html>WX</a>, <a
href=matplotlib.backends.backend_wxagg.html>WXAgg</a>, <a
href=matplotlib.backends.backend_paint.html>Paint</a>, <a
href=matplotlib.backends.backend_gd.html>GD</a>, <a
href=matplotlib.backends.backend_emf.html>EMF</a> and <a
href=matplotlib.backends.backend_template.html>Template</a>.

The default is GTKAgg.  Template is a do nothing backend that serves as a
template for backend writers (volunteers welcome!).<p>

To get the most of your backend of choice, you may need to set an
environment variable controlling the fonts; see <a
href="fonts.html">fonts</a> for more information.<p>

<h2>Backend requirements</h2>

Each of the backends have a different set of requirements, listed
below.  All require the <a
href=http://sourceforge.net/projects/numpy>Numeric or numarray</a>
modules.  Note, matplotlib can also be made to work with numarray with
minor changes; see the <a href=faq.html#NUMARRAY>FAQ</a>.<p>


Specific information for installing the other backends can be found on
this page below or by clicking
<ul>
<li><a href=backends.html#Agg>Agg</a></li>
<li><a href=backends.html#Cairo>Cairo</a></li>
<li><a href=backends.html#TkAgg>TkAgg</a></li>
<li><a href=backends.html#GTK>GTK</a></li>
<li><a href=backends.html#GTKAgg>GTKAgg</a></li>
<li><a href=backends.html#GTKCairo>GTKCairo</a></li>
<li><a href=backends.html#WX>WX</a></li>
<li><a href=backends.html#WXAgg>WXAgg</a></li>
<li><a href=backends.html#PS>PS</a></li>
<li><a href=backends.html#Paint>Paint</a></li>
<li><a href=backends.html#GD>GD</a></li>
<li><a href=backends.html#EMF>EMF</a></li>
</ul>


<a name=Agg><h3>Agg</h3></a>

The <a href=http://antigrain.com>antigrain geometry</a> 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 <tt>setup.py</tt><p>

The windows installer comes with Agg prebuilt.  For other platforms,
to compile Agg from src, set the <tt>BUILD_AGG</tt> flag in
<tt>setup.py</tt>.  

<a name=Cairo><h3>Cairo</h3></a>

<a href=http://cairographics.org>Cairo</a> 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<p>

It requires pycairo version 0.5.0 or higher from 
<a href=http://www.freedesktop.org/Cairo/download>Cairo downloads</a>


<a name=GTK><h3>GTK</h3></a>

This was the first backend supported by matplotlib; it requires

<ul> 

  <li><a href=http://www.pfdubois.com/numpy>Numeric/numarray</a></li>

  <li><a href=http://prdownloads.sourceforge.net/gtk-win>
GTK runtime</a></li> 

  <li><a href=http://www.pygtk.org>pygtk</a>
  version 2.0.0 or later</li>

</ul>

<h4>Redhat Users</h4>

  GTK2 became the default with the Redhat Linux 8 series.  If your
  distro is older than that, you'll need to upgrade your desktop,
  upgrade your gtk libs, or upgrade your distro.<p>

  I am not sure what the status of GTK2 versus version number is with
  the other distros, but I would be happy for answers, so if you know,
  please email me @myemail@.  If you put matplotlib in the subject,
  the email will be sure to get past my spam filters.<p>


<h2> Windows GTK Quickstart</h2>

These install instructions will provide the <a
href=backends.html#GTK>GTK<a/> and <a
href=backends.html#GTKAgg>GTK<a/>GTKAgg</a> backends on windows.  If
you encounter troubles, please see <a
href=http://matplotlib.sourceforge.net/faq.html#GTKPATH>the
FAQ</a><ul>

<li>Install <a
href=http://sourceforge.net/project/showfiles.php?group_id=1369&release_id=176455>
Numeric/numarray</a>. If you are using the enthought edition of
python, you can skip this step.</li>

<li>Install the <a href=http://prdownloads.sourceforge.net/gtk-win>
GTK runtime</a> (currently version 2.2.4.1). <i>I recommend not using
the default install location as it makes it difficult to set your
path; use C:\GTk instead</i></li>

<li>Install <a
href=http://www.pcpm.ucl.ac.be/~gustin/win32_ports/binaries/pygtk-2.2.0-1.win32-py2.3.exe>pygtk-2.2.0</a></li>

<li>Modify your path.  Check <a
href=http://www.async.com.br/faq/pygtk/index.py?req=show&file=faq21.012.htp>this
FAQ entry</a> for information on how to do this right.

<li> Install matplotlib using the windows installer on the <a
ref=http://sourceforge.net/projects/matplotlib>download page<a></li>

</ul> 


<a name=WX><h3>WX</h3></a>

Requires <a href=http://www.wxpython.org>wxpython</a>.  Windows users
may want to consider the <a
href=http://www.enthought.com/python>enthought edition</a> of python,
which comes with wxpython and Numeric built in, so matplotlib will
work right out of the box.  matplotlib under WX has been tested on
linux, win32 and OSX.<p>

<a name=WXAgg><h3>WXAgg</h3></a>

Requires <a href=http://www.wxpython.org>wxpython</a>.  Windows users
may want to consider the <a
href=http://www.enthought.com/python>enthought edition</a> of python,
which comes with wxpython and Numeric built in, so matplotlib will
work right out of the box.  matplotlib under WXAgg has been tested on
linux, win32 and OSX.<p>

<a name=GTKAgg><h3>GTKAgg: GTK GUI with antigrain rendering</h3></a>

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 <a
href=http:///antigrain.com>antigrain</a>.  You need the <a
href=backends.html#Agg>agg</a> and <a href=backends.html#GTK>gtk</a>
prerequisites.  On windows, GTKAgg is builtin, so you only need to
install pygtk and the GTK runtime, as described in <a
href=backends.html#GTK>gtk</a>.


<a name=GTKAgg><h3>GTKCairo</h3></a>

GTKCairo uses Cairo rendering from within the GTK GUI.
You need the <a href=backends.html#Cairo>Cairo</a> and <a href=backends.html#GTK>gtk</a>
prerequisites.


<a name=TkAgg><h3>Tkinter GUI backend</h3></a>

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 <a href=backends.html#Agg>agg backend</a> 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
<ul>
<li>python</li>
<li>idle -n (set <tt>tk.PYTHONINSPECT : True</tt> in <a href=matplotlibrc>matplotlibrc</a> </li>
<li>IPython</li>
</ul>

TkAgg is known not work with:

<ul>
<li>SciTE</li>
<li>pythonw</li>
<li>Pythonwin</li>
<li>idle</li>
</ul>

Both of the latter shells fail with a RuntimeError "abnormal program
termination".

I checked on www.python.org about Tkinter and Pythonwin and they're
known not to work together so that explains TkAgg on Pythonwin.  <a
href=http://www.python.org/topics/tkinter/trouble.html>tkinter
trouble</a>.<p>

I also looked into SciTE a little and discovered that it is related to
Scintilla which in turn was derived from Pythonwin.  <a
href=http://www.scintilla.org>scintilla</a> This indicates to me that
the same problem with Tkinter may be affecting both (SciTE and
Pythonwin)... but I am out on a limb.<p>

<h3><a name=GD>GD output</a></h3>

The recommended image backend is Agg.  If you are sure you want to use
GD, read on.<p>
  
The GD module can be used to create images with no X11 server, and is
particularly useful for web application developers who want dynamic
graphing capabilities.  There are a number of prerequisites but they
are easy to install (Windows users should skip ahead to the win32
section).<p>

The GD backend depends on Numeric/numarray, gdmodule, and gd.  To ease
installation, the latter two packages now ship with matplotlib.  Below
are instructions for building gdmodule.
	
  <ul>

  <li><a href=http://www.pfdubois.com/numpy>Numeric/numarray</a>  --
  Numeric processing in python</li>

  <li><a href=http://www.boutell.com/gd>GD lib</a> -- The GD library.
  Note if you are using linux and have this installed in /usr/lib, you
  will need to install the latest version over the existing install
  unless you have gd-2.0.22 or later</li>

  <li><a
  href=http://newcenturycomputers.net/projects/gdmodule.html>gdmodule-0.52</a>
  -- The python interface to the gd module.</li>

  </ul>

<h4><a name=GDWIN32>Quick install guide for GD output: Windows</a></h4>

In addition to Numeric, you'll need

<ul>

<li> The GD DLL <a href=gd/bgd.dll>bgd.dll</a> somewhere in your
PATH</li>

<li> gdmodule for win32 and python2.3 <a href=gd/gdmodule-0.52a.win32-py2.3.exe >gdmodule-0.52a</a>.</li>

</ul>

<a name=PS><h3>Postscript</h3></a>

The only requirement is <a
href=http://sourceforge.net/projects/numpy>Numeric/numarray</a><p>

See the <a href=fonts.html#PSFONTS>fonts page</a> 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
<tt>AFMPATH</tt> if you want to use fonts other than the ones that
ship with matplotlib.


<a name=Paint><h3>Paint</h3></a>

David Moore has written a paint backend for matplotlib.  paint is a <a
href=http://www.levien.com/libart>libart</a> wrapper</a>. In a
nutshell, libart is a svg oriented, high performance, 2D graphics
engine that supports lots of nifty features.  The paint backend
exposes some of them, and David has been extending it to expose more.<p>

The paint backend requires <a
href=http://sourceforge.net/projects/numpy>Numeric/numarray</a>, <a
href=http://sourceforge.net/projects/pypaint>pypaint</a> version 0.3.

libart is highly portable, and the paint backend has been confirmed to
work on win32 and linux.  The pypaint web site has a src distribution
and a windows installer.<p>



<a name=EMF><h3>EMF</h3></a>

Rob McMullen has written an Enhanced Metafile (EMF) backend for
matplotlib, which requires <a
href="http://pyemf.sourceforge.net">pyemf</a> version 2.0.0b1 (or
newer).  EMF is a vector graphics format supported by the
cross-platform OpenOffice suite as well as most Windows office
applications.  EMF images can also be embedded within Rich Text Format
(.rtf) files to create a single document with multiple plots. <p>




@footer@