ImageFont Module

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

PIL uses its 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

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)

功能

PIL.ImageFont.load(filename)

Load a font file. This function loads a font object from the given bitmap font file, and returns the corresponding font object.

参数

filename – Name of font file.

返回

A font object.

引发

IOError – If the file could not be read.

PIL.ImageFont.load_path(filename)

Load font file. Same as load(), but searches for a bitmap font along the Python path.

参数

filename – Name of font file.

返回

A font object.

引发

IOError – If the file could not be read.

PIL.ImageFont.truetype(font=None, size=10, index=0, encoding='', layout_engine=None)

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-like object, and creates a font object for a font of the given size.

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

This function requires the _imagingft service.

参数

• font – A filename or file-like object containing a TrueType font. If the file is not found in this filename, the loader may also search in other directories, such as the fonts/ directory on Windows or /Library/Fonts/, /System/Library/Fonts/ and ~/Library/Fonts/ on macOS.

• 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). Possible encodings include (see the FreeType documentation for more information):

  • ”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 the encoding of any text provided in subsequent operations.

• layout_engine – Which layout engine to use, if available: ImageFont.LAYOUT_BASIC or ImageFont.LAYOUT_RAQM.

返回

A font object.

引发

IOError – If the file could not be read.

PIL.ImageFont.load_default()

Load a “better than nothing” default font.

1.1.4 新版功能.

返回

A font object.

Methods

class PIL.ImageFont.ImageFont

PIL font wrapper

getmask(text, mode='', *args, **kwargs)

Create a bitmap for the text.

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

参数

• text – Text to render.

• mode –

  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.

  1.1.5 新版功能.

返回

An internal PIL storage memory instance as defined by the PIL.Image.core interface module.

getsize(text, *args, **kwargs)

Returns width and height (in pixels) of given text.

参数

text – Text to measure.

返回

(width, height)

class PIL.ImageFont.FreeTypeFont(font=None, size=10, index=0, encoding='', layout_engine=None)

FreeType font wrapper (requires _imagingft service)

font_variant(font=None, size=None, index=None, encoding=None, layout_engine=None)

Create a copy of this FreeTypeFont object, using any specified arguments to override the settings.

Parameters are identical to the parameters used to initialize this object.

返回

A FreeTypeFont object.

get_variation_axes()

返回

A list of the axes in a variation font.

引发

IOError – If the font is not a variation font.

get_variation_names()

返回

A list of the named styles in a variation font.

引发

IOError – If the font is not a variation font.

getmask(text, mode='', direction=None, features=None, language=None, stroke_width=0)

Create a bitmap for the text.

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

参数

• text – Text to render.

• mode –

  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.

  1.1.5 新版功能.

• direction –

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

  4.2.0 新版功能.

• features –

  A list of OpenType font features to be used during text layout. This is usually used to turn on optional font features that are not enabled by default, for example ‘dlig’ or ‘ss01’, but can be also used to turn off default font features for example ‘-liga’ to disable ligatures or ‘-kern’ to disable kerning. To get all supported features, see https://docs.microsoft.com/en-us/typography/opentype/spec/featurelist Requires libraqm.

  4.2.0 新版功能.

• language –

  Language of the text. Different languages may use different glyph shapes or ligatures. This parameter tells the font which language the text is in, and to apply the correct substitutions as appropriate, if available. It should be a BCP 47 language code <https://www.w3.org/International/articles/language-tags/> Requires libraqm.

  6.0.0 新版功能.

• stroke_width –

  The width of the text stroke.

  6.2.0 新版功能.

返回

An internal PIL storage memory instance as defined by the PIL.Image.core interface module.

getmask2(text, mode='', fill=<built-in function fill>, direction=None, features=None, language=None, stroke_width=0, *args, **kwargs)

Create a bitmap for the text.

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

参数

• text – Text to render.

• mode –

  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.

  1.1.5 新版功能.

• direction –

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

  4.2.0 新版功能.

• features –

  A list of OpenType font features to be used during text layout. This is usually used to turn on optional font features that are not enabled by default, for example ‘dlig’ or ‘ss01’, but can be also used to turn off default font features for example ‘-liga’ to disable ligatures or ‘-kern’ to disable kerning. To get all supported features, see https://docs.microsoft.com/en-us/typography/opentype/spec/featurelist Requires libraqm.

  4.2.0 新版功能.

• language –

  Language of the text. Different languages may use different glyph shapes or ligatures. This parameter tells the font which language the text is in, and to apply the correct substitutions as appropriate, if available. It should be a BCP 47 language code <https://www.w3.org/International/articles/language-tags/> Requires libraqm.

  6.0.0 新版功能.

• stroke_width –

  The width of the text stroke.

  6.2.0 新版功能.

返回

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

getmetrics()

返回

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

getname()

返回

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

getoffset(text)

Returns the offset of given text. This is the gap between the starting coordinate and the first marking. Note that this gap is included in the result of getsize().

参数

text – Text to measure.

返回

A tuple of the x and y offset

getsize(text, direction=None, features=None, language=None, stroke_width=0)

Returns width and height (in pixels) of given text if rendered in font with provided direction, features, and language.

参数

• text – Text to measure.

• direction –

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

  4.2.0 新版功能.

• features –

  A list of OpenType font features to be used during text layout. This is usually used to turn on optional font features that are not enabled by default, for example ‘dlig’ or ‘ss01’, but can be also used to turn off default font features for example ‘-liga’ to disable ligatures or ‘-kern’ to disable kerning. To get all supported features, see https://docs.microsoft.com/en-us/typography/opentype/spec/featurelist Requires libraqm.

  4.2.0 新版功能.

• language –

  Language of the text. Different languages may use different glyph shapes or ligatures. This parameter tells the font which language the text is in, and to apply the correct substitutions as appropriate, if available. It should be a BCP 47 language code <https://www.w3.org/International/articles/language-tags/> Requires libraqm.

  6.0.0 新版功能.

• stroke_width –

  The width of the text stroke.

  6.2.0 新版功能.

返回

(width, height)

getsize_multiline(text, direction=None, spacing=4, features=None, language=None, stroke_width=0)

Returns width and height (in pixels) of given text if rendered in font with provided direction, features, and language, while respecting newline characters.

参数

• text – Text to measure.

• direction – Direction of the text. It can be ‘rtl’ (right to left), ‘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 text layout. This is usually used to turn on optional font features that are not enabled by default, for example ‘dlig’ or ‘ss01’, but can be also used to turn off default font features for example ‘-liga’ to disable ligatures or ‘-kern’ to disable kerning. To get all supported features, see https://docs.microsoft.com/en-us/typography/opentype/spec/featurelist Requires libraqm.

• language –

  Language of the text. Different languages may use different glyph shapes or ligatures. This parameter tells the font which language the text is in, and to apply the correct substitutions as appropriate, if available. It should be a BCP 47 language code <https://www.w3.org/International/articles/language-tags/> Requires libraqm.

  6.0.0 新版功能.

• stroke_width –

  The width of the text stroke.

  6.2.0 新版功能.

返回

(width, height)

set_variation_by_axes(axes)

参数

axes – A list of values for each axis.

引发

IOError – If the font is not a variation font.

set_variation_by_name(name)

参数

name – The name of the style.

引发

IOError – If the font is not a variation font.

class PIL.ImageFont.TransposedFont(font, orientation=None)

Wrapper for writing rotated or mirrored text