matplotlib.ft2font#

class matplotlib.ft2font.FT2Font(self: matplotlib.ft2font.FT2Font, filename: object, hinting_factor: SupportsInt | SupportsIndex | None = None, *, face_index: SupportsInt | SupportsIndex = 0, _fallback_list: collections.abc.Sequence[matplotlib.ft2font.FT2Font] | None = None, _kerning_factor: SupportsInt | SupportsIndex | None = None, _warn_if_used: bool = False)#

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, bytes, os.PathLike, or io.BinaryIO

The source of the font data in a format (ttf or ttc) that FreeType can read.

face_indexint, optional

The index of the face in the font file to load.

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

_warn_if_usedbool, optional

Used to trigger missing glyph warnings.

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()#

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:

image2d array of uint8

The image buffer on which to draw the glyph.

x, yint

The position of the glyph's top left corner.

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 face_index#

The index of the font in the file.

property family_name#

Face family name.

property fname#

The original filename for this object.

get_bitmap_offset(self: matplotlib.ft2font.FT2Font) → tuple[int, int]#

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: SupportsInt | SupportsIndex, *, _fallback: bool = True) → 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.)

_fallbackbool

Whether to enable fallback fonts while searching for a character.

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: SupportsInt | SupportsIndex) → 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.typing.NDArray[numpy.uint8]#

Return the underlying image buffer for this font object.

Returns:

np.ndarray[int]

See also

get_path

get_kerning(self: matplotlib.ft2font.FT2Font, left: SupportsInt | SupportsIndex, right: SupportsInt | SupportsIndex, mode: Kerning | SupportsInt | SupportsIndex) → 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[int, int]#

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: SupportsInt | SupportsIndex, flags: LoadFlags | SupportsInt | SupportsIndex = <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: SupportsInt | SupportsIndex, flags: LoadFlags | SupportsInt | SupportsIndex = <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: SupportsInt | SupportsIndex) → 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: SupportsInt | SupportsIndex) → 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: SupportsFloat | SupportsIndex, dpi: SupportsFloat | SupportsIndex) → 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: SupportsFloat | SupportsIndex = 0.0, flags: LoadFlags | SupportsInt | SupportsIndex = <LoadFlags.FORCE_AUTOHINT: 32>, *, features: collections.abc.Sequence[str] | None = None, language: collections.abc.Sequence[tuple[str, typing.SupportsInt | typing.SupportsIndex, typing.SupportsInt | typing.SupportsIndex]] | None | str=None) → numpy.typing.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.

featurestuple[str, ...]

The font feature tags to use for the font.

Available font feature tags may be found at https://learn.microsoft.com/en-us/typography/opentype/spec/featurelist

Added in version 3.11.

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: SupportsInt | SupportsIndex | SupportsFloat | SupportsIndex, height: SupportsInt | SupportsIndex | SupportsFloat | SupportsIndex)#

Bases:

An image buffer for drawing glyphs.

Parameters:

width, heightint

The dimensions of the image buffer.

draw_rect_filled(self: matplotlib.ft2font.FT2Image, x0: SupportsInt | SupportsIndex | SupportsFloat | SupportsIndex, y0: SupportsInt | SupportsIndex | SupportsFloat | SupportsIndex, x1: SupportsInt | SupportsIndex | SupportsFloat | SupportsIndex, y1: SupportsInt | SupportsIndex | SupportsFloat | SupportsIndex) → 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(*values)#

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#

SBIX = 131072#

SBIX_OVERLAY = 262144#

SCALABLE = 1#

SFNT = 8#

SVG = 65536#

TRICKY = 8192#

VARIATION = 32768#

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(*values)#

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.LayoutItem(self: matplotlib.ft2font.LayoutItem)#

Bases:

property char#

The character code for the item.

property ft_object#

The FT_Face of the item.

property glyph_index#

The glyph index for the item.

property prev_kern#

The kerning between this item and the previous one.

property x#

The x position of the item.

property y#

The y position of the item.

class matplotlib.ft2font.LoadFlags(*values)#

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.

BITMAP_METRICS_ONLY = 4194304#

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#

NO_SVG = 16777216#

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.RenderMode(*values)#

Bases: Enum

Render modes.

For more information, see the FreeType documentation.

Added in version 3.10.

LCD = 3#

LCD_V = 4#

LIGHT = 1#

MONO = 2#

NORMAL = 0#

SDF = 5#

class matplotlib.ft2font.StyleFlags(*values)#

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#