Face

class freetype.Face(path_or_stream, index=0)

FT_Face wrapper

FreeType root face class structure. A face object models a typeface in a font file.

ascender

The typographic ascender of the face, expressed in font units. For font formats not having this information, it is set to ‘bbox.yMax’. Only relevant for scalable formats.

attach_file(filename)

Attach data to a face object. Normally, this is used to read additional information for the face object. For example, you can attach an AFM file that comes with a Type 1 font to get the kerning values and other metrics.

Parameters:filename – Filename to attach

Note

The meaning of the ‘attach’ (i.e., what really happens when the new file is read) is not fixed by FreeType itself. It really depends on the font format (and thus the font driver).

Client applications are expected to know what they are doing when invoking this function. Most drivers simply do not implement file attachments.

available_sizes

A list of FT_Bitmap_Size for all bitmap strikes in the face. It is set to NULL if there is no bitmap strike.

bbox

The font bounding box. Coordinates are expressed in font units (see ‘units_per_EM’). The box is large enough to contain any glyph from the font. Thus, ‘bbox.yMax’ can be seen as the ‘maximal ascender’, and ‘bbox.yMin’ as the ‘minimal descender’. Only relevant for scalable formats.

Note that the bounding box might be off by (at least) one pixel for hinted fonts. See FT_Size_Metrics for further discussion.

charmap

The current active charmap for this face.

charmaps

A list of the charmaps of the face.

descender

The typographic descender of the face, expressed in font units. For font formats not having this information, it is set to ‘bbox.yMin’. Note that this field is usually negative. Only relevant for scalable formats.

face_flags

A set of bit flags that give important information about the face; see FT_FACE_FLAG_XXX for the details.

face_index

The index of the face in the font file. It is set to 0 if there is only one face in the font file.

family_name

The face’s family name. This is an ASCII string, usually in English, which describes the typeface’s family (like ‘Times New Roman’, ‘Bodoni’, ‘Garamond’, etc). This is a least common denominator used to list fonts. Some formats (TrueType & OpenType) provide localized and Unicode versions of this string. Applications should use the format specific interface to access them. Can be NULL (e.g., in fonts embedded in a PDF file).

get_advance(gindex, flags)

Retrieve the advance value of a given glyph outline in an FT_Face. By default, the unhinted advance is returned in font units.

Parameters:
  • gindex – The glyph index.
  • flags – A set of bit flags similar to those used when calling FT_Load_Glyph, used to determine what kind of advances you need.
Returns:

The advance value, in either font units or 16.16 format.

If FT_LOAD_VERTICAL_LAYOUT is set, this is the vertical advance corresponding to a vertical layout. Otherwise, it is the horizontal advance in a horizontal layout.

get_best_name_string(nameID, default_string='', preferred_order=None)

Retrieve a name string given nameID. Searches available font names matching nameID and returns the decoded bytes of the best match. “Best” is defined as a preferred list of platform/encoding/languageIDs which can be overridden by supplying a preferred_order matching the scheme of ‘sort_order’ (see below).

The routine will attempt to decode the string’s bytes to a Python str, when the platform/encoding[/langID] are known (Windows, Mac, or Unicode platforms).

If you prefer more control over name string selection and decoding than this routine provides:

  • call self._init_name_string_map()
  • use (nameID, platformID, encodingID, languageID) as a key into the self._name_strings dict
get_char_index(charcode)

Return the glyph index of a given character code. This function uses a charmap object to do the mapping.

Parameters:charcode – The character code.

Note:

If you use FreeType to manipulate the contents of font files directly, be aware that the glyph index returned by this function doesn’t always correspond to the internal indices used within the file. This is done to ensure that value 0 always corresponds to the ‘missing glyph’.
get_chars()

This generator function is used to return all unicode character codes in the current charmap of a given face. For each character it also returns the corresponding glyph index.

Returns:character code, glyph index
Note:
Note that ‘agindex’ is set to 0 if the charmap is empty. The character code itself can be 0 in two cases: if the charmap is empty or if the value 0 is the first valid character code.
get_first_char()

This function is used to return the first character code in the current charmap of a given face. It also returns the corresponding glyph index.

Returns:Glyph index of first character code. 0 if charmap is empty.

Note:

You should use this function with get_next_char to be able to parse all character codes available in a given charmap. The code should look like this:

Note that ‘agindex’ is set to 0 if the charmap is empty. The result itself can be 0 in two cases: if the charmap is empty or if the value 0 is the first valid character code.

get_format()

Return a string describing the format of a given face, using values which can be used as an X11 FONT_PROPERTY. Possible values are ‘TrueType’, ‘Type 1’, ‘BDF’, ‘PCF’, ‘Type 42’, ‘CID Type 1’, ‘CFF’, ‘PFR’, and ‘Windows FNT’.

get_fstype()

Return the fsType flags for a font (embedding permissions).

The return value is a tuple containing the freetype enum name as a string and the actual flag as an int

get_glyph_name(agindex, buffer_max=64)

This function is used to return the glyph name for the given charcode.

Parameters:
  • agindex – The glyph index.
  • buffer_max – The maximum number of bytes to use to store the glyph name.
  • glyph_name – The glyph name, possibly truncated.
get_kerning(left, right, mode=0)

Return the kerning vector between two glyphs of a same face.

Parameters:
  • left – The index of the left glyph in the kern pair.
  • right – The index of the right glyph in the kern pair.
  • mode – See FT_Kerning_Mode for more information. Determines the scale and dimension of the returned kerning vector.

Note:

Only horizontal layouts (left-to-right & right-to-left) are supported by this method. Other layouts, or more sophisticated kernings, are out of the scope of this API function – they can be implemented through format-specific interfaces.
get_name_index(name)

Return the glyph index of a given glyph name. This function uses driver specific objects to do the translation.

Parameters:name – The glyph name.
get_next_char(charcode, agindex)

This function is used to return the next character code in the current charmap of a given face following the value ‘charcode’, as well as the corresponding glyph index.

Parameters:
  • charcode – The starting character code.
  • agindex – Glyph index of next character code. 0 if charmap is empty.

Note:

You should use this function with FT_Get_First_Char to walk over all character codes available in a given charmap. See the note for this function for a simple code example.

Note that ‘agindex’ is set to 0 when there are no more codes in the charmap.

get_sfnt_name(index)

Retrieve a string of the SFNT ‘name’ table for a given index

Parameters:index – The index of the ‘name’ string.

Note:

The ‘string’ array returned in the ‘aname’ structure is not null-terminated. The application should deallocate it if it is no longer in use.

Use FT_Get_Sfnt_Name_Count to get the total number of available ‘name’ table entries, then do a loop until you get the right platform, encoding, and name ID.

get_var_blend_coords()

Get the current blend coordinates (-1.0..+1.0)

get_var_design_coords()

Get the current design coordinates

get_variation_info()

Retrieves variation space information for the current face.

glyph

The face’s associated glyph slot(s).

has_fixed_sizes

True whenever a face object contains some embedded bitmaps. See the ‘available_sizes’ field of the FT_FaceRec structure.

has_glyph_names

True whenever a face object contains some glyph names that can be accessed through FT_Get_Glyph_Name.

has_horizontal

True whenever a face object contains horizontal metrics (this is true for all font formats though).

has_kerning

True whenever a face object contains kerning data that can be accessed with FT_Get_Kerning.

has_multiple_masters

True whenever a face object contains some multiple masters. The functions provided by FT_MULTIPLE_MASTERS_H are then available to choose the exact design you want.

has_vertical

True whenever a face object contains vertical metrics.

height

The height is the vertical distance between two consecutive baselines, expressed in font units. It is always positive. Only relevant for scalable formats.

is_cid_keyed

True whenever a face object contains a CID-keyed font. See the discussion of FT_FACE_FLAG_CID_KEYED for more details.

If this macro is true, all functions defined in FT_CID_H are available.

is_fixed_width

True whenever a face object contains a font face that contains fixed-width (or ‘monospace’, ‘fixed-pitch’, etc.) glyphs.

is_scalable

true whenever a face object contains a scalable font face (true for TrueType, Type 1, Type 42, CID, OpenType/CFF, and PFR font formats.

is_sfnt

true whenever a face object contains a font whose format is based on the SFNT storage scheme. This usually means: TrueType fonts, OpenType fonts, as well as SFNT-based embedded bitmap fonts.

If this macro is true, all functions defined in FT_SFNT_NAMES_H and FT_TRUETYPE_TABLES_H are available.

is_tricky

True whenever a face represents a ‘tricky’ font. See the discussion of FT_FACE_FLAG_TRICKY for more details.

load_char(char, flags=4)

A function used to load a single glyph into the glyph slot of a face object, according to its character code.

Parameters:
  • char – The glyph’s character code, according to the current charmap used in the face.
  • flags – A flag indicating what to load for this glyph. The FT_LOAD_XXX constants can be used to control the glyph loading process (e.g., whether the outline should be scaled, whether to load bitmaps or not, whether to hint the outline, etc).

Note:

This function simply calls FT_Get_Char_Index and FT_Load_Glyph.
load_glyph(index, flags=4)

A function used to load a single glyph into the glyph slot of a face object.

Parameters:
  • index – The index of the glyph in the font file. For CID-keyed fonts (either in PS or in CFF format) this argument specifies the CID value.
  • flags – A flag indicating what to load for this glyph. The FT_LOAD_XXX constants can be used to control the glyph loading process (e.g., whether the outline should be scaled, whether to load bitmaps or not, whether to hint the outline, etc).

Note:

The loaded glyph may be transformed. See FT_Set_Transform for the details.

For subsetted CID-keyed fonts, ‘FT_Err_Invalid_Argument’ is returned for invalid CID values (this is, for CID values which don’t have a corresponding glyph in the font). See the discussion of the FT_FACE_FLAG_CID_KEYED flag for more details.

max_advance_height

The maximal advance height, in font units, for all glyphs in this face. This is only relevant for vertical layouts, and is set to ‘height’ for fonts that do not provide vertical metrics. Only relevant for scalable formats.

max_advance_width

The maximal advance width, in font units, for all glyphs in this face. This can be used to make word wrapping computations faster. Only relevant for scalable formats.

num_faces

The number of faces in the font file. Some font formats can have multiple faces in a font file.

num_fixed_sizes

The number of bitmap strikes in the face. Even if the face is scalable, there might still be bitmap strikes, which are called ‘sbits’ in that case.

num_glyphs

The number of glyphs in the face. If the face is scalable and has sbits (see ‘num_fixed_sizes’), it is set to the number of outline glyphs.

For CID-keyed fonts, this value gives the highest CID used in the font.

postscript_name

ASCII PostScript name of face, if available. This only works with PostScript and TrueType fonts.

select_charmap(encoding)

Select a given charmap by its encoding tag (as listed in ‘freetype.h’).

Note:

This function returns an error if no charmap in the face corresponds to the encoding queried here.

Because many fonts contain more than a single cmap for Unicode encoding, this function has some special code to select the one which covers Unicode best (‘best’ in the sense that a UCS-4 cmap is preferred to a UCS-2 cmap). It is thus preferable to FT_Set_Charmap in this case.

select_size(strike_index)

Select a bitmap strike.

Parameters:strike_index – The index of the bitmap strike in the ‘available_sizes’ field of Face object.
set_char_size(width=0, height=0, hres=72, vres=72)

This function calls FT_Request_Size to request the nominal size (in points).

Parameters:
  • width (float) – The nominal width, in 26.6 fractional points.
  • height (float) – The nominal height, in 26.6 fractional points.
  • hres (float) – The horizontal resolution in dpi.
  • vres (float) – The vertical resolution in dpi.

Note

If either the character width or height is zero, it is set equal to the other value.

If either the horizontal or vertical resolution is zero, it is set equal to the other value.

A character width or height smaller than 1pt is set to 1pt; if both resolution values are zero, they are set to 72dpi.

Don’t use this function if you are using the FreeType cache API.

set_charmap(charmap)

Select a given charmap for character code to glyph index mapping.

Parameters:charmap – A handle to the selected charmap, or an index to face->charmaps[]
set_pixel_sizes(width, height)

This function calls FT_Request_Size to request the nominal size (in pixels).

Parameters:
  • width – The nominal width, in pixels.
  • height – The nominal height, in pixels.
set_transform(matrix, delta)

A function used to set the transformation that is applied to glyph images when they are loaded into a glyph slot through FT_Load_Glyph.

Parameters:matrix – A pointer to the transformation’s 2x2 matrix. Use 0 for the identity matrix.
Parm delta:A pointer to the translation vector. Use 0 for the null vector.

Note:

The transformation is only applied to scalable image formats after the glyph has been loaded. It means that hinting is unaltered by the transformation and is performed on the character size given in the last call to FT_Set_Char_Size or FT_Set_Pixel_Sizes.

Note that this also transforms the ‘face.glyph.advance’ field, but not the values in ‘face.glyph.metrics’.

set_var_blend_coords(coords, reset=False)

Set blend coords. Using reset=True will set all axes to their default coordinates.

set_var_design_coords(coords, reset=False)

Set design coords. Using reset=True will set all axes to their default coordinates.

set_var_named_instance(instance_name)

Set instance by name. This will work with any FreeType with variable support (for our purposes: v2.8.1 or later). If the actual FT_Set_Named_Instance() function is available (v2.9.1 or later), we use it (which, despite what you might expect from its name, sets instances by index). Otherwise we just use the coords of the named instance (if found) and call self.set_var_design_coords.

sfnt_name_count

Number of name strings in the SFNT ‘name’ table.

size

The current active size for this face.

style_flags

A set of bit flags indicating the style of the face; see FT_STYLE_FLAG_XXX for the details.

style_name

The face’s style name. This is an ASCII string, usually in English, which describes the typeface’s style (like ‘Italic’, ‘Bold’, ‘Condensed’, etc). Not all font formats provide a style name, so this field is optional, and can be set to NULL. As for ‘family_name’, some formats provide localized and Unicode versions of this string. Applications should use the format specific interface to access them.

underline_position

The position, in font units, of the underline line for this face. It is the center of the underlining stem. Only relevant for scalable formats.

underline_thickness

The thickness, in font units, of the underline for this face. Only relevant for scalable formats.

units_per_EM

The number of font units per EM square for this face. This is typically 2048 for TrueType fonts, and 1000 for Type 1 fonts. Only relevant for scalable formats.