The ImageFont Module

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.

Examples

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)

Functions

load

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.

load_path

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.

truetype

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

load_default

ImageFont.load_default() => Font instance

(New in 1.1.4) Load a "better than nothing" default font.

Methods

Font objects must implement the following methods, which are used by the ImageDraw layer.

getsize

font.getsize(text) => (width, height)

Returns the width and height of the given text, as a 2-tuple.

getmask

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.