matplotlib Code

149 lines (117 with data), 6.3 kB

@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>

The GD, Agg, and Paint backends all support freetype fonts, which
provide high quality, anti-aliased font rendering to PNG and JPEG output
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>

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.

<h3><a name=MANAGER>The font manager</a></h3>

Thanks to Paul Barrett, matplotlib now has a freestanding, cross
platform font finder, resusing parts of ttfquery, which implements the
<a href=http://www.w3.org/TR/1999/REC-CSS1-19990111>W3C standard</a> for
describing fonts. Formerly, matplotlib required the external packages
fonttools and ttfquery, but no longer does.<p>

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
default values.  The <a
href=matplotlib.font_manager.html#FontProperties>FontProperties</a>
class is used to describe these properties.<p>

See <a href=examples/font_properties_demo.py>font_properties_demo.py</a>
for an example setting the default font property and changing it in the
middle of the script.

<h4>font family</h4> 

The font.family property has five values: 'serif' (e.g. Times),
'sans-serif' (e.g. Helvetica), 'cursive' (e.g. Zapf-Chancery), 'fantasy'
(e.g. Western), and 'monospace' (e.g. Courier).  Each of these font
families has a default list of font names in decreasing order of
priority associated with them.  You describe which family you want by
choosing, eg, <tt>family='serif'</tt>, and the font manager will search
the font.serif list looking for one of the named fonts on your system.
The lists are user configurable, and reside in your <a
href=matplotlibrc>matplotlibrc</a> file. <p>

This allows you to choose your family in your matplotlib script and the
font manager will try and find the best font no matter which platform
you run on.

<h4>font style</h4>  

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>  
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>  
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>  
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>  
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
href="http://www.adobe.com/products/postscript/main.html">Postscript</a>,
despite its age, is still a great output format.  Most publishers
accept it, it scales to arbitrary resolutions, you can import it
directly into LaTeX document, and send it directly to postscript
printers.<p>

The only requirement to generate postscript output is the Numeric
module and some AFM fonts on your system.  Even the latter is only a
quasi-requirement, because matplotlib ships with some of the most
popular font files.  These are <it>Adobe Font Metric</it> files, which
have the '*.afm' extension.  matplotlib comes with it's own AFM parser
to read these files and select the best match for the font you've
chosen.  If you want additional fonts, set the <tt>AFMPATH</tt>
environment variable to point to the dir containing your AFM font
files.  matplotlib willl recursively search any directory in
<tt>AFMPATH</tt>, so you only need to specify a base directory if
multiple subdirectories contaning '*.afm' files.<p>


@footer@