| Python Imaging Library Handbook |
The ImageFont module defines a class with the same name. Instances of this class store bitmap fonts, and are used with the text method of the ImageDraw class.
PIL uses it's own font file format to store bitmap fonts. You can use the pilfont utility to convert BDF and PCF font descriptors (X window font formats) to this format.
Starting with version 1.1.4, PIL can be configured to support TrueType and OpenType fonts (as well as other font formats supported by the FreeType library). For earlier versions, TrueType support is only available as part of the imToolkit package.
Here's a simple example:
import ImageFont, ImageDraw
draw = ImageDraw.Draw(image)
# use a bitmap font
font = ImageFont.load("arial.pil")
draw.text((10, 10), "hello", font=font)
# use a truetype font
font = ImageFont.truetype("arial.ttf", 15)
draw.text((10, 25), "world", font=font)
ImageFont.load(file) => Font instance
Loads a font from the given file, and returns the corresponding font object. If this function fails, it raises an IOError exception.
ImageFont.load_path(file) => Font instance
Same as load, but searches for the file along sys.path if it's not found in the current directory.
ImageFont.truetype(file, size) => Font instance
Load a TrueType or OpenType font file, and create a font object. This function loads a font object from the given file, and creates a font object for a font of the given size.
On Windows, if the given file name does not exist, the loader also looks in Windows fonts directory.
This function requires the _imagingft service.
ImageFont.truetype(file, size, encoding=value) => Font instance
(New in 1.1.5) Load a TrueType or OpenType font file, and create a font object using the given encoding. Common encodings are "unic" (Unicode), "symb" (Microsoft Symbol), "ADOB" (Adobe Standard), "ADBE" (Adobe Expert), and "armn" (Apple Roman).
The following example draws a character using the Microsoft Symbol font, which uses the "symb" encoding and characters in the range 0xF000 to 0xF0FF:
font = ImageFont.truetype("symbol.ttf", 16, encoding="symb")
draw.text((0, 0), unichr(0xF000 + 0xAA))
ImageFont.load_default() => Font instance
(New in 1.1.4) Load a "better than nothing" default font.
Font objects must implement the following methods, which are used by the ImageDraw layer.
font.getsize(text) => (width, height)
Returns the width and height of the given text, as a 2-tuple.
font.getmask(text, mode="") => Image object
Returns a bitmap for the text. The bitmap should be an internal PIL storage memory instance (as defined by the Image.core interface module).
If the font uses antialiasing, the bitmap should have mode "L" and use a maximum value of 255. Otherwise, it should have mode "1".
(New in 1.1.5) The optional mode argument is used by some graphics drivers to indicate what mode the driver prefers; if empty, the renderer may return either mode. Note that the mode is always a string, to simplify C-level implementations.