`matplotlib.ft2font`#

class matplotlib.ft2font.FT2Font(self: matplotlib.ft2font.FT2Font, filename: object, hinting_factor: int = 8, *, _fallback_list: list[matplotlib.ft2font.FT2Font] | None = None, _kerning_factor: int = 0)#

Bases:

An object representing a single font face.

Outside of the font itself and querying its properties, this object provides methods for processing text strings into glyph shapes.

Commonly, one will use FT2Font.set_text to load some glyph metrics and outlines. Then FT2Font.draw_glyphs_to_bitmap and FT2Font.get_image may be used to get a rendered form of the loaded string.

For single characters, FT2Font.load_char or FT2Font.load_glyph may be used, either directly for their return values, or to use FT2Font.draw_glyph_to_bitmap or FT2Font.get_path.

Useful metrics may be examined via the Glyph return values or FT2Font.get_kerning. Most dimensions are given in 26.6 or 16.6 fixed-point integers representing subpixels. Divide these values by 64 to produce floating-point pixels.

Parameters:

filenamestr or file-like: The source of the font data in a format (ttf or ttc) that FreeType can read.
hinting_factorint, optional: Must be positive. Used to scale the hinting in the x-direction.
_fallback_listlist of FT2Font, optional: A list of FT2Font objects used to find missing glyphs.

Warning

This API is both private and provisional: do not use it directly.
_kerning_factorint, optional: Used to adjust the degree of kerning.

Warning

This API is private: do not use it directly.

property ascender#: Ascender in 26.6 units.

property bbox#: Face global bounding box (xmin, ymin, xmax, ymax).

clear(self: matplotlib.ft2font.FT2Font) → None#: Clear all the glyphs, reset for a new call to set_text.

property descender#: Descender in 26.6 units.

draw_glyph_to_bitmap(self: matplotlib.ft2font.FT2Font, image: matplotlib.ft2font.FT2Image, x: float | int, y: float | int, glyph: matplotlib.ft2font.Glyph, *, antialiased: bool = True) → None#

Draw a single glyph to the bitmap at pixel locations x, y.

Note it is your responsibility to create the image manually with the correct size before this call is made.

If you want automatic layout, use set_text in combinations with draw_glyphs_to_bitmap. This function is instead intended for people who want to render individual glyphs (e.g., returned by load_char) at precise locations.

Parameters:

imageFT2Image: The image buffer on which to draw the glyph.
x, yint: The pixel location at which to draw the glyph.
glyphGlyph: The glyph to draw.
antialiasedbool, default: True: Whether to render glyphs 8-bit antialiased or in pure black-and-white.

See also

draw_glyphs_to_bitmap

draw_glyphs_to_bitmap(self: matplotlib.ft2font.FT2Font, *, antialiased: bool = True) → None#

Draw the glyphs that were loaded by set_text to the bitmap.

The bitmap size will be automatically set to include the glyphs.

Parameters:

antialiasedbool, default: True: Whether to render glyphs 8-bit antialiased or in pure black-and-white.

See also

draw_glyph_to_bitmap

property face_flags#: Face flags; see FaceFlags.

property family_name#: Face family name.

property fname#: The original filename for this object.

get_bitmap_offset(self: matplotlib.ft2font.FT2Font) → tuple#

Get the (x, y) offset for the bitmap if ink hangs left or below (0, 0).

Since Matplotlib only supports left-to-right text, y is always 0.

Returns:

x, yfloat: The x and y offset in 26.6 subpixels of the bitmap. To get x and y in pixels, divide these values by 64.

See also

get_width_height
get_descent

get_char_index(self: matplotlib.ft2font.FT2Font, codepoint: int) → int#

Return the glyph index corresponding to a character code point.

Parameters:

codepointint: A character code point in the current charmap (which defaults to Unicode.)

Returns:

int: The corresponding glyph index.

See also

set_charmap
select_charmap
get_glyph_name
get_name_index

get_charmap(self: matplotlib.ft2font.FT2Font) → dict#

Return a mapping of character codes to glyph indices in the font.

The charmap is Unicode by default, but may be changed by set_charmap or select_charmap.

Returns:

dict[int, int]: A dictionary of the selected charmap mapping character codes to their corresponding glyph indices.

get_descent(self: matplotlib.ft2font.FT2Font) → int#

Get the descent of the current string set by set_text.

The rotation of the string is accounted for.

Returns:

int: The descent in 26.6 subpixels of the bitmap. To get the descent in pixels, divide these values by 64.

See also

get_bitmap_offset
get_width_height

get_glyph_name(self: matplotlib.ft2font.FT2Font, index: int) → str#

Retrieve the ASCII name of a given glyph index in a face.

Due to Matplotlib's internal design, for fonts that do not contain glyph names (per FT_FACE_FLAG_GLYPH_NAMES), this returns a made-up name which does not roundtrip through get_name_index.

Parameters:

indexint: The glyph number to query.

Returns:

str: The name of the glyph, or if the font does not contain names, a name synthesized by Matplotlib.

See also

get_name_index

get_image(self: matplotlib.ft2font.FT2Font) → numpy.ndarray#

Return the underlying image buffer for this font object.

Returns:

np.ndarray[int]

See also

get_path

get_kerning(self: matplotlib.ft2font.FT2Font, left: int, right: int, mode: Kerning | int) → int#

Get the kerning between two glyphs.

Parameters:

left, rightint

The glyph indices. Note these are not characters nor character codes. Use get_char_index to convert character codes to glyph indices.

modeKerning

A kerning mode constant:

DEFAULT - Return scaled and grid-fitted kerning distances.
UNFITTED - Return scaled but un-grid-fitted kerning distances.
UNSCALED - Return the kerning vector in original font units.

Changed in version 3.10: This now takes a ft2font.Kerning value instead of an int.

Returns:

int: The kerning adjustment between the two glyphs.

get_name_index(self: matplotlib.ft2font.FT2Font, name: str) → int#

Return the glyph index of a given glyph name.

Parameters:

namestr: The name of the glyph to query.

Returns:

int: The corresponding glyph index; 0 means 'undefined character code'.

See also

get_char_index
get_glyph_name

get_num_glyphs(self: matplotlib.ft2font.FT2Font) → int#: Return the number of loaded glyphs.

get_path(self: matplotlib.ft2font.FT2Font) → tuple#

Get the path data from the currently loaded glyph.

Returns:

verticesnp.ndarray[double]: The (N, 2) array of vertices describing the current glyph.
codesnp.ndarray[np.uint8]: The (N, ) array of codes corresponding to the vertices.

See also

get_image
load_char
load_glyph
set_text

get_ps_font_info(self: matplotlib.ft2font.FT2Font) → tuple#

Return the information in the PS Font Info structure.

For more information, see the FreeType documentation on this structure.

Returns:

versionstr
noticestr
full_namestr
family_namestr
weightstr
italic_angleint
is_fixed_pitchbool
underline_positionint
underline_thicknessint

get_sfnt(self: matplotlib.ft2font.FT2Font) → dict#

Load the entire SFNT names table.

Returns:

dict[tuple[int, int, int, int], bytes]

The SFNT names table; the dictionary keys are tuples of:

(platform-ID, ISO-encoding-scheme, language-code, description)

and the values are the direct information from the font table.

get_sfnt_table(self: matplotlib.ft2font.FT2Font, name: str) → dict | None#

Return one of the SFNT tables.

Parameters:

name{"head", "maxp", "OS/2", "hhea", "vhea", "post", "pclt"}: Which table to return.

Returns:

dict[str, Any]: The corresponding table; for more information, see the FreeType documentation.

get_width_height(self: matplotlib.ft2font.FT2Font) → tuple#

Get the dimensions of the current string set by set_text.

The rotation of the string is accounted for.

Returns:

width, heightfloat: The width and height in 26.6 subpixels of the current string. To get width and height in pixels, divide these values by 64.

See also

get_bitmap_offset
get_descent

property height#: Height in 26.6 units; used to compute a default line spacing (baseline-to-baseline distance).

load_char(self: matplotlib.ft2font.FT2Font, charcode: int, flags: Union[LoadFlags, int] = <LoadFlags.FORCE_AUTOHINT: 32>) → matplotlib.ft2font.Glyph#

Load character in current fontfile and set glyph.

Parameters:

charcodeint: The character code to prepare rendering information for. This code must be in the charmap, or else a .notdef glyph may be returned instead.
flagsLoadFlags, default: LoadFlags.FORCE_AUTOHINT: Any bitwise-OR combination of the LoadFlags flags.

Changed in version 3.10: This now takes an ft2font.LoadFlags instead of an int.

Returns:

Glyph: The glyph information corresponding to the specified character.

See also

load_glyph
select_charmap
set_charmap

load_glyph(self: matplotlib.ft2font.FT2Font, glyph_index: int, flags: Union[LoadFlags, int] = <LoadFlags.FORCE_AUTOHINT: 32>) → matplotlib.ft2font.Glyph#

Load glyph index in current fontfile and set glyph.

Note that the glyph index is specific to a font, and not universal like a Unicode code point.

Parameters:

glyph_indexint: The glyph index to prepare rendering information for.
flagsLoadFlags, default: LoadFlags.FORCE_AUTOHINT: Any bitwise-OR combination of the LoadFlags flags.

Changed in version 3.10: This now takes an ft2font.LoadFlags instead of an int.

Returns:

Glyph: The glyph information corresponding to the specified index.

See also

load_char

property max_advance_height#: Maximum vertical cursor advance for all glyphs.

property max_advance_width#: Maximum horizontal cursor advance for all glyphs.

property num_charmaps#: Number of charmaps in the face.

property num_faces#: Number of faces in file.

property num_fixed_sizes#: Number of bitmap in the face.

property num_glyphs#: Number of glyphs in the face.

property num_named_instances#: Number of named instances in the face.

property postscript_name#: PostScript name of the font.

property scalable#: Whether face is scalable; attributes after this one are only defined for scalable faces.

select_charmap(self: matplotlib.ft2font.FT2Font, i: int) → None#

Select a charmap by its FT_Encoding number.

For more details on character mapping, see the FreeType documentation.

Parameters:

iint: The charmap in the form defined by FreeType: https://freetype.org/freetype2/docs/reference/ft2-character_mapping.html#ft_encoding

See also

set_charmap
get_charmap

set_charmap(self: matplotlib.ft2font.FT2Font, i: int) → None#

Make the i-th charmap current.

For more details on character mapping, see the FreeType documentation.

Parameters:

iint: The charmap number in the range [0, num_charmaps).

See also

num_charmaps
select_charmap
get_charmap

set_size(self: matplotlib.ft2font.FT2Font, ptsize: float, dpi: float) → None#

Set the size of the text.

Parameters:

ptsizefloat: The size of the text in points.
dpifloat: The DPI used for rendering the text.

set_text(self: matplotlib.ft2font.FT2Font, string: str, angle: float = 0.0, flags: Union[LoadFlags, int] = <LoadFlags.FORCE_AUTOHINT: 32>) → numpy.ndarray[numpy.float64]#

Set the text string and angle.

You must call this before draw_glyphs_to_bitmap.

Parameters:

stringstr: The text to prepare rendering information for.
anglefloat: The angle at which to render the supplied text.
flagsLoadFlags, default: LoadFlags.FORCE_AUTOHINT: Any bitwise-OR combination of the LoadFlags flags.

Changed in version 3.10: This now takes an ft2font.LoadFlags instead of an int.

Returns:

np.ndarray[double]: A sequence of x,y glyph positions in 26.6 subpixels; divide by 64 for pixels.

property style_flags#: Style flags; see StyleFlags.

property style_name#: Style name.

property underline_position#: Vertical position of the underline bar.

property underline_thickness#: Thickness of the underline bar.

property units_per_EM#: Number of font units covered by the EM.

class matplotlib.ft2font.FT2Image(self: matplotlib.ft2font.FT2Image, width: float | int, height: float | int)#

Bases:

An image buffer for drawing glyphs.

Parameters:

width, heightint: The dimensions of the image buffer.

draw_rect_filled(self: matplotlib.ft2font.FT2Image, x0: float | int, y0: float | int, x1: float | int, y1: float | int) → None#

Draw a filled rectangle to the image.

Parameters:

x0, y0, x1, y1float: The bounds of the rectangle from (x0, y0) to (x1, y1).

class matplotlib.ft2font.FaceFlags(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)#

Bases: Flag

Flags returned by FT2Font.face_flags.

For more information, see the FreeType documentation.

Added in version 3.10.

CID_KEYED = 4096#

COLOR = 16384#

EXTERNAL_STREAM = 1024#

FAST_GLYPHS = 128#

FIXED_SIZES = 2#

FIXED_WIDTH = 4#

GLYPH_NAMES = 512#

HINTER = 2048#

HORIZONTAL = 16#

KERNING = 64#

MULTIPLE_MASTERS = 256#

SCALABLE = 1#

SFNT = 8#

TRICKY = 8192#

VERTICAL = 32#

class matplotlib.ft2font.Glyph(self: matplotlib.ft2font.Glyph)#

Bases:

Information about a single glyph.

You cannot create instances of this object yourself, but must use FT2Font.load_char or FT2Font.load_glyph to generate one. This object may be used in a call to FT2Font.draw_glyph_to_bitmap.

For more information on the various metrics, see the FreeType documentation.

property bbox#: The control box of the glyph.

property height#: The glyph's height.

property horiAdvance#: Advance width for horizontal layout.

property horiBearingX#: Left side bearing for horizontal layout.

property horiBearingY#: Top side bearing for horizontal layout.

property linearHoriAdvance#: The advance width of the unhinted glyph.

property vertAdvance#: Advance height for vertical layout.

property vertBearingX#: Left side bearing for vertical layout.

property vertBearingY#: Top side bearing for vertical layout.

property width#: The glyph's width.

class matplotlib.ft2font.Kerning(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)#

Bases: Enum

Kerning modes for FT2Font.get_kerning.

For more information, see the FreeType documentation.

Added in version 3.10.

DEFAULT = 0#

UNFITTED = 1#

UNSCALED = 2#

class matplotlib.ft2font.LoadFlags(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)#

Bases: Flag

Flags for FT2Font.load_char, FT2Font.load_glyph, and FT2Font.set_text.

For more information, see the FreeType documentation.

Added in version 3.10.

COLOR = 1048576#

COMPUTE_METRICS = 2097152#

CROP_BITMAP = 64#

DEFAULT = 0#

FORCE_AUTOHINT = 32#

IGNORE_GLOBAL_ADVANCE_WIDTH = 512#

IGNORE_TRANSFORM = 2048#

LINEAR_DESIGN = 8192#

MONOCHROME = 4096#

NO_AUTOHINT = 32768#

NO_BITMAP = 8#

NO_HINTING = 2#

NO_RECURSE = 1024#

NO_SCALE = 1#

PEDANTIC = 128#

RENDER = 4#

TARGET_LCD = 196608#

TARGET_LCD_V = 262144#

TARGET_LIGHT = 65536#

TARGET_MONO = 131072#

TARGET_NORMAL = 0#

VERTICAL_LAYOUT = 16#

class matplotlib.ft2font.StyleFlags(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)#

Bases: Flag

Flags returned by FT2Font.style_flags.

For more information, see the FreeType documentation.

Added in version 3.10.

BOLD = 2#

ITALIC = 1#

NORMAL = 0#

matplotlib.ft2font#

`matplotlib.ft2font`#