ImageFont Module

ImageFont Module

The ImageFont module defines a class with the same name. Instances ofthis class store bitmap fonts, and are used with thePIL.ImageDraw.Draw.text() method.

PIL uses its own font file format to store bitmap fonts. You can use thepilfont utility to convert BDF and PCF font descriptors (X windowfont formats) to this format.

Starting with version 1.1.4, PIL can be configured to support TrueType andOpenType fonts (as well as other font formats supported by the FreeTypelibrary). For earlier versions, TrueType support is only available as part ofthe imToolkit package

Example

from PIL 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

PIL.ImageFont.load(filename)[source]
Load a font file. This function loads a font object from the givenbitmap font file, and returns the corresponding font object.

Parameters:filename – Name of font file.Returns:A font object.Raises:IOError – If the file could not be read.

PIL.ImageFont.loadpath(_filename)[source]
Load font file. Same as load(), but searches for abitmap font along the Python path.

Parameters:filename – Name of font file.Returns:A font object.Raises:IOError – If the file could not be read.

PIL.ImageFont.truetype(font=None, size=10, index=0, encoding='', layout_engine=None)[source]
Load a TrueType or OpenType font from a file or file-like object,and create a font object.This function loads a font object from the given file or file-likeobject, and creates a font object for a font of the given size.

Pillow uses FreeType to open font files. If you are opening many fontssimultaneously on Windows, be aware that Windows limits the number of filesthat can be open in C at once to 512. If you approach that limit, anOSError may be thrown, reporting that FreeType “cannot open resource”.

This function requires the _imagingft service.

Parameters:

font – A filename or file-like object containing a TrueType font.If the file is not found in this filename, the loader may alsosearch in other directories, such as the fonts/directory on Windows or /Library/Fonts/,/System/Library/Fonts/ and ~/Library/Fonts/ onmacOS.
size – The requested size, in points.
index – Which font face to load (default is first available face).
encoding –
Which font encoding to use (default is Unicode). Possibleencodings include (see the FreeType documentation for moreinformation):
- ”unic” (Unicode)
- ”symb” (Microsoft Symbol)
- ”ADOB” (Adobe Standard)
- ”ADBE” (Adobe Expert)
- ”ADBC” (Adobe Custom)
- ”armn” (Apple Roman)
- ”sjis” (Shift JIS)
- ”gb ” (PRC)
- ”big5”
- ”wans” (Extended Wansung)
- ”joha” (Johab)
- ”lat1” (Latin-1)
  This specifies the character set to use. It does not alter theencoding of any text provided in subsequent operations.
layout_engine – Which layout engine to use, if available:ImageFont.LAYOUT_BASIC or ImageFont.LAYOUT_RAQM.Returns:
A font object.
Raises:
IOError – If the file could not be read.

PIL.ImageFont.load_default()[source]
Load a “better than nothing” default font.

New in version 1.1.4.

Returns:A font object.

Methods

class PIL.ImageFont.ImageFont[source]
PIL font wrapper
- getmask(text, mode='', *args, **kwargs)[source]
- Create a bitmap for the text.

If the font uses antialiasing, the bitmap should have mode L and use amaximum value of 255. Otherwise, it should have mode 1.

Parameters:

- **text** – Text to render.
- **mode** –

Used by some graphics drivers to indicate what mode thedriver prefers; if empty, the renderer may return eithermode. Note that the mode is always a string, to simplifyC-level implementations.

New in version 1.1.5.

Returns:
An internal PIL storage memory instance as defined by thePIL.Image.core interface module.

getsize(text, *args, **kwargs)[source]
Returns width and height (in pixels) of given text.

Parameters:text – Text to measure.Returns:(width, height)

class PIL.ImageFont.FreeTypeFont(font=None, size=10, index=0, encoding='', layout_engine=None)[source]
FreeType font wrapper (requires _imagingft service)
- fontvariant(_font=None, size=None, index=None, encoding=None, layout_engine=None)[source]
- Create a copy of this FreeTypeFont object,using any specified arguments to override the settings.

Parameters are identical to the parameters used to initialize thisobject.

Returns:A FreeTypeFont object.

get_variation_axes()[source]

Returns:A list of the axes in a variation font.Raises:IOError – If the font is not a variation font.

get_variation_names()[source]

Returns:A list of the named styles in a variation font.Raises:IOError – If the font is not a variation font.

getmask(text, mode='', direction=None, features=None, language=None, stroke_width=0)[source]
Create a bitmap for the text.

If the font uses antialiasing, the bitmap should have mode L and use amaximum value of 255. Otherwise, it should have mode 1.

Parameters:

- **text** – Text to render.
- **mode** –

Used by some graphics drivers to indicate what mode thedriver prefers; if empty, the renderer may return eithermode. Note that the mode is always a string, to simplifyC-level implementations.

New in version 1.1.5.

- **direction** –

Direction of the text. It can be ‘rtl’ (right toleft), ‘ltr’ (left to right) or ‘ttb’ (top to bottom).Requires libraqm.

New in version 4.2.0.

- **features** –

A list of OpenType font features to be used during textlayout. This is usually used to turn on optionalfont features that are not enabled by default,for example ‘dlig’ or ‘ss01’, but can be alsoused to turn off default font features forexample ‘-liga’ to disable ligatures or ‘-kern’to disable kerning. To get all supportedfeatures, seehttps://docs.microsoft.com/en-us/typography/opentype/spec/featurelistRequires libraqm.

New in version 4.2.0.

- **language** –

Language of the text. Different languages may usedifferent glyph shapes or ligatures. This parameter tellsthe font which language the text is in, and to apply thecorrect substitutions as appropriate, if available.It should be a _BCP 47 language code_Requires libraqm.

New in version 6.0.0.

- **stroke_width** –

The width of the text stroke.

New in version 6.2.0.

Returns:
An internal PIL storage memory instance as defined by thePIL.Image.core interface module.

getmask2(text, mode='', fill=, direction=None, features=None, language=None, stroke_width=0, *args, **kwargs)[source]
Create a bitmap for the text.

If the font uses antialiasing, the bitmap should have mode L and use amaximum value of 255. Otherwise, it should have mode 1.

Parameters:

- **text** – Text to render.
- **mode** –

Used by some graphics drivers to indicate what mode thedriver prefers; if empty, the renderer may return eithermode. Note that the mode is always a string, to simplifyC-level implementations.

New in version 1.1.5.

- **direction** –

Direction of the text. It can be ‘rtl’ (right toleft), ‘ltr’ (left to right) or ‘ttb’ (top to bottom).Requires libraqm.

New in version 4.2.0.

- **features** –

New in version 4.2.0.

- **language** –

New in version 6.0.0.

- **stroke_width** –

The width of the text stroke.

New in version 6.2.0.

Returns:
A tuple of an internal PIL storage memory instance as defined by thePIL.Image.core interface module, and the text offset, thegap between the starting coordinate and the first marking

getmetrics()[source]

Returns:A tuple of the font ascent (the distance from the baseline tothe highest outline point) and descent (the distance from thebaseline to the lowest outline point, a negative value)

getname()[source]

Returns:A tuple of the font family (e.g. Helvetica) and the font style(e.g. Bold)

getoffset(text)[source]
Returns the offset of given text. This is the gap between thestarting coordinate and the first marking. Note that this gap isincluded in the result of getsize().

Parameters:text – Text to measure.Returns:A tuple of the x and y offset

getsize(text, direction=None, features=None, language=None, stroke_width=0)[source]
Returns width and height (in pixels) of given text if rendered in font withprovided direction, features, and language.

Parameters:

- **text** – Text to measure.
- **direction** –

Direction of the text. It can be ‘rtl’ (right toleft), ‘ltr’ (left to right) or ‘ttb’ (top to bottom).Requires libraqm.

New in version 4.2.0.

- **features** –

New in version 4.2.0.

- **language** –

New in version 6.0.0.

- **stroke_width** –

The width of the text stroke.

New in version 6.2.0.

Returns:
(width, height)

getsizemultiline(_text, direction=None, spacing=4, features=None, language=None, stroke_width=0)[source]
Returns width and height (in pixels) of given text if rendered in fontwith provided direction, features, and language, while respectingnewline characters.

Parameters:

- **text** – Text to measure.
- **direction** – Direction of the text. It can be ‘rtl’ (right toleft), ‘ltr’ (left to right) or ‘ttb’ (top to bottom).Requires libraqm.
- **spacing** – The vertical gap between lines, defaulting to 4 pixels.
- **features** – A list of OpenType font features to be used during textlayout. This is usually used to turn on optionalfont features that are not enabled by default,for example ‘dlig’ or ‘ss01’, but can be alsoused to turn off default font features forexample ‘-liga’ to disable ligatures or ‘-kern’to disable kerning. To get all supportedfeatures, see[https://docs.microsoft.com/en-us/typography/opentype/spec/featurelist](https://docs.microsoft.com/en-us/typography/opentype/spec/featurelist)Requires libraqm.
- **language** –

New in version 6.0.0.

- **stroke_width** –

The width of the text stroke.

New in version 6.2.0.

Returns:
(width, height)

setvariation_by_axes(_axes)[source]

Parameters:axes – A list of values for each axis.Raises:IOError – If the font is not a variation font.

setvariation_by_name(_name)[source]

Parameters:name – The name of the style.Raises:IOError – If the font is not a variation font.

class PIL.ImageFont.TransposedFont(font, orientation=None)[source]
Wrapper for writing rotated or mirrored text