luma.core.bitmap_font

class luma.core.bitmap_font.bitmap_font[source]

Bases: object

An PIL.Imagefont style font.

The structure of this class was modeled after the PIL ImageFont class and is intended to be interchangable for PIL.ImageFont objects.

It has the following additional capabilities:

  • Allows fonts larger than 256 characters to be created

  • Font can be combined with other fonts

  • Font characters can be mapped to their correct unicode codepoints

  • Font can be initialized from a basic sprite table (with conditions)

New in version 1.16.0.

PUA_SPACE = 1015808
combine(source_font, characters=None, force=False)[source]

Combine two luma.core.bitmap_font instances.

Parameters:

  • source_font (luma.core.bitmap_font) – a luma.core.bitmap_font to copy from

  • characters (str) – (optional) A list of the characters to transfer from the source_font. If not provided, all of the characters within the source_font will be transferred.

  • force (bool) – If set, the source_font can overwrite values that already exists within this font. Default is False.

dumps()[source]

Serializes the font data for transfer or storage

Returns:

Serialized font data

Return type:

bytes

getmask(text, mode='1', *args, **kwargs)[source]

Implements an PIL.ImageFont compatible method to return the rendered image of a line of text

getsize(text, *args, **kwargs)[source]

Wrapper for _getsize to match the interface of PIL.ImageFont

load(filename)[source]

Load font from filename

Parameters:

filename (str) – the filename of the file containing the font data

Returns:

a font object

Return type:

luma.core.bitmap_font

load_pillow_font(file, mappings=None)[source]

Create luma.core.bitmap_font from a PIL ImageFont style font.

Parameters:

  • file (str) – The filename of the PIL.ImageFont to load

  • mappings (dict) – a dictionary of unicode to value pairs (optional). Mappings allow the appropriate unicode values to be provided for each character contained within the font

Returns:

a font object

Return type:

luma.core.bitmap_font

load_sprite_table(sprite_table, index, xwidth, glyph_size, cell_size, mappings=None)[source]

Load a font from a sprite table

Parameters:

  • sprite_table (PIL.Image) – A PIL.Image representation of every glyph within the font

  • index (list or other iterable) – The list of character values contained within sprite_table. This list MUST be in the same order that the glyphs for the characters appear within the sprite_table (in left to right, top to bottom order)

  • xwidth (int) – number of pixels between placements of each character in a line of text

  • glyph_size (tuple(int, int)) – tuple containing the width and height of each character in the font

  • cell_size (tuple(int, int)) – tuple containing the width and height of each cell in the sprite table. Defaults to the size of the glyphs.

  • mappings (dict) – a dictionary of unicode to value pairs (optional) Mappings allow the appropriate unicode values to be provided for each character contained within the font

Returns:

a font object

Return type:

luma.core.bitmap_font

loads(fontdata)[source]

Load luma.core.bitmap_font from a string of serialized data produced by the dumps method

Parameters:

fontdata (bytes) – The serialized font data that will be used to initialize the font. This data is produced by the luma.core.bitmap_font.dumps() method.

Returns:

a font object

Return type:

luma.core.bitmap_font

save(filename)[source]

Write luma.core.bitmap_font data to a file

class luma.core.bitmap_font.embedded_fonts(data, selected_font=0)[source]

Bases: ImageFont

Utility class to manage the set of fonts that are embedded within a compatible device.

Parameters:

  • data (dict) – The font data from the device. See note below.

  • selected_font (str or int) – The font that should be loaded as this device’s default. Will accept the font’s index or its name.

..note:

The class is used by devices which have embedded fonts and is not intended to be used directly. To initialize it requires providing a dictionary of font data including a PIL.Image.tobytes representation of a sprite_table which contains the glyphs of the font organized in consistent rows and columns, a metrics dictionary which provides the information on how to retrieve fonts from the sprite_table, and a mappings dictionary that provides unicode to table mappings.

New in version 1.16.0.

combine(font, characters=None, force=False)[source]

Combine the current font with a new one

Parameters:

  • font (luma.core.bitmap_font) – The font to combine with the current font

  • characters (list of unicode characters) – (Optional) A list of characters to move from the new font to the current font. If not provided all characters from the new font will be transferred.

  • force – Determines if conflicting characters should be ignored (default) or overwritten.

property current

Returns the currently selected font

getbbox(text, *args, **kwargs)

Returns bounding box (in pixels) of given text.

New in version 9.2.0.

Parameters:

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

Returns:

(left, top, right, bottom) bounding box

getlength(text, *args, **kwargs)

Returns length (in pixels) of given text. This is the amount by which following text should be offset.

New in version 9.2.0.

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.

Parameters:

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

    New in version 1.1.5.

Returns:

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

load(val)[source]

Load a font by its index value or name and return it

Parameters:

val (int or str) – The index or the name of the font to return

luma.core.bitmap_font.load(filename)[source]

Load a luma.core.bitmap_font file. This function creates a luma.core.bitmap_font object from the given luma.core.bitmap_font file, and returns the corresponding font object.

Parameters:

filename (str) – Filename of font file.

Returns:

A luma.core.bitmap_font object.

Raises:

  • OSError – If the file could not be read.

  • SyntaxError – If the file does not contain the expected data

luma.core.bitmap_font.load_pillow_font(filename, mappings=None)[source]

Load a PIL font file. This function creates a luma.core.bitmap_font object from the given PIL bitmap font file, and returns the corresponding font object.

Parameters:

  • filename (str) – Filename of font file.

  • mappings (dict) – a dictionary of unicode to value pairs (optional)

Returns:

A font object.

Raises:

  • OSError – If the file could not be read.

  • SyntaxError – If the file does not contain the expected data

luma.core.bitmap_font.load_sprite_table(sprite_table, index, xwidth, glyph_size, cell_size=None, mappings=None)[source]

Create a luma.core.bitmap_font from a sprite table.

Parameters:

  • sprite_table (str or PIL.Image) – Filename of a sprite_table file or a PIL.Image containing the sprite_table

  • index (list or other iterable) – The list of character values contained within sprite_table. This list MUST be in the same order that the glyphs for the characters appear within the sprite_table (in left to right, top to bottom order)

  • xwidth (int) – number of pixels between placements of each character in a line of text

  • glyph_size (tuple(int, int)) – tuple containing the width and height of each character in the font

  • cell_size (tuple(int, int)) – tuple containing the width and height of each cell in the sprite table. Defaults to the size of the glyphs.

  • mappings (dict) – a dictionary of unicode to value pairs (optional)

Returns:

A font object.

Raises:

  • OSError – If the file could not be read.

  • SyntaxError – If the file does not contain the expected data

luma.core.bitmap_font.loads(data)[source]

Load a luma.core.bitmap_font from a string of serialized data. This function creates a luma.core.bitmap_font object from serialized data produced from the dumps method and returns the corresponding font object.

Parameters:

data (str) – Serialized luma.core.bitmap_font data.

Returns:

A luma.core.bitmap_font object.

Raises:

ValueError – If the data does not a valid luma.core.bitmap_font