`matplotlib.ft2font`#

classmatplotlib.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 methodsfor processing text strings into glyph shapes.

Commonly, one will useFT2Font.set_text to load some glyph metrics and outlines.ThenFT2Font.draw_glyphs_to_bitmap andFT2Font.get_image may be used to get arendered form of the loaded string.

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

Useful metrics may be examined via theGlyph return values orFT2Font.get_kerning. Most dimensions are given in 26.6 or 16.6 fixed-pointintegers representing subpixels. Divide these values by 64 to produce floating-pointpixels.

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

propertydescender#: 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 sizebefore this call is made.

If you want automatic layout, useset_text in combinations withdraw_glyphs_to_bitmap. This function is instead intended for people who want torender individual glyphs (e.g., returned byload_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 byset_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; seeFaceFlags.

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: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 byset_charmap orselect_charmap.

Returns:

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

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

Get the descent of the current string set byset_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 glyphindex in a face.

Due to Matplotlib's internal design, for fonts that do not contain glyph names (perFT_FACE_FLAG_GLYPH_NAMES), this returns a made-up name which doesnotroundtrip throughget_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 synthesizedby 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.Useget_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 aft2font.Kerning value instead of anint.

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

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 theFreeType 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, seethe FreeType documentation.

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

Get the dimensions of the current string set byset_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 andheight 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: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 inthe charmap, or else a.notdef glyph may be returned instead.
flagsLoadFlags, default:LoadFlags.FORCE_AUTOHINT: Any bitwise-OR combination of theLoadFlags flags.
Changed in version 3.10:This now takes anft2font.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 Unicodecode point.

Parameters:

glyph_indexint: The glyph index to prepare rendering information for.
flagsLoadFlags, default:LoadFlags.FORCE_AUTOHINT: Any bitwise-OR combination of theLoadFlags flags.
Changed in version 3.10:This now takes anft2font.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:int)→None#

Select a charmap by its FT_Encoding number.

For more details on character mapping, see theFreeType 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 theFreeType 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 textstring andangle.

You must call this beforedraw_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 theLoadFlags flags.
Changed in version 3.10:This now takes anft2font.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; seeStyleFlags.

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: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).

classmatplotlib.ft2font.FaceFlags(*values)#

Bases:Flag

Flags returned byFT2Font.face_flags.

For more information, seethe 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 useFT2Font.load_char orFT2Font.load_glyph to generate one. This object may beused in a call toFT2Font.draw_glyph_to_bitmap.

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