matplotlib.ft2font

classmatplotlib.ft2font.FT2Font(self:matplotlib.ft2font.FT2Font, filename:object, hinting_factor:SupportsInt=8, *, _fallback_list:collections.abc.Sequence[matplotlib.ft2font.FT2Font]|None=None, _kerning_factor:SupportsInt=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.

propertyascender

Ascender in 26.6 units.

propertybbox

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.

propertydescender

Descender in 26.6 units.

draw_glyph_to_bitmap(self:matplotlib.ft2font.FT2Font, image:matplotlib.ft2font.FT2Image, x:SupportsFloat|SupportsInt, y:SupportsFloat|SupportsInt, 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

propertyface_flags

Face flags; see FaceFlags.

propertyfamily_name

Face family name.

propertyfname

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:SupportsInt) → 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:SupportsInt) → 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:SupportsInt, right:SupportsInt, mode:Kerning|SupportsInt) → 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

propertyheight

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

load_char(self: matplotlib.ft2font.FT2Font, charcode: typing.SupportsInt, flags: LoadFlags | typing.SupportsInt = <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: typing.SupportsInt, flags: LoadFlags | typing.SupportsInt = <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

propertymax_advance_height

Maximum vertical cursor advance for all glyphs.

propertymax_advance_width

Maximum horizontal cursor advance for all glyphs.

propertynum_charmaps

Number of charmaps in the face.

propertynum_faces

Number of faces in file.

propertynum_fixed_sizes

Number of bitmap in the face.

propertynum_glyphs

Number of glyphs in the face.

propertynum_named_instances

Number of named instances in the face.

propertypostscript_name

PostScript name of the font.

propertyscalable

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

select_charmap(self:matplotlib.ft2font.FT2Font, i:SupportsInt) → 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) → 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, dpi:SupportsFloat) → 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: typing.SupportsFloat = 0.0, flags: LoadFlags | typing.SupportsInt = <LoadFlags.FORCE_AUTOHINT: 32>) → 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.

Returns:

np.ndarray[double]

A sequence of x,y glyph positions in 26.6 subpixels; divide by 64 for pixels.

propertystyle_flags

Style flags; see StyleFlags.

propertystyle_name

Style name.

propertyunderline_position

Vertical position of the underline bar.

propertyunderline_thickness

Thickness of the underline bar.

propertyunits_per_EM

Number of font units covered by the EM.

classmatplotlib.ft2font.FT2Image(self:matplotlib.ft2font.FT2Image, width:SupportsFloat|SupportsInt, height:SupportsFloat|SupportsInt)

Bases:

An image buffer for drawing glyphs.

Parameters:

width, heightint

The dimensions of the image buffer.

draw_rect_filled(self:matplotlib.ft2font.FT2Image, x0:SupportsFloat|SupportsInt, y0:SupportsFloat|SupportsInt, x1:SupportsFloat|SupportsInt, y1:SupportsFloat|SupportsInt) → None

Draw a filled rectangle to the image.

Parameters:

x0, y0, x1, y1float

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

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

SCALABLE=1

SFNT=8

TRICKY=8192

VERTICAL=32

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

propertybbox

The control box of the glyph.

propertyheight

The glyph's height.

propertyhoriAdvance

Advance width for horizontal layout.

propertyhoriBearingX

Left side bearing for horizontal layout.

propertyhoriBearingY

Top side bearing for horizontal layout.

propertylinearHoriAdvance

The advance width of the unhinted glyph.

propertyvertAdvance

Advance height for vertical layout.

propertyvertBearingX

Left side bearing for vertical layout.

propertyvertBearingY

Top side bearing for vertical layout.

propertywidth

The glyph's width.

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

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

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

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