matplotlib Code

122 lines (96 with data), 5.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>Truetype fonts</a></h3>

All of the backends support Truetype fonts, which
provide high quality, anti-aliased font rendering to PNG and JPEG output
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 <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 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>

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


<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'
(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.

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

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

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

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

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