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 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.
- source_font (
-
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: 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
methodParameters: 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:
PIL.ImageFont.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 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.
- font (
-
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