@header@
Font handling
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.
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.
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 Vera 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 TTFPATH to
point to them. Note, if you are on linux but have access to a licensed
copy of windows ttf fonts, the same *.ttf fonts in
C:\windows\fonts will work with matplotlib on linux if you
place them in your TTFPATH; see core
fonts.
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 matplotlib images in html and font manager docs for more
information. The Agg and GD image backends both support freetype2. If
you are trying to decide among an image backend, see the which backend should I use
If you are aware of other freely distributable ttf fonts, please
contact me.
Thanks to Paul Barrett, matplotlib now has a freestanding, cross
platform font finder, resusing parts of ttfquery, which implements the
W3C standard for
describing fonts. Formerly, matplotlib required the external packages
fonttools and ttfquery, but no longer does.
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 FontProperties
class is used to describe these properties.
See font_properties_demo.py
for an example setting the default font property and changing it in the
middle of the script.
font family
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, family='serif', 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 .matplotlibrc file.
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.
font style
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.
font variant
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.
font weight
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.
font stretch
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.
font size
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.
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
GDK_USE_XFT
export GDK_USE_XFT=1 # bash and friends
or
setenv GDK_USE_XFT 1 # csh and friends
If you are using GTK under windows, see the
pygtk FAQ.
Postscript,
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.
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 Adobe Font Metric 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 AFMPATH
environment variable to point to the dir containing your AFM font
files. matplotlib willl recursively search any directory in
AFMPATH, so you only need to specify a base directory if
multiple subdirectories contaning '*.afm' files.
@footer@