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 forPIL.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
) – aluma.core.bitmap_font
to copy fromcharacters (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:
- 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:
- load_pillow_font(file, mappings=None)[source]
Create
luma.core.bitmap_font
from a PIL ImageFont style font.- Parameters:
- Returns:
a font object
- Return type:
- 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:
- loads(fontdata)[source]
Load
luma.core.bitmap_font
from a string of serialized data produced by thedumps
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:
- 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:
- ..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 fontcharacters (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 mode1
.- 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.
- luma.core.bitmap_font.load(filename)[source]
Load a
luma.core.bitmap_font
file. This function creates aluma.core.bitmap_font
object from the givenluma.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:
- 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 aluma.core.bitmap_font
object from serialized data produced from thedumps
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