From: <md...@us...> - 2007-11-30 19:31:31
|
Revision: 4530 http://matplotlib.svn.sourceforge.net/matplotlib/?rev=4530&view=rev Author: mdboom Date: 2007-11-30 11:31:05 -0800 (Fri, 30 Nov 2007) Log Message: ----------- Lots of updates to bring the website inline with 0.91.1 Modified Paths: -------------- trunk/htdocs/backends.html.template trunk/htdocs/faq.html.template trunk/htdocs/fonts.html.template trunk/htdocs/tutorial.html.template Modified: trunk/htdocs/backends.html.template =================================================================== --- trunk/htdocs/backends.html.template 2007-11-30 17:39:05 UTC (rev 4529) +++ trunk/htdocs/backends.html.template 2007-11-30 19:31:05 UTC (rev 4530) @@ -1,25 +1,475 @@ -@header@ +@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, -pdf, 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> +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 +<a href="http://sourceforge.net/mailarchive/forum.php?forum_name=matplotlib-devel">matplotlib-devel</a> +mailing list.<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 +<a name="comparision"/><h2>Comparison of backends</h2> + +The following table enumerates the capabilities of the different backends.<p> + +<!-- This HTML table template is generated by emacs 22.1.1 --> +<table border="1"> + <tr bgcolor="#dddddd"> + <td align="left" valign="top"> + + </td> + <td align="left" valign="top"> + output formats + </td> + <td align="left" valign="top"> + rotated text + </td> + <td align="left" valign="top"> + usetex + </td> + <td align="left" valign="top"> + alpha-blending + </td> + <td align="left" valign="top"> + arbitrary clipping<br/> (polar plots) + </td> + <td align="left" valign="top"> + images + </td> + </tr> + <tr> + <td align="left" valign="top"> + Agg + </td> + <td align="left" valign="top"> + png, raw + </td> + <td align="left" valign="top"> + X + </td> + <td align="left" valign="top"> + X + </td> + <td align="left" valign="top"> + X + </td> + <td align="left" valign="top"> + X + </td> + <td align="left" valign="top"> + X + </td> + </tr> + <tr> + <td align="left" valign="top"> + Cairo + </td> + <td align="left" valign="top"> + pdf, + png,ps, + svg, + svgz + </td> + <td align="left" valign="top"> + X + </td> + <td align="left" valign="top"> + + </td> + <td align="left" valign="top"> + + </td> + <td align="left" valign="top"> + + </td> + <td align="left" valign="top"> + X + </td> + </tr> + <tr> + <td align="left" valign="top"> + CocoaAgg + </td> + <td align="left" valign="top"> + png, + raw + </td> + <td align="left" valign="top"> + X + </td> + <td align="left" valign="top"> + X + </td> + <td align="left" valign="top"> + X + </td> + <td align="left" valign="top"> + X + </td> + <td align="left" valign="top"> + X + </td> + </tr> + <tr> + <td align="left" valign="top"> + Emf + </td> + <td align="left" valign="top"> + emf + </td> + <td align="left" valign="top"> + ? + </td> + <td align="left" valign="top"> + ? + </td> + <td align="left" valign="top"> + ? + </td> + <td align="left" valign="top"> + ? + </td> + <td align="left" valign="top"> + ? + </td> + </tr> + <tr> + <td align="left" valign="top"> + FltkAgg + </td> + <td align="left" valign="top"> + png, + raw + </td> + <td align="left" valign="top"> + X + </td> + <td align="left" valign="top"> + X + </td> + <td align="left" valign="top"> + X + </td> + <td align="left" valign="top"> + X + </td> + <td align="left" valign="top"> + X + </td> + </tr> + <tr> + <td align="left" valign="top"> + Gtk + (Gdk) + </td> + <td align="left" valign="top"> + jpeg, + png, + raw + </td> + <td align="left" valign="top"> + + </td> + <td align="left" valign="top"> + + </td> + <td align="left" valign="top"> + + </td> + <td align="left" valign="top"> + + </td> + <td align="left" valign="top"> + X + </td> + </tr> + <tr> + <td align="left" valign="top"> + GtkAgg + </td> + <td align="left" valign="top"> + jpeg, + png, + raw + </td> + <td align="left" valign="top"> + X + </td> + <td align="left" valign="top"> + X + </td> + <td align="left" valign="top"> + X + </td> + <td align="left" valign="top"> + X + </td> + <td align="left" valign="top"> + X + </td> + </tr> + <tr> + <td align="left" valign="top"> + GtkCairo + </td> + <td align="left" valign="top"> + jpeg, + pdf, + png, + ps, + svg, + svgz + </td> + <td align="left" valign="top"> + X + </td> + <td align="left" valign="top"> + + </td> + <td align="left" valign="top"> + + </td> + <td align="left" valign="top"> + + </td> + <td align="left" valign="top"> + X + </td> + </tr> + <tr> + <td align="left" valign="top"> + Pdf + </td> + <td align="left" valign="top"> + pdf + </td> + <td align="left" valign="top"> + X + </td> + <td align="left" valign="top"> + X + </td> + <td align="left" valign="top"> + X + </td> + <td align="left" valign="top"> + X + </td> + <td align="left" valign="top"> + X + </td> + </tr> + <tr> + <td align="left" valign="top"> + Ps + </td> + <td align="left" valign="top"> + eps,ps + </td> + <td align="left" valign="top"> + X + </td> + <td align="left" valign="top"> + X + </td> + <td align="left" valign="top"> + + </td> + <td align="left" valign="top"> + + </td> + <td align="left" valign="top"> + X + </td> + </tr> + <tr> + <td align="left" valign="top"> + QtAgg + </td> + <td align="left" valign="top"> + png,raw + </td> + <td align="left" valign="top"> + X + </td> + <td align="left" valign="top"> + X + </td> + <td align="left" valign="top"> + X + </td> + <td align="left" valign="top"> + X + </td> + <td align="left" valign="top"> + X + </td> + </tr> + <tr> + <td align="left" valign="top"> + Qt4Agg + </td> + <td align="left" valign="top"> + png,raw + </td> + <td align="left" valign="top"> + X + </td> + <td align="left" valign="top"> + X + </td> + <td align="left" valign="top"> + X + </td> + <td align="left" valign="top"> + X + </td> + <td align="left" valign="top"> + X + </td> + </tr> + <tr> + <td align="left" valign="top"> + Svg + </td> + <td align="left" valign="top"> + svg, + svgz + </td> + <td align="left" valign="top"> + X + </td> + <td align="left" valign="top"> + + </td> + <td align="left" valign="top"> + X + </td> + <td align="left" valign="top"> + + </td> + <td align="left" valign="top"> + X + </td> + </tr> + <tr> + <td align="left" valign="top"> + TkAgg + </td> + <td align="left" valign="top"> + png,raw + </td> + <td align="left" valign="top"> + X + </td> + <td align="left" valign="top"> + X + </td> + <td align="left" valign="top"> + X + </td> + <td align="left" valign="top"> + X + </td> + <td align="left" valign="top"> + X + </td> + </tr> + <tr> + <td align="left" valign="top"> + Wx + </td> + <td align="left" valign="top"> + bmp, + jpeg, + pcx, + png, + raw, + tiff, + xpm + </td> + <td align="left" valign="top"> + + </td> + <td align="left" valign="top"> + + </td> + <td align="left" valign="top"> + + </td> + <td align="left" valign="top"> + + </td> + <td align="left" valign="top"> + + </td> + </tr> + <tr> + <td align="left" valign="top"> + WxAgg + </td> + <td align="left" valign="top"> + png,raw + </td> + <td align="left" valign="top"> + X + </td> + <td align="left" valign="top"> + X + </td> + <td align="left" valign="top"> + X + </td> + <td align="left" valign="top"> + X + </td> + <td align="left" valign="top"> + X + </td> + </tr> +</table> + +<p> + +In addition to these factors, there are other factors that may +affect your backend selection:<p> + +<ul> + <li><b>Scalability:</b> 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. + + <li><b>Speed:</b> 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.</li> + + <li><b>Interactivity:</b> All of the GUI backends can be used interactively + from a python shell (see <a href=interactive.html>interactive</a>) 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.</li> + + <li><b>Pretty widgets:</b> 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. </li> +</ul> + +<h3>Choosing a backend</h3> + +You can choose your default backend in +the <a href=matplotlibrc>matplotlibrc</a> 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 <tt>print</tt> command, the backend can be chosen from the +command line with the <tt>-d</tt> flag, as in <pre> @@ -59,10 +509,11 @@ matplotlib.use('PS') </pre> -The current backend strings that are supported are +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_fltkagg.html>FltkAgg</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 @@ -90,15 +541,17 @@ 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=#Agg>Agg</a></li> +<li><a href=#Cairo>Cairo</a></li> +<li><a href=#TkAgg>TkAgg</a></li> +<li><a href=#GTK>GTK</a></li> +<li><a href=#GTKAgg>GTKAgg</a></li> +<li><a href=#GTKCairo>GTKCairo</a></li> +<li><a href=#WX>WX</a></li> +<li><a href=#WXAgg>WXAgg</a></li> +<li><a href=#PS>PS</a></li> +<li><a href=#PDF>PDF</a></li> +<li><a href=#SVG>SVG</a></li> </ul> @@ -112,20 +565,19 @@ 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>. +matplotlib includes its own copy of Agg. It does not need to be +installed separately, even if compiling matplotlib from source. <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. +<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 +It requires pycairo version 0.5.0 or higher from <a href=http://www.freedesktop.org/Cairo/download>Cairo downloads</a> @@ -133,35 +585,23 @@ This was the first backend supported by matplotlib; it requires -<ul> +<ul> <li><a href=http://numpy.scipy.org/>numpy</a></li> <li><a href=http://prdownloads.sourceforge.net/gtk-win> -GTK runtime</a></li> +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 +href=backends.html#GTKAgg>GTKAgg<a/> backends on windows. If you encounter troubles, please see <a href=http://matplotlib.sourceforge.net/faq.html#GTKPATH>the FAQ</a><ul> @@ -184,7 +624,7 @@ <li> Install matplotlib using the windows installer on the <a ref=http://sourceforge.net/projects/matplotlib>download page<a></li> -</ul> +</ul> <a name=WX><h3>WX</h3></a> @@ -212,7 +652,7 @@ 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 +prerequisites. Agg is builtin, so you only need to install pygtk and the GTK runtime, as described in <a href=backends.html#GTK>gtk</a>. @@ -270,7 +710,7 @@ <a name=PS><h3>Postscript</h3></a> -The only requirement is <a href=http://numpy.scipy.org/>numpy</a><p> +The only requirement is <a href=http://numpy.scipy.org/>numpy</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; @@ -278,9 +718,15 @@ <tt>AFMPATH</tt> if you want to use fonts other than the ones that ship with matplotlib. +<a name=PS><h3>PDF</h3></a> +The only requirement is <a href=http://numpy.scipy.org/>numpy</a>.<p> +<a name=PS><h3>SVG</h3></a> +The only requirement is <a href=http://numpy.scipy.org/>numpy</a>.<p> + + @footer@ Modified: trunk/htdocs/faq.html.template =================================================================== --- trunk/htdocs/faq.html.template 2007-11-30 17:39:05 UTC (rev 4529) +++ trunk/htdocs/faq.html.template 2007-11-30 19:31:05 UTC (rev 4530) @@ -2,7 +2,7 @@ FAQs = ( - ('BUGREPORT', + ('BUGREPORT', 'How do I report a problem?', """\ OK, this is not a FAQ, but I wish it were <wink>.<p> @@ -13,7 +13,7 @@ <pre> > rm -rf build - > python setup.py build + > python setup.py build </pre> @@ -110,7 +110,7 @@ ('CLICKMAPS', "Can I use matplotlib to make clickable images?" , - """\ + """ Yes. Andrew Dalke of <a href=http://www.dalkescientific.com>Dalke Scientific</a> has written a nice <a href=http://www.dalkescientific.com/writings/diary/archive/2005/04/24/interactive_html.html>article</a> @@ -188,7 +188,7 @@ approach taken in <a href=examples/log_bar.py>log_bar.py</a>. """), - ('EQUAL', + ('EQUAL', 'How do I make my figure square / axes sides equal?', """\ There are three considerations: the width/height of the figure, of the @@ -210,7 +210,7 @@ vertical resolutions, you can do a little hack on the figure width and height to correct for the display differences. """), - + ('FREEZE', 'My matplotlib window is freezing', @@ -270,7 +270,7 @@ The swiss army knife of image tools, ImageMagick's <a href=http://imagemagick.sourceforge.net/www/convert.html>convert</a>, -works for this as well.<p> +works for this as well.<p> Here is a simple example script that saves some PNGs, makes them into a movie, and then cleans up. @@ -299,10 +299,10 @@ </pre> """), - + ('FONTMISSING', "When I start matplotlib, I am getting warnings about not being able to find fonts?", """ -matplotlib uses a cache file to store information about your system fonts, and occasionally we reorganize our direcotroy schemes or your system may have changed. When you get warnings about missing fonts, try removing your font cache directory "ttffont.cache" which is located in your ".matplotlib" configuration directory. Where this is depends on your operating system but see the prolog of <a href=matplotlibrc>matplotlibrc</a> for information on where this is stored. You can also run a test pylab script with <tt>--verbose-helpful</tt> or <tt>--verbose-debug</tt>, eg +matplotlib uses a cache file to store information about your system fonts, and occasionally we reorganize our directory schemes or your system may have changed. When you get warnings about missing fonts, try removing your font cache directory "fontManager.cache" which is located in your ".matplotlib" configuration directory. Where this is depends on your operating system but see the prolog of <a href=matplotlibrc>matplotlibrc</a> for information on where this is stored. You can also run a test pylab script with <tt>--verbose-helpful</tt> or <tt>--verbose-debug</tt>, eg <pre> > python test.py --verbose-helpful @@ -326,14 +326,14 @@ install. You may want to try rebuilding with <pre> > rm -rf build - > python setup.py build > build.out + > python setup.py build > build.out </pre> and post the results to the matplotlib-devel or matplotlib-users <a href=http://sourceforge.net/mail/?group_id=80706>mailing lists</a>. """), - + ('EXAMPLES', 'Where can I find information about what matplotlib can do?', """\ @@ -366,39 +366,22 @@ ('LARGEPS', "My PS/EPS files are huge; what's wrong?", """ -With matplotlib-0.61, Paul Barrett introduced truetype fonts in -backend_ps, primarily in order to support mathtext. Because he was -unable to get the individual glyphs from freetype, he had to dump the -entire font into the PS file. A typical font takes about 300K of -noncompressed space. This, however, is a fixed cost and does not -increase with the complexity of the figure or number of points -plotted. It would, however, increase if you use multiple fonts, eg in -mathtext.<p> +As of matplotlib-0.91.0, only the glyphs that are needed for the plot +are saved in the Postscript file. This significantly reduces file +sizes. To revert to the old behavior, where entire font files are +saved in the Postscript file, you can set the parameter 'ps.fonttype' +to 42. -Before 0.61, we used the afm fonts that ship with matplotlib and -matplotlib has its own <a href=matplotlib.afm.html>AFM parser</a> -which handles character metrics, kerning, etc. It would not be too -much work to have an option (eg in the matplotlib rc file) which -allows users to simply use AFM fonts when possible (eg when not using -mathtext) in which case you wouldn't see these big eps files. The -other advantage to this approach is that they seem to render nicer in -some viewers, eg xdvi.<p> - -One nice thing about dumping the truetype into the ps files is that -the text is the same across backends. The ideal solution would be -able to dump just the glyphs needed, which presumably would be much -smaller, but we haven't figured this out yet.<p> - -Given that the 300K is a fixed cost (118K gzipped), if you still find -the size sufficiently troublesome that it justifies the extra work (on -our end) to provide an option to revert to AFM fonts, please let us -know on the mailing list. +Starting with matplotlib-0.87, it is also possible to reduce +Postscript file sizes by using the standard Postscript fonts, rather +than embedding Truetype files. Just set the parameter 'ps.useafm' to +True. """), ('PROMPT', "After my matplotlib script runs, I get a python shell prompt. What's going on?", """ -Tkinter, used by the default windows backend TkAgg not have a mainloop +Tkinter, used by the default windows backend TkAgg does not have a mainloop like GTK or WX. We needed a way to keep the figure open, and decided the best way was to switch into interactive mode in python. This has the additional benefit that you can issue additional python commands @@ -453,7 +436,7 @@ Also, if you are running a python script, make sure your interactive setting in your <a href=matplotlibrc>matplotlibrc</a> is <tt>False</tt>; otherwise the figure will be redrawn with every plotting command when -what you want if for the figure to be drawn only once at the end of +what you want is for the figure to be drawn only once at the end of the script. See <a href=interactive.html>interactive</a> and <a href=faq.html#SHOW>what's up with show?</a> for more information.<p> @@ -473,16 +456,16 @@ output of <tt>python yourscript.py --verbose-helpful</tt>. """), - ('MATPLOTLIBRC', - 'How do I customize the default behavior of matplotib?', + ('MATPLOTLIBRC', + 'How do I customize the default behavior of matplotib?', """ Recent versions of matplotlib (0.51 or later) use a configuration file to set everything from the default font, to the figure size, to the default line width. See <a href=matplotlibrc>matplotlibrc</a> for a sample config file and information on how to use it. """), - ('OO', - 'Is there any guide to using matplotlib with pythonic / OO /API rather than the pylab interface?', + ('OO', + 'Is there any guide to using matplotlib with pythonic / OO /API rather than the pylab interface?', """ @@ -500,10 +483,10 @@ <li>Many examples in the <a href=examples>examples</a> directory in the matplotlib src distribution illustrate the use of the API. - Eg, + Eg, <pre> - + > grep -l FigureCanvas *.py agg_oo.py dynamic_demo_wx.py dynamic_image_wxagg.py @@ -604,7 +587,7 @@ command. See <a examples/customize_rc.py>customize_rc.py</a> for example usage."""), - + ('GTKPATH', 'I cannot import gtk / gdk / gobject', """ @@ -612,7 +595,7 @@ Basically, there are 3 things that I've seen cause failure (relative likelihood in parentheses): - <ul> + <ul> <li> You didn't set the path properly (95% of the time). <it>Solution:</it> Add the lib and bin subdirs of your GTK install @@ -635,62 +618,14 @@ thread</a>, which is filled with good troubleshooting advice. """ ), - + ('WHICHBACKEND', 'Which backend should I use?', """ -Each of the backends offers different strengths. I'll summarize some -of them. - -<h4>Image generation</h4> - -For pure image generation (no GUI) you can choose from the Agg, Cairo, -PS, SVG, Paint, GD or EMF backends. At this point, I advise people to -use the <a href=http://antigrain.com>agg</a> backend because: - -<ul> - <li>it's the fastest</li> - <li>it uses freetype2 (as does GD) which renders nicely even - at small resolutions </li> - <li>there are clipping issues with GD and Paint </li> - <li>it supports fast antialiased drawing and alpha blending </li> - <li>it supports <a href=matplotlib.mathtext.html>mathtext</a></li> - <li>it supports images with <a href=matplotlib.pyplot.html#-imshow>imshow</a></li> -</ul> - -It is likely that with time many of these limitiations or problems -will be fixed on the other backends.<p> - -For publication submission or use with TeX, however, the postscript -backend is naturally a good choice. - -<h4>GUI</h4> - -Currently there are several choices for GUIs: GTK, GTKAgg, GTKCairo, WX, -WXAgg, TkAgg and FltkAgg, with different advantages. - -<ul> - -<li>Speed: TkAgg and GTKAgg are likely to be the fastest since most of Agg is renderered in C extension code</li> - -<li>Stability: GTK was the first backend and thus has been most thoroughly -vetted for bugs. The GTKAgg and GTKCairo backends reuse the GTK widget code, -so should likewise be quite stable</li> - -<li>Interactivity: All of the GUI backends can be used interactively -from a python shell (see <a href=interactive.html>interactive</a>) 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 </li> - -<li>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 widgets are not visually stunning. </li> - -</ul> - - +Each of the backends offers different strengths. See the + <a href="backends.html#comparison">comparison of backends for a + discussion of the issues.</p> """), ('DATES', @@ -711,19 +646,19 @@ 'Can I include math expressions in my figures?', r"""As of matplotlib-0.51, you can use TeX markup in any text element. Just use raw strings and enclose the strings with dollar signs, as in -<tt>title(r'$\\alpha > \\beta_i$')</tt>. See <a +<tt>title(r'$\alpha > \beta_i$')</tt>. See <a href=screenshots.html#mathtext_demo>screenshot</a> and the <a href=matplotlib.mathtext.html>mathtext</a> documentation for usage, requirements and backend information. """), - + ('BATCHMODE', 'Can I just generate images without having a window popup?', """ The easiest way to do this is use an image backend, either <a -href=backends.html#Agg>Agg</a>, href=backends.html#Cairo>Cairo</a>, <a -href=backends.html#GD>GD</a> or <a href=backends.html#Paint>Paint</a> -if you want to generate PNG images, eg, for use in a web page, or PS +href=backends.html#Agg>Agg</a>, or <a href=backends.html#Cairo>Cairo</a>, +if you want to generate PNG images, e.g., for use in a web page, or + PS, PDF or SVG if you want publication quality, scalable images. All of these backends run on all of the major platforms. One additional option on an X windows platform is to run the GTK backend under an Xvfb, which @@ -738,10 +673,7 @@ Yes. matplotlb can be used with any web application server that can call python. It has been used with mod_python, xml_rpc, and other frameworks. You'll want to use one of the image backends; <a -href=faq.html#BATCHMODE>see image backends</a>. Also to make small -images appropriate for use on a web page, you may want to consider the -Agg, Cairo or GD backends, since they render small font rasters using -freetype2 better than Paint, which currently use freetype1. You can +href=faq.html#BATCHMODE>see image backends</a>. You can work around the problem of small raster sizes by making your fonts appear larger for a given by decreasing the figure size and increasing the dpi. See <a href=fonts.html#TTFFONTS>ttf fonts</a> for more @@ -773,10 +705,10 @@ """ -You do not need this function with the image backends (Agg, Cairo, Paint, GD, -PS) but you do need it with the GUI (GTK, WX, TkAgg, GTKAgg, GTKCairo) backends, -unless you are running matplotlib in <a -href=interactive.html>interactive mode</a>. <p> +You do not need this function with the image backends (Agg, Cairo, PS, +PDF, SVG) but you do need it with the GUI (GTK, WX, TkAgg, GTKAgg, +GTKCairo) backends, unless you are running matplotlib +in <a href=interactive.html>interactive mode</a>. <p> Because it is expensive to draw, I want to avoid redrawing the figure many times in a batch script such as the following<p> @@ -786,7 +718,7 @@ xlabel('time') # and here ? ylabel('volts') # and here ? title('a simple plot') # and here ? - show() + show() </pre> It is possible to force matplotlib to draw after every command, which @@ -800,21 +732,23 @@ script with <tt>python -i myscript.py -dTkAgg</tt> and then change it interactively from the shell. -<b>IMPORTANT: show should called at most once per script and it should +<b>IMPORTANT: show should be called at most once per script and it should be the last line of your script. At that point, the GUI takes control of the interpreter. If you want to force a figure draw, use <a href=matplotlib.pyplot.html#-draw>draw</a> instead.</b> """), - + ('PSGUI', - 'Can I save PS/EPS from a GUI backend?', + 'Can I save PS/EPS/PDF/SVG etc. from a GUI backend?', """ -Yep. Just choose a filename that contains <tt>ps</tt> in the extension, eg -<tt>somefile.ps</tt> or <tt>somefile.eps</tt> and matplotlib will try -and do the right thing. That is, if it's an eps file, it will include -a bounding box, if it's a ps file it will output plain postscript. It -is recommended you use matplotlib-0.50 or later for this feature to -work properly."""), +Yep. Just choose a filename that contains the desired extension and +matplotlib will try and do the right thing. That is, if it's an eps +file, it will include a bounding box, if it's a ps file it will output +plain postscript. It is recommended you use matplotlib-0.91 or later +for this feature to work properly, since far fewer options are +available for all GUI backends prior to that. +"""), + ('TEXTOVERLAP', 'My title or ticklabel or whatever is overlapping some other figure element, what should I do?', """ @@ -842,7 +776,7 @@ ('DYNAMIC', - 'Can matplotlib do dynamic plots, like digital oscilloscopes or animations?', + 'Can matplotlib do dynamic plots, like digital oscilloscopes or animations?', """ Absolutely. See for example, <a href=examples/anim.py>anim.py</a> and <a href=examples/system_monitor.py>system_monitor.py</a>"""), @@ -862,10 +796,10 @@ ('IMAGES', 'Can matplotlib handle image data?', """ -Yes - you can now plot images from numerix arraysq with <a +Yes - you can now plot images from numpy arrays with <a href=matplotlib.pyplot.html#-imshow>imshow</a>. You can load png files into arrays <a href=matplotlib.pyplot.html#-imread>imread</a>; -image loaders coming soon."""), +other image loaders coming soon."""), ('ROTATETICKS', 'How do I make vertical xticklabels?', @@ -876,7 +810,7 @@ from pylab import * plot([1,2,3,4], [1,4,9,16]) set(gca(), 'xticks', [1,2,3,4]) - labels = set(gca(), 'xticklabels', + labels = set(gca(), 'xticklabels', ['Frogs', 'Hogs', 'Bogs', 'Slogs']) set(labels, 'rotation', 'vertical') show() @@ -892,7 +826,7 @@ C:\GTK\etc\pango\pango.aliases. Add a line like <pre> -times = "times new roman,angsana new,mingliu,simsun,\\ +times = "times new roman,angsana new,mingliu,simsun,\\ gulimche,ms gothic,latha,mangal,code2000" </pre> @@ -904,7 +838,7 @@ experiencing for ages with matplotlib. I was getting WARNING **: Couldn't load font "MS Sans Serif 8" falling back to "Sans 8" - errors. + errors. It's addressed in their FAQ, http://www2.arnes.si/~sopjsimo/gimp/faq.html>, reproduced here: @@ -924,20 +858,20 @@ I took option B and now all is well with both Gimp and Matplotlib. I'm running Win98 and the Gimp FAQ entry hints that it may be a -problem in Win98,ME and NT installations. +problem in Win98,ME and NT installations. </pre> -""" +""" ), - + ('FREETYPE2', "Why are my fonts not being rendered properly?", """ -This is probably due to an outdated freetype2 library. The latest -version is 2.1.9. See <a href=matplotlib.font_manager.html>font manager +This is probably due to an outdated freetype2 library. +See <a href=matplotlib.font_manager.html>font manager docs</a> for details. """ ), @@ -945,17 +879,15 @@ """My SVG viewer doesn't properly display special (TeX) characters ('\sum', '\infty',etc.) generated by mathtext. Is this a bug?""", """ -You need to install the BaKoMa fonts (TrueType version of the Computer +As of matplotlib-0.91.0, the glyph outlines for the font are embedded +directly in the SVG file, so this should not occur. + +For matplotlib-0.90.0 and earlier, +you need to install the BaKoMa fonts (TrueType version of the Computer Modern fonts) on your system. The BaKoMa fonts come packaged with matplotlib. They are located in the "site-packages/matplotlib/mpl-data/fonts/ttf" dir (the cm*.ttf files). Installation of the fonts varies from OS to OS. - -Alternatively, as of r3498 (matplotlib > 0.90.1) you can set -svg.embed_char_paths to True in your matplotlibrc file. This -setting makes matplotlib embed all fonts as paths in the SVG file, -which results in a "portable" SVG file, at the cost of bigger file -size and uneditable text. """ ), ('LEAKS', @@ -970,14 +902,13 @@ the <tt>--without-pymalloc</tt> flag, which disables pool allocation.) If after sufficient iterations, you still see that memory usage is increasing, it is a likely a bonafide memory leak that should be -reported. +reported.<p> -</a> The unit directory of the source tree contains an example scripts useful for diagnosing and reporting memory leaks. For -example, <a href="http://matplotlib.svn.sourceforge.net/viewvc/matplotlib/trunk/matplotlib/unit/memleak_hawaii.py?view=markup"><tt>memleak_hawaii.py</tt> +example, <a href="http://matplotlib.svn.sourceforge.net/viewvc/matplotlib/trunk/matplotlib/unit/memleak_hawaii.py?view=markup"><tt>memleak_hawaii.py</tt></a> is useful for finding plotting-related memory leaks, - and <a href="http://matplotlib.svn.sourceforge.net/viewvc/matplotlib/trunk/matplotlib/unit/memleak_gui.py?view=markup"><tt>memleak_gui.py</tt> + and <a href="http://matplotlib.svn.sourceforge.net/viewvc/matplotlib/trunk/matplotlib/unit/memleak_gui.py?view=markup"><tt>memleak_gui.py</tt></a> helps find memory leaks in the GUI-backend. Please use something like these when reporting leaks so we get an idea of the magnitude of the problem (i.e. bytes per figure). Also please provide @@ -987,12 +918,12 @@ obvious coding errors vis-a-vis matplotlib.<p> There are some known memory leaks in matplotlib-0.90.1 when used in -conjunction with the Tk, Gtk, Wx, Qt and Qt4 GUI backends. Many of -these leaks have resolutions in the current SVN version of matplotlib. +conjunction with the Tk, Gtk, Wx, Qt and Qt4 GUI backends. Many of +these leaks have resolutions in the current SVN version of matplotlib. However, the following library versions are known to have leaks that matplotlib triggers. If you have one of these versions and are experiencing memory leaks, you should upgrade your library. This is -not an exhaustive list. +not an exhaustive list.<p> <ul> <li><b>Wx backend:</b>wxPython-2.8.2 or earlier in the 2.8 series @@ -1028,7 +959,7 @@ This will print out all of the reference cycles that are preventing the uncollectable objects from being freed. The code should then be modified to prevent these cycles, or break the cycles during - destruction. + destruction.<p> <li><b>Real references:</b> Sometimes objects are legitimately being held onto by other Python objects. When this happens, you would @@ -1045,7 +976,7 @@ <pre> original_objects = [id(x) for x in gc.get_objects()] # ... do something that leaks objects - new_objects = [x for x in gc.get_objects() + new_objects = [x for x in gc.get_objects() if id(x) not in original_objects] </pre> You can then determine what is referencing those objects and @@ -1053,7 +984,7 @@ <pre> print gc.get_referents(x) </pre> - The code should be modified to prevent these unwanted references. + The code should be modified to prevent these unwanted references.<p> <li><b>C/C++ leaks in extension objects:</b> These is the classic problem of objects that are "malloc'd/new'd" and never @@ -1104,9 +1035,9 @@ href=http://matplotlib.sf.net/examples>examples</a> explaining how to embed matplotlib in your GUI of choice. """), - + ) - + @header@ <h2> matplotlib FAQ </h2> Modified: trunk/htdocs/fonts.html.template =================================================================== --- trunk/htdocs/fonts.html.template 2007-11-30 17:39:05 UTC (rev 4529) +++ trunk/htdocs/fonts.html.template 2007-11-30 19:31:05 UTC (rev 4530) @@ -1,39 +1,29 @@ -@header@ -<h2>Font handling</h2> +@header@ +<h2>Font handling</h2> I have spent a lot of time trying to make text in matplotlib look good. This has been a limitation of many pre-exisiting python graphing solutions, but with the rise of freetype and anti-aliased rendering for linux, it is now possible to have great looking fonts. -<h3><a name=TTFFONTS>Freetype fonts: GD, Agg, Paint</a></h3> +<h3><a name=TTFFONTS>Truetype fonts</a></h3> -The GD, Agg, and Paint backends all support freetype fonts, which +All of the backends support Truetype fonts, which provide high quality, anti-aliased font rendering to PNG and JPEG output -without X support. This is particularly useful for batch processing +with or without X support. This is particularly useful for batch processing over terminal, or for web application servers. <p> You need to have truetype '*.ttf' files on your system to use these fonts. The font finder does platform dependent searches to find them. -In addition, matplotlib distributes the <tt>Vera</tt> fonts from -bitstream, which were released under a permissive license, as well as -the BaKoMa computer modern TeX fonts, which are free for noncommerical -use. If you want more, set the environment variable <tt>TTFPATH</tt> to -point to them. Note, if you are on linux but have access to a licensed -copy of windows ttf fonts, the same <tt>*.ttf</tt> fonts in -<tt>C:\windows\fonts</tt> will work with matplotlib on linux if you -place them in your TTFPATH; see <a href=http://corefonts.sf.net>core -fonts</a>.<p> +In addition, matplotlib distributes +the <a href="http://www.gnome.org/fonts">Vera</a> fonts from +Bitstream, the BaKoMa Computer Modern TeX fonts, and +the <a href="http://www.stixfonts.org/">STIX</a> math fonts, all of +which are available under different permissive licenses. If you want +more, most of the time, matplotlib will pick up fonts installed in the +standard place(s) on your operating system. Note that on Linux, you +may need to run 'fc-cache' after installing new fonts.<p> -If you are using matplotlib to generate images for html, you may want to -consider using a backend which supports freetype2. freetype 2 tends to -render fonts better at very small raster sizes. See <a -href=faq.html#APPSERVER>matplotlib images in html</a> and <a -href=matplotlib.font_manager.html>font manager docs</a> for more -information. The Agg and GD image backends both support freetype2. If -you are trying to decide among an image backend, see the <a -href=faq.html#WHICHBACKEND>which backend should I use</a><p> - If you are aware of other freely distributable ttf fonts, please contact me. @@ -45,6 +35,14 @@ describing fonts. Formerly, matplotlib required the external packages fonttools and ttfquery, but no longer does.<p> +As of matplotlib-0.91.0, fonts can also be specified using the +fontconfig pattern syntax +described <a href="http://fontconfig.org/fontconfig-user.html">here</a>. +A fontconfig pattern string may be used in place of a FontProperties +class instance.<p> + +<h4>Font properties</h4> + Fonts are described by properties, and the font manager searches your system for the font that most closely matches the properties you choose. The 6 font properties used for font matching are given below with their @@ -56,7 +54,7 @@ for an example setting the default font property and changing it in the middle of the script. -<h4>font family</h4> +<h5>font family</h5> The font.family property has five values: 'serif' (e.g. Times), 'sans-serif' (e.g. Helvetica), 'cursive' (e.g. Zapf-Chancery), 'fantasy' @@ -72,58 +70,35 @@ font manager will try and find the best font no matter which platform you run on. -<h4>font style</h4> +<h5>font style</h5> The font.style property has three values: normal (or roman), italic or oblique. The oblique style will be used for italic, if it is not present. -<h4>font variant</h4> +<h5>font variant</h5> The font.variant property has two values: normal or small-caps. For TrueType fonts, which are scalable fonts, small-caps is equivalent to using a font size of 'smaller', or about 83% of the current font size. -<h4>font weight</h4> +<h5>font weight</h5> The font.weight property has effectively 13 values: normal, bold, bolder, lighter, 100, 200, 300, ..., 900. Normal is the same as 400, and bold is 700. bolder and lighter are relative values with respect to the current weight. -<h4>font stretch</h4> +<h5>font stretch</h5> The font.stretch property has 11 values: ultra-condensed, extra-condensed, condensed, semi-condensed, normal, semi-expanded, expanded, extra-expanded, ultra-expanded, wider, and narrower. This property is not currently implemented. -<h4>font size</h4> +<h5>font size</h5> The font.size property has 11 values: xx-small, x-small, small, medium, large, x-large, xx-large, larger, smaller, length (such as 12pt), and percentage. larger and smaller are relative values. percentage is not yet implemented. - - -<h3><a name=GTKFONTS>GTK</a></h3> - -The most recent versions of GTK (2.2.4.1 and later) and pygtk-2.0.0 -and later on linux have freetype font support built-in by default. If -you are using an older version, set the environment variable -<tt>GDK_USE_XFT</tt> - -<pre> -export GDK_USE_XFT=1 # bash and friends -</pre> - -or - -<pre> -setenv GDK_USE_XFT 1 # csh and friends -</pre> - -If you are using GTK under windows, see <a -href=http://www.async.com.br/faq/pygtk/index.py?req=show&file=faq21.011.htp>the -pygtk FAQ</a>. - <h3><a name=PSFONTS>Postscript</a></h3> <a Modified: trunk/htdocs/tutorial.html.template =================================================================== --- trunk/htdocs/tutorial.html.template 2007-11-30 17:39:05 UTC (rev 4529) +++ trunk/htdocs/tutorial.html.template 2007-11-30 19:31:05 UTC (rev 4530) @@ -27,11 +27,11 @@ ) - -@header@ -<h2>Using matplotlib</h2> +@header@ +<h2>Using matplotlib</h2> + If you are new to python, I recommend reading the <a href=http://docs.python.org/tut/tut.html>python tutorial</a> and <a @@ -190,7 +190,7 @@ There are several ways to set line properties <pre> # Use keyword args -plot(x, y, linewidth=2.0) +plot(x, y, linewidth=2.0) # Use the setter methods of the Line2D instance. plot returns a list # of lines; eg line1, line2 = plot(x1,y1,x2,x2). Below I have only @@ -202,7 +202,7 @@ # Use the set command. The example below uses matlab handle graphics # style command to set multiple properties on a list of lines. Set # works transparently with a list of objects or a single object -lines = plot(x1, y1, x2, y2) +lines = plot(x1, y1, x2, y2) setp(lines, color='r', linewidth=2.0) @@ -301,8 +301,8 @@ from pylab import * figure(1) # the first figure -plot([1,2,3]) -figure(2) # a second figure +plot([1,2,3]) +figure(2) # a second figure plot([4,5,6]) figure(1) # figure 1 current @@ -311,7 +311,7 @@ </pre> You can clear the current figure with <a -href=matplotlib.pyplot.html#-clf>clf</a> and the current axes with +href=matplotlib.pyplot.html#-clf>clf</a> and the current axes with <a href=matplotlib.pyplot.html#-cla>cla</a> @@ -448,8 +448,13 @@ Any text element can use math text. You need to use raw strings (preceed the quotes with an <tt>'r'</tt>), and surround the string -text with dollar signs, as in TeX. +text with dollar signs, as in TeX. Regular text and mathtext can be +interleaved within the same string.<p> +Mathtext can use the Bakoma Computer Modern fonts, STIX fonts or a +Unicode font that you provide. The mathtext font can be selected with +the customization variable "mathtext.fontset".<p> + <pre> # plain text title('alpha > beta') @@ -458,7 +463,7 @@ title(r'$\alpha > \beta$') </pre> -To make subscripts and superscripts use the '_' and '^' symbols, as in +To make subscripts and superscripts use the '_' and '^' symbols, as in <pre> title(r'$\alpha_i > \beta_i$') @@ -475,17 +480,29 @@ </pre> The default font is <i>italics</i> for mathematical symbols. To -change fonts, eg, to write "sin" in a roman font, enclose the text in +change fonts, eg, to write "sin" in a Roman font, enclose the text in a font command, as in <pre> -text(1,2, r's(t) = $\cal{A}\rm{sin}(2 \omega t)$') +text(1,2, r's(t) = $\mathcal{A}\mathrm{sin}(2 \omega t)$') </pre> +Even better, many commonly used function names that are typeset in a +Roman font have shortcuts. So the expression above could be written +as follows: + +<pre> +text(1,2, r's(t) = $\mathcal{A}\sin(2 \omega t)$') +</pre> + Here "s" and "t" are variable in italics font (default), "sin" is in -roman font, and the amplitude "A" is in caligraphy font. The font -choices are roman <tt>\rm</tt>, italics <tt>\it</tt>, caligraphy -<tt>\cal</tt>, and typewriter <tt>\tt</tt> <p> +Roman font, and the amplitude "A" is in caligraphy font. The font +choices are Roman <tt>\mathrm</tt>, italics <tt>\mathit</tt>, caligraphy +<tt>\mathcal</tt>, and typewriter <tt>\mathtt</tt>. If using the STIX +fonts, you also have the choice +of blackboard (double-struck) <tt>\mathbb</tt>, +circled <tt>\mathcircled</tt>, Fraktur <tt>\mathfrak</tt>, script +(cursive) <tt>\mathscr</tt> and sans-serif <tt>\mathsf</tt>.<p> The following accents are provided: <tt>\hat</tt>, <tt>\breve</tt>, <tt>\grave</tt>, <tt>\bar</tt>, <tt>\acute</tt>, <tt>\tilde</tt>, @@ -506,7 +523,7 @@ plot(t,s) title(r'$\alpha_i > \beta_i$', fontsize=20) text(1, -0.6, r'$\sum_{i=0}^\infty x_i$', fontsize=20) -text(0.6, 0.6, r'$\cal{A}\rm{sin}(2 \omega t)$', +text(0.6, 0.6, r'$\mathcal{A}\mathrm{sin}(2 \omega t)$', fontsize=20) xlabel('time (s)') ylabel('volts (mV)') @@ -526,7 +543,7 @@ to navigate through the data set. You can select either the "classic" or newfangled toolbar "toolbar2" in your <a href=matplotlibrc>matplotlibrc</a> file using the <tt>toolbar</tt> -setting. +setting. If you want to interact with very large data sets, matplotlib supports data clipping where the data is clipped with numerix before they are @@ -553,7 +570,7 @@ so you never have to move the mouse to pan the x-axis left and right. If you don't have a wheel mouse, buy one!<p> -<table> +<table> <tr><td><img src=tut/navcontrols.png></td></tr> <tr><td width=400> <i>The left widget that says 'All' on the controls on the bottom of the figure is a drop down menu used to select which axes the @@ -586,7 +603,7 @@ <b>The Pan/Zoom</b> button has two modes: pan and zoom. Click this toolbar button to activate this mode. Then put your mouse somewhere over an -axes. +axes. <ul> <li>Pan Mode: Press the left mouse button and hold it, dragging it to @@ -594,7 +611,7 @@ you pressed will be moved to the point where you released. If you press 'x' or 'y' while panning, the motion will be contrained to the x or y axis, respectively</li> - + <li>Zoom Mode: Press the right mouse button, dragging it to a new position. The x axis will be zoomed in proportionate to the rightward movement and zoomed out proportionate to the leftward @@ -626,7 +643,7 @@ PNG over JPG and TIFF, which is why I haven't worked too hard to include these other image formats in agg.<p> -<table> +<table> <tr><td><img src=tut/navcontrols2.png></td></tr> <tr><td width=400> <i>The new toolbar2</i> </td></tr> </table><br> @@ -687,13 +704,13 @@ plot([1,2,3]) glines = getp(gca(), 'gridlines') # make the gridlines blue and thicker -setp(glines, 'color', 'b', 'linewidth', 2) +setp(glines, 'color', 'b', 'linewidth', 2) -# get the patches.Rectangle instance increase +# get the patches.Rectangle instance increase # the linewidth of the rectangular axis frame -frame = gca(gca(), 'frame') -setp(frame, 'linewidth', 2) - +frame = gca(gca(), 'frame') +setp(frame, 'linewidth', 2) + </pre> @@ -770,7 +787,7 @@ print 'you clicked', event.x, event.y #register this function with the event handler -connect('button_press_event', click) +connect('button_press_event', click) </pre> Then whenever the user clicks anywhere on the figure canvas, your @@ -791,7 +808,7 @@ <tr><td>canvas</td><td>The FigureCanvas instance the event occured in</td></tr> <tr><td>key</td><td>The key press if any, eg 'a', 'b', '1'. Also records 'control and 'shift'</td></tr> -</table> +</table> You can connect to the following events: 'button_press_event', 'button_release_event', 'motion_notify_event'. @@ -868,7 +885,7 @@ <pre> # make up some random y values -s = rand(len(dates)) +s = rand(len(dates)) plot_date(dates, s) </pre> @@ -909,10 +926,10 @@ <pre> # every 5 years -years = YearLocator(5) +years = YearLocator(5) # every quarter -months = MonthLocator(range(3,13,3)) +months = MonthLocator(range(3,13,3)) </pre> The date tick locators MinuteLocator, HourLocator, DayLocator, @@ -939,7 +956,7 @@ </td></tr> </table><br> -<h4>timezones with pytz</h4> +<h4>timezones with pytz</h4> Timezone support is provided via the <a href=http://pytz.sourceforge.net/>pytz</a> module. This module This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site. |