Skip to content

Commit 63a5c11

Browse files
efiringefiring
committed
faq: move the backends section from installing to usage
If there is information about installing backends, then that can be put in a new subsection of the installation faq; but the subsection that I moved is much more relevant to mpl usage than to installation.
1 parent 1415d18 commit 63a5c11

File tree

2 files changed

+143
-143
lines changed

2 files changed

+143
-143
lines changed

‎doc/faq/installing_faq.rst‎

Lines changed: 0 additions & 143 deletions
Original file line numberDiff line numberDiff line change
@@ -144,149 +144,6 @@ setupegg.py develop` command again to compile them.
144144
There is more information on :ref:`using git <using-git>` in
145145
the developer docs.
146146

147-
Backends
148-
========
149-
150-
.. _what-is-a-backend:
151-
152-
What is a backend?
153-
------------------
154-
155-
A lot of documentation on the website and in the mailing lists refers
156-
to the "backend" and many new users are confused by this term.
157-
matplotlib targets many different use cases and output formats. Some
158-
people use matplotlib interactively from the python shell and have
159-
plotting windows pop up when they type commands. Some people embed
160-
matplotlib into graphical user interfaces like wxpython or pygtk to
161-
build rich applications. Others use matplotlib in batch scripts to
162-
generate postscript images from some numerical simulations, and still
163-
others in web application servers to dynamically serve up graphs.
164-
165-
To support all of these use cases, matplotlib can target different
166-
outputs, and each of these capabilities is called a backend; the
167-
"frontend" is the user facing code, ie the plotting code, whereas the
168-
"backend" does all the hard work behind-the-scenes to make the
169-
figure. There are two types of backends: user interface backends (for
170-
use in pygtk, wxpython, tkinter, qt, macosx, or fltk; also
171-
referred to as "interactive backends") and hardcopy backends to
172-
make image files (PNG, SVG, PDF, PS; also referred to as "non-interactive
173-
backends").
174-
175-
There are a two primary ways to configure your backend. One is to set
176-
the ``backend`` parameter in your ``matplotlibrc`` file (see
177-
:ref:`customizing-matplotlib`)::
178-
179-
backend : WXAgg # use wxpython with antigrain (agg) rendering
180-
181-
The other is to use the matplotlib :func:`~matplotlib.use` directive::
182-
183-
import matplotlib
184-
matplotlib.use('PS') # generate postscript output by default
185-
186-
If you use the ``use`` directive, this must be done before importing
187-
:mod:`matplotlib.pyplot` or :mod:`matplotlib.pylab`.
188-
189-
.. note::
190-
Backend name specifications are not case-sensitive; e.g., 'GTKAgg'
191-
and 'gtkagg' are equivalent.
192-
193-
With a typical installation of matplotlib, such as from a
194-
binary installer or a linux distribution package, a good default
195-
backend will already be set, allowing both interactive work and
196-
plotting from scripts, with output to the screen and/or to
197-
a file, so at least initially you will not need to use either of the
198-
two methods given above.
199-
200-
If, however, you want to write graphical user interfaces, or a web
201-
application server (:ref:`howto-webapp`), or need a better
202-
understanding of what is going on, read on. To make things a little
203-
more customizable for graphical user interfaces, matplotlib separates
204-
the concept of the renderer (the thing that actually does the drawing)
205-
from the canvas (the place where the drawing goes). The canonical
206-
renderer for user interfaces is ``Agg`` which uses the `Anti-Grain
207-
Geometry`_ C++ library to make a raster (pixel) image of the figure.
208-
All of the user interfaces except ``macosx`` can be used with
209-
agg rendering, eg
210-
``WXAgg``, ``GTKAgg``, ``QT4Agg``, ``TkAgg``. In
211-
addition, some of the user interfaces support other rendering engines.
212-
For example, with GTK, you can also select GDK rendering (backend
213-
``GTK``) or Cairo rendering (backend ``GTKCairo``).
214-
215-
For the rendering engines, one can also distinguish between `vector
216-
<http://en.wikipedia.org/wiki/Vector_graphics>`_ or `raster
217-
<http://en.wikipedia.org/wiki/Raster_graphics>`_ renderers. Vector
218-
graphics languages issue drawing commands like "draw a line from this
219-
point to this point" and hence are scale free, and raster backends
220-
generate a pixel representation of the line whose accuracy depends on a
221-
DPI setting.
222-
223-
Here is a summary of the matplotlib renderers (there is an eponymous
224-
backed for each; these are *non-interactive backends*, capable of
225-
writing to a file):
226-
227-
============= ============ ================================================
228-
Renderer Filetypes Description
229-
============= ============ ================================================
230-
:term:`AGG` :term:`png` :term:`raster graphics` -- high quality images
231-
using the `Anti-Grain Geometry`_ engine
232-
PS :term:`ps` :term:`vector graphics` -- Postscript_ output
233-
:term:`eps`
234-
PDF :term:`pdf` :term:`vector graphics` --
235-
`Portable Document Format`_
236-
SVG :term:`svg` :term:`vector graphics` --
237-
`Scalable Vector Graphics`_
238-
:term:`Cairo` :term:`png` :term:`vector graphics` --
239-
:term:`ps` `Cairo graphics`_
240-
:term:`pdf`
241-
:term:`svg`
242-
...
243-
:term:`GDK` :term:`png` :term:`raster graphics` --
244-
:term:`jpg` the `Gimp Drawing Kit`_
245-
:term:`tiff`
246-
...
247-
============= ============ ================================================
248-
249-
And here are the user interfaces and renderer combinations supported;
250-
these are *interactive backends*, capable of displaying to the screen
251-
and of using appropriate renderers from the table above to write to
252-
a file:
253-
254-
============ ================================================================
255-
Backend Description
256-
============ ================================================================
257-
GTKAgg Agg rendering to a :term:`GTK` canvas (requires PyGTK_)
258-
GTK GDK rendering to a :term:`GTK` canvas (not recommended)
259-
(requires PyGTK_)
260-
GTKCairo Cairo rendering to a :term:`GTK` Canvas (requires PyGTK_)
261-
WXAgg Agg rendering to to a :term:`wxWidgets` canvas
262-
(requires wxPython_)
263-
WX Native :term:`wxWidgets` drawing to a :term:`wxWidgets` Canvas
264-
(not recommended) (requires wxPython_)
265-
TkAgg Agg rendering to a :term:`Tk` canvas (requires TkInter_)
266-
QtAgg Agg rendering to a :term:`Qt` canvas (requires PyQt_)
267-
(not recommended; use Qt4Agg)
268-
Qt4Agg Agg rendering to a :term:`Qt4` canvas (requires PyQt4_)
269-
FLTKAgg Agg rendering to a :term:`FLTK` canvas (requires pyFLTK_)
270-
(not widely used; consider TKAgg, GTKAgg, WXAgg, or
271-
QT4Agg instead)
272-
macosx Cocoa rendering in OSX windows
273-
(presently lacks blocking show() behavior when matplotlib
274-
is in non-interactive mode)
275-
============ ================================================================
276-
277-
.. _`Anti-Grain Geometry`: http://www.antigrain.com/
278-
.. _Postscript: http://en.wikipedia.org/wiki/PostScript
279-
.. _`Portable Document Format`: http://en.wikipedia.org/wiki/Portable_Document_Format
280-
.. _`Scalable Vector Graphics`: http://en.wikipedia.org/wiki/Scalable_Vector_Graphics
281-
.. _`Cairo graphics`: http://en.wikipedia.org/wiki/Cairo_(graphics)
282-
.. _`Gimp Drawing Kit`: http://en.wikipedia.org/wiki/GDK
283-
.. _PyGTK: http://www.pygtk.org
284-
.. _wxPython: http://www.wxpython.org/
285-
.. _TkInter: http://wiki.python.org/moin/TkInter
286-
.. _PyQt: http://www.riverbankcomputing.co.uk/software/pyqt/intro
287-
.. _PyQt4: http://www.riverbankcomputing.co.uk/software/pyqt/intro
288-
.. _pyFLTK: http://pyfltk.sourceforge.net
289-
290147

291148
OS-X questions
292149
==============

‎doc/faq/usage_faq.rst‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -146,4 +146,147 @@ complicated applications, this explicitness and clarity becomes
146146
increasingly valuable, and the richer and more complete object-oriented
147147
interface will likely make the program easier to write and maintain.
148148

149+
Backends
150+
========
151+
152+
.. _what-is-a-backend:
153+
154+
What is a backend?
155+
------------------
156+
157+
A lot of documentation on the website and in the mailing lists refers
158+
to the "backend" and many new users are confused by this term.
159+
matplotlib targets many different use cases and output formats. Some
160+
people use matplotlib interactively from the python shell and have
161+
plotting windows pop up when they type commands. Some people embed
162+
matplotlib into graphical user interfaces like wxpython or pygtk to
163+
build rich applications. Others use matplotlib in batch scripts to
164+
generate postscript images from some numerical simulations, and still
165+
others in web application servers to dynamically serve up graphs.
166+
167+
To support all of these use cases, matplotlib can target different
168+
outputs, and each of these capabilities is called a backend; the
169+
"frontend" is the user facing code, ie the plotting code, whereas the
170+
"backend" does all the hard work behind-the-scenes to make the
171+
figure. There are two types of backends: user interface backends (for
172+
use in pygtk, wxpython, tkinter, qt, macosx, or fltk; also
173+
referred to as "interactive backends") and hardcopy backends to
174+
make image files (PNG, SVG, PDF, PS; also referred to as "non-interactive
175+
backends").
176+
177+
There are a two primary ways to configure your backend. One is to set
178+
the ``backend`` parameter in your ``matplotlibrc`` file (see
179+
:ref:`customizing-matplotlib`)::
180+
181+
backend : WXAgg # use wxpython with antigrain (agg) rendering
182+
183+
The other is to use the matplotlib :func:`~matplotlib.use` directive::
184+
185+
import matplotlib
186+
matplotlib.use('PS') # generate postscript output by default
187+
188+
If you use the ``use`` directive, this must be done before importing
189+
:mod:`matplotlib.pyplot` or :mod:`matplotlib.pylab`.
190+
191+
.. note::
192+
Backend name specifications are not case-sensitive; e.g., 'GTKAgg'
193+
and 'gtkagg' are equivalent.
194+
195+
With a typical installation of matplotlib, such as from a
196+
binary installer or a linux distribution package, a good default
197+
backend will already be set, allowing both interactive work and
198+
plotting from scripts, with output to the screen and/or to
199+
a file, so at least initially you will not need to use either of the
200+
two methods given above.
201+
202+
If, however, you want to write graphical user interfaces, or a web
203+
application server (:ref:`howto-webapp`), or need a better
204+
understanding of what is going on, read on. To make things a little
205+
more customizable for graphical user interfaces, matplotlib separates
206+
the concept of the renderer (the thing that actually does the drawing)
207+
from the canvas (the place where the drawing goes). The canonical
208+
renderer for user interfaces is ``Agg`` which uses the `Anti-Grain
209+
Geometry`_ C++ library to make a raster (pixel) image of the figure.
210+
All of the user interfaces except ``macosx`` can be used with
211+
agg rendering, eg
212+
``WXAgg``, ``GTKAgg``, ``QT4Agg``, ``TkAgg``. In
213+
addition, some of the user interfaces support other rendering engines.
214+
For example, with GTK, you can also select GDK rendering (backend
215+
``GTK``) or Cairo rendering (backend ``GTKCairo``).
216+
217+
For the rendering engines, one can also distinguish between `vector
218+
<http://en.wikipedia.org/wiki/Vector_graphics>`_ or `raster
219+
<http://en.wikipedia.org/wiki/Raster_graphics>`_ renderers. Vector
220+
graphics languages issue drawing commands like "draw a line from this
221+
point to this point" and hence are scale free, and raster backends
222+
generate a pixel representation of the line whose accuracy depends on a
223+
DPI setting.
224+
225+
Here is a summary of the matplotlib renderers (there is an eponymous
226+
backed for each; these are *non-interactive backends*, capable of
227+
writing to a file):
228+
229+
============= ============ ================================================
230+
Renderer Filetypes Description
231+
============= ============ ================================================
232+
:term:`AGG` :term:`png` :term:`raster graphics` -- high quality images
233+
using the `Anti-Grain Geometry`_ engine
234+
PS :term:`ps` :term:`vector graphics` -- Postscript_ output
235+
:term:`eps`
236+
PDF :term:`pdf` :term:`vector graphics` --
237+
`Portable Document Format`_
238+
SVG :term:`svg` :term:`vector graphics` --
239+
`Scalable Vector Graphics`_
240+
:term:`Cairo` :term:`png` :term:`vector graphics` --
241+
:term:`ps` `Cairo graphics`_
242+
:term:`pdf`
243+
:term:`svg`
244+
...
245+
:term:`GDK` :term:`png` :term:`raster graphics` --
246+
:term:`jpg` the `Gimp Drawing Kit`_
247+
:term:`tiff`
248+
...
249+
============= ============ ================================================
250+
251+
And here are the user interfaces and renderer combinations supported;
252+
these are *interactive backends*, capable of displaying to the screen
253+
and of using appropriate renderers from the table above to write to
254+
a file:
255+
256+
============ ================================================================
257+
Backend Description
258+
============ ================================================================
259+
GTKAgg Agg rendering to a :term:`GTK` canvas (requires PyGTK_)
260+
GTK GDK rendering to a :term:`GTK` canvas (not recommended)
261+
(requires PyGTK_)
262+
GTKCairo Cairo rendering to a :term:`GTK` Canvas (requires PyGTK_)
263+
WXAgg Agg rendering to to a :term:`wxWidgets` canvas
264+
(requires wxPython_)
265+
WX Native :term:`wxWidgets` drawing to a :term:`wxWidgets` Canvas
266+
(not recommended) (requires wxPython_)
267+
TkAgg Agg rendering to a :term:`Tk` canvas (requires TkInter_)
268+
QtAgg Agg rendering to a :term:`Qt` canvas (requires PyQt_)
269+
(not recommended; use Qt4Agg)
270+
Qt4Agg Agg rendering to a :term:`Qt4` canvas (requires PyQt4_)
271+
FLTKAgg Agg rendering to a :term:`FLTK` canvas (requires pyFLTK_)
272+
(not widely used; consider TKAgg, GTKAgg, WXAgg, or
273+
QT4Agg instead)
274+
macosx Cocoa rendering in OSX windows
275+
(presently lacks blocking show() behavior when matplotlib
276+
is in non-interactive mode)
277+
============ ================================================================
278+
279+
.. _`Anti-Grain Geometry`: http://www.antigrain.com/
280+
.. _Postscript: http://en.wikipedia.org/wiki/PostScript
281+
.. _`Portable Document Format`: http://en.wikipedia.org/wiki/Portable_Document_Format
282+
.. _`Scalable Vector Graphics`: http://en.wikipedia.org/wiki/Scalable_Vector_Graphics
283+
.. _`Cairo graphics`: http://en.wikipedia.org/wiki/Cairo_(graphics)
284+
.. _`Gimp Drawing Kit`: http://en.wikipedia.org/wiki/GDK
285+
.. _PyGTK: http://www.pygtk.org
286+
.. _wxPython: http://www.wxpython.org/
287+
.. _TkInter: http://wiki.python.org/moin/TkInter
288+
.. _PyQt: http://www.riverbankcomputing.co.uk/software/pyqt/intro
289+
.. _PyQt4: http://www.riverbankcomputing.co.uk/software/pyqt/intro
290+
.. _pyFLTK: http://pyfltk.sourceforge.net
291+
149292

0 commit comments

Comments
 (0)