`mcfonts.providers.bitmap`¶

A bitmap provider, handling PNG glyphs.

Module Contents¶

Classes¶

`BitmapProvider`	The `bitmap` provider defines simple bitmap glyphs from a texture.

Functions¶

`assert_charlist_is_equal`(charlist)	Ensure that every string inside charlist has the same length as the first string.
`charlist_from_unicode_range`(start, end[, width])	Return a character list that contains characters from start to end in order.
`charlist_to_chars`(charlist)	Given charlist, yield all the characters that charlist covers.
`fit_chars_into_charlist`(chars[, charlist_length])	Given a list of chars, fit them into a charlist whose width is equal to charlist_length.
`is_charline_empty`(charline)	Given charline, return if it contains only spaces or null bytes.
`pad_chars_list`(chars_list[, pad_amount, ...])	Pad charlist so that all its strings have the same length.
`resource_to_charlist`(resource, character[, cell_bounds])	Given a path to a resource and a starting character, return an appropriate charlist.
`validate_charlist`(charlist[, resource, cell_bounds])	Given charlist, ensure that it's valid and doesn't have any possible issues.

class mcfonts.providers.bitmap.BitmapProvider(provider, origin, resource)¶

Bases: mcfonts.providers.base.Provider

The bitmap provider defines simple bitmap glyphs from a texture.

It references a single PNG file and declares a "chars" list of strings.

The characters inside each string entry inside the charlist will be mapped to the corresponding positions in the referenced file.

The texture is evenly divided according to the number of entries and the length of these entries.

Construct a Provider base class.

Parameters:¶

provider_type: A string of the value in the JSON "type" field.
origin : os.PathLike[str] | str¶: The absolute path to the provider's JSON file.
chars_covered: A set of the individual characters covered by this provider.
provider : mcfonts.utils.types.TypedProviderBitmap¶
resource : PIL.Image.Image | None¶

construct_glyphs()¶

Yield a tuple of (character, glyph) for every glyph available in the provider's resource.

Some glyphs may be empty or have no content.

Returns:¶: A yield of (character, Glyph), or None if there are no glyphs.
Return type:¶: collections.abc.Iterable[tuple[str, mcfonts.glyphs.BitmapGlyph]]

get_contents()¶

Return the contents of the provider.

Returns:¶: Dictionary of the provider.
Return type:¶: mcfonts.utils.types.TypedProviderBitmap

get_glyph_for_character(character)¶

Extract a desired character's sheet from this provider.

Glyph textures that are mapped to spaces or null padding return None. If there's more than one sheet mapped to a character (duplicate characters), the first occurance will be returned.

Parameters:¶

character : str¶: A single character.

Returns:¶

A PIL.Image.Image, or None if no glyph exists.

Return type:¶

mcfonts.glyphs.BitmapGlyph | None

get_icon()¶

Return a Unicode character that can be used to represent this provider in shorthand descriptions.

Returns:¶: A 1-character string.
Return type:¶: str

get_pack_versions()¶

Return a tuple of the minimum and maximum pack versions for which this provider is valid.

The first element is guaranteed to be an integer. There will always be a minimum version, even if it's 0. The second element may be an integer, or None. If it is None, there is no maximum version bound.

Returns:¶: A 2-element tuple of the minimum and maximum valid pack versions.
Return type:¶: tuple[int, None]

pretty_print()¶

Return a short one line description of the provider.

Returns:¶: A string of the provider's info, normally <icon> <type>: <info,...>.
Return type:¶: str

print_info(table_chars=True)¶

Print information about this provider.

Parameters:¶

table_chars : bool¶: Whether to print a 'chars' list as a square table, or as a simple string.

Return type:¶

None

reload_to_monochrome()¶

Replace the resource used in this provider with a grayscale version.

If the resource is already grayscale or if there's no resource, False will be returned. Otherwise, True.

This modifies the resource of this provider in place, and can't be undone.

Returns:¶: Boolean of success; if there's a resource, and it isn't already grayscale.
Return type:¶: bool

validate()¶

Specific tests for validating a provider.

This function checks values to ensure that they're correct and in an acceptable range.

If applicable, textures are checked to ensure all characters have a defined glyph, and that the dimensions are correct.

Warnings are printed through mcfonts.logger.warning().

Returns:¶: Nothing; problems are either raised or warned.
Return type:¶: None

yield_characters()¶

Yield strings of the individual characters this provider supports.

Returns:¶: A yield of strings of length 1, or None if no characters are present.
Return type:¶: collections.abc.Iterable[str]

yield_glyphs()¶

Yield a tuple of (character, glyph) for every glyph available in the provider's resource.

This is different from construct_glyphs() because it yields glyphs that have already been constructed and stored.

Returns:¶: A yield of (character, Glyph).
Return type:¶: collections.abc.Iterable[tuple[str, mcfonts.glyphs.BitmapGlyph | None]]

yield_glyphs_in_unirange(unirange_notation)¶

Given unirange_notation, return a dictionary of the requested characters to their glyphs.

Parameters:¶

unirange_notation : str¶: A string representing the requested range of chars. See https://pypi.org/project/unirange/.

Returns:¶

A yield of the requested glyphs that match unirange_notation.

Return type:¶

collections.abc.Iterable[tuple[str, mcfonts.glyphs.BitmapGlyph | None]]

mcfonts.providers.bitmap.assert_charlist_is_equal(charlist)¶

Ensure that every string inside charlist has the same length as the first string.

>>> assert_charlist_is_equal(["abc","de"])
(False, 3)
>>> assert_charlist_is_equal(["abc","def"])
(True, 3)
>>> assert_charlist_is_equal([])
(True, 0)
>>> assert_charlist_is_equal([""])
(True, 0)

Parameters:¶

charlist : list[str]¶: The charlist of strings to check lengths of.

Returns:¶

A tuple of (if the lengths are equal, the expected length).

Return type:¶

tuple[bool, int]

mcfonts.providers.bitmap.charlist_from_unicode_range(start, end, width=16)¶

Return a character list that contains characters from start to end in order.

Given a starting character start, and an ending character end, return a charlist that contains these characters in order, and whose width is equal to width.

>>> charlist_from_unicode_range("\u2600", "\u26ff")
[
    '☀☁☂☃☄★☆☇☈☉☊☋☌☍☎☏',
    '☐☑☒☓☔☕☖☗☘☙☚☛☜☝☞☟',
    '☠☡☢☣☤☥☦☧☨☩☪☫☬☭☮☯',
    '☰☱☲☳☴☵☶☷☸☹☺☻☼☽☾☿',
    '♀♁♂♃♄♅♆♇♈♉♊♋♌♍♎♏',
    '♐♑♒♓♔♕♖♗♘♙♚♛♜♝♞♟',
    '♠♡♢♣♤♥♦♧♨♩♪♫♬♭♮♯',
    '♰♱♲♳♴♵♶♷♸♹♺♻♼♽♾♿',
    '⚀⚁⚂⚃⚄⚅⚆⚇⚈⚉⚊⚋⚌⚍⚎⚏',
    '⚐⚑⚒⚓⚔⚕⚖⚗⚘⚙⚚⚛⚜⚝⚞⚟',
    '⚠⚡⚢⚣⚤⚥⚦⚧⚨⚩⚪⚫⚬⚭⚮⚯',
    '⚰⚱⚲⚳⚴⚵⚶⚷⚸⚹⚺⚻⚼⚽⚾⚿',
    '⛀⛁⛂⛃⛄⛅⛆⛇⛈⛉⛊⛋⛌⛍⛎⛏',
    '⛐⛑⛒⛓⛔⛕⛖⛗⛘⛙⛚⛛⛜⛝⛞⛟',
    '⛠⛡⛢⛣⛤⛥⛦⛧⛨⛩⛪⛫⛬⛭⛮⛯',
    '⛰⛱⛲⛳⛴⛵⛶⛷⛸⛹⛺⛻⛼⛽⛾⛿'
]
>>> charlist_from_unicode_range(" ", "\xff", 8)
[
    ' !"#$%&'',
    '()*+,-./',
    '01234567',
    '89:;<=>?',
    '@ABCDEFG',
    'HIJKLMNO',
    'PQRSTUVW',
    'XYZ[\\]^_',
    '`abcdefg',
    'hijklmno',
    'pqrstuvw',
    'xyz{|}~\x7f',
    '\x80\x81\x82\x83\x84\x85\x86\x87',
    '\x88\x89\x8a\x8b\x8c\x8d\x8e\x8f',
    '\x90\x91\x92\x93\x94\x95\x96\x97',
    '\x98\x99\x9a\x9b\x9c\x9d\x9e\x9f',
    '\xa0¡¢£¤¥¦§',
    '¨©ª«¬\xad®¯',
    '°±²³´µ¶·',
    '¸¹º»¼½¾¿',
    'ÀÁÂÃÄÅÆÇ',
    'ÈÉÊËÌÍÎÏ',
    'ÐÑÒÓÔÕÖ×',
    'ØÙÚÛÜÝÞß',
    'àáâãäåæç',
    'èéêëìíîï',
    'ðñòóôõö÷',
    'øùúûüýþÿ'
]

Parameters:¶

start : str¶: The starting single character.
end : str¶: The ending single character. Codepoint must be greater than the codepoint of start.
width : int¶: The number of characters to put in one row of the returned charlist.

Returns:¶

A charlist, with each string's length equal to width.

Return type:¶

list[str]

mcfonts.providers.bitmap.charlist_to_chars(charlist)¶

Given charlist, yield all the characters that charlist covers.

>>> chars = ['agtg', 'b', '5', 'c', 'd', 'e', 'f', '0', '1', '2', '3', '4', '5', '6', '7', '8']
>>> list(charlist_to_chars(chars))
['a', 'g', 't', 'g', 'b', '5', 'c', 'd', 'e', 'f', '0', '1', '2', '3', '4', '5', '6', '7', '8']

Parameters:¶

charlist : list[str]¶: The charlist.

Returns:¶

A yield of characters.

Return type:¶

collections.abc.Iterable[str]

mcfonts.providers.bitmap.fit_chars_into_charlist(chars, charlist_length=16)¶

Given a list of chars, fit them into a charlist whose width is equal to charlist_length.

>>> list(fit_chars_into_charlist(["thisisareallylongcharlist"]))
['thisisareallylon', 'gcharlist']
>>> list(fit_chars_into_charlist(["thisisareallylongcharlist"], 5))
['thisi', 'sarea', 'llylo', 'ngcha', 'rlist']

Parameters:¶

chars : list[str]¶: A list of chars.
charlist_length : int¶: The width to make each line of characters in the charlist equal to.

Returns:¶

Yield of lines in a charlist.

Return type:¶

collections.abc.Iterable[str]

mcfonts.providers.bitmap.is_charline_empty(charline)¶

Given charline, return if it contains only spaces or null bytes.

>>> is_charline_empty("\0\0\0\x20\x20\x20\0\0")
True
>>> is_charline_empty("         ")
True
>>> is_charline_empty("      xxx")
False

Parameters:¶

charline : str¶: A single string, likely part_notation of a wider charlist.

Returns:¶

If charline is all spaces or null bytes.

Return type:¶

bool

mcfonts.providers.bitmap.pad_chars_list(chars_list, pad_amount=0, padding_character=' ', pad_from='right')¶

Pad charlist so that all its strings have the same length.

>>> pad_chars_list(["abc", "de"])
['abc', 'de ']
>>> pad_chars_list(["abc", "defg"])
['abc ', 'defg']

Parameters:¶

chars_list : list[str]¶: Character list to pad.
pad_amount : int¶: What to pad the characters to; the ideal width. If this is 0, this will be determined from the largest length of strings in charlist.
padding_character : str¶: The character to pad with, default is a space.
pad_from : Literal[left, right]¶: Direction to pad the string from, left => "___Text", right => "Text___".

Returns:¶

The padded charlist list.

Return type:¶

list[str]

mcfonts.providers.bitmap.resource_to_charlist(resource, character, cell_bounds=(8, 8))¶

Given a path to a resource and a starting character, return an appropriate charlist.

Return a provider that has a charlist that correctly encompasses all chars covered by the resource. Glyphs in the resource that are empty are skipped.

Parameters:¶

resource : PIL.Image.Image¶: The resource to grab textures from.
character : str¶: A single character. The codepoint of this will increase by 1 on every glyph.
cell_bounds : tuple[int, int]¶: The dimensions of an individual glyph in resource. Glyph dimensions must be the same throughout the whole of resource.

Returns:¶

A chars list.

Return type:¶

list[str]

mcfonts.providers.bitmap.validate_charlist(charlist, resource=None, cell_bounds=(8, 8))¶

Given charlist, ensure that it's valid and doesn't have any possible issues.

Issues include:

Empty lines,
Uneven lines,
Duplicate characters,
*Padding chars in places where glyph exists in resource,
*Characters that will have an empty glyph in resource.

* Optional, requires resource.

Parameters:¶

charlist : list[str]¶: A charlist to validate.
resource : PIL.Image.Image | None¶: An optional PIL.Image.Image to validate glyph textures against.
cell_bounds : tuple[int, int]¶: Tuple of (glyph width, glyph height) for each glyph in resource.

Return type:¶

None

Last update: 2023 November 30

mcfonts.providers.bitmap¶

Module Contents¶

Classes¶

Functions¶

`mcfonts.providers.bitmap`¶