Fonts

The module ezdxf.tools.fonts manages the internal usage of fonts and has no relation how the DXF formats manages text styles.

See also

The Textstyle entity, the DXF way to define fonts.

The tools in this module provide abstractions to get font measurements with and without the optional Matplotlib package.

For a proper text rendering the font measurements are required. Ezdxf has a lean approach to package dependencies, therefore the rendering results without support from the optional Matplotlib package are not very good.

Hint

If Matplotlib does not find an installed font and rebuilding the matplotlib font cache does not help, deleting the cache file ~/.matplotlib/fontlist-v330.json may help.

Font Classes

ezdxf.tools.fonts.make_font(ttf_path: str, cap_height: float, width_factor: float = 1.0) → ezdxf.tools.fonts.AbstractFont

Factory function to create a font abstraction.

Creates a MatplotlibFont if the Matplotlib font support is available and enabled or else a MonospaceFont.

Parameters:
  • ttf_path – raw font file name as stored in the Textstyle entity
  • cap_height – desired cap height in drawing units.
  • width_factor – horizontal text stretch factor
class ezdxf.tools.fonts.AbstractFont(measurements: ezdxf.tools.fonts.FontMeasurements)

The ezdxf font abstraction.

measurement

The FontMeasurements data.

text_width(text: str) → float
space_width() → float
class ezdxf.tools.fonts.MonospaceFont(cap_height: float, width_factor: float = 1.0, baseline: float = 0, descender_factor: float = 0.333, x_height_factor: float = 0.666)

Defines a monospaced font without knowing the real font properties. Each letter has the same cap- and descender height and the same width. This font abstraction is used if no Matplotlib font support is available.

Use the make_font() factory function to create a font abstraction.

text_width(text: str) → float

Returns the text width in drawing units for the given text based on a simple monospaced font calculation.

space_width() → float

Returns the width of a “space” char.

class ezdxf.tools.fonts.MatplotlibFont(ttf_path: str, cap_height: float = 1.0, width_factor: float = 1.0)

This class provides proper font measurement support by using the optional Matplotlib font support.

Use the make_font() factory function to create a font abstraction.

text_width(text: str) → float

Returns the text width in drawing units for the given text string. Text rendering and width calculation is done by the Matplotlib TextPath class.

space_width() → float

Returns the width of a “space” char.

Font Anatomy

Font Properties

The default way of DXF to store fonts in the Textstyle entity by using the raw TTF file name is not the way how most render backends select fonts.

The render backends and web technologies select the fonts by their properties. This list shows the Matplotlib properties:

family
List of font names in decreasing order of priority. The items may include a generic font family name, either “serif”, “sans-serif”, “cursive”, “fantasy”, or “monospace”.
style
“normal” (“regular”), “italic” or “oblique”
stretch
A numeric value in the range 0-1000 or one of “ultra-condensed”, “extra-condensed”, “condensed”, “semi-condensed”, “normal”, “semi-expanded”, “expanded”, “extra-expanded” or “ultra-expanded”
weight
A numeric value in the range 0-1000 or one of “ultralight”, “light”, “normal”, “regular”, “book”, “medium”, “roman”, “semibold”, “demibold”, “demi”, “bold”, “heavy”, “extra bold”, “black”.

This way the backend can choose a similar font if the original font is not available.

See also

class ezdxf.tools.fonts.FontFace(ttf, family, style, stretch, weight)

This is the equivalent to the Matplotlib FontProperties class.

ttf

Raw font file name as string, e.g. “arial.ttf”

family

Family name as string, the default value is “sans-serif”

style

Font style as string, the default value is “normal”

stretch

Font stretch as string, the default value is “normal”

weight

Font weight as string, the default value is “normal”

class ezdxf.tools.fonts.FontMeasurements

See Font Anatomy for more information.

baseline
cap_height
x_height
descender_height
scale(factor: float = 1.0) → ezdxf.tools.fonts.FontMeasurements
scale_from_baseline(desired_cap_height: float) → ezdxf.tools.fonts.FontMeasurements
shift(distance: float = 0.0) → ezdxf.tools.fonts.FontMeasurements

Font Caching

Ezdxf uses Matplotlib to manage fonts and caches the collected information. The default installation of ezdxf provides a basic set of font properties. It is possible to create your own font cache specific for your system: see ezdxf.options.font_cache_directory

The font cache is loaded automatically at startup, if not disabled by setting config variable auto_load_fonts in [core] section to False : see Environment Variables

ezdxf.tools.fonts.get_font_face(ttf_path: str, map_shx=True) → ezdxf.tools.fonts.FontFace

Get cached font face definition by TTF file name e.g. “Arial.ttf”.

This function translates a DXF font definition by the raw TTF font file name into a FontFace object. Fonts which are not available on the current system gets a default font face.

Parameters:
  • ttf_path – raw font file name as stored in the Textstyle entity
  • map_shx – maps SHX font names to TTF replacement fonts, e.g. “TXT” -> “txt_____.ttf”
ezdxf.tools.fonts.get_entity_font_face(entity: DXFEntity, doc: Optional[Drawing] = None) → FontFace

Returns the FontFace defined by the associated text style. Returns the default font face if the entity does not have or support the DXF attribute “style”. Supports the extended font information stored in Textstyle table entries.

Pass a DXF document as argument doc to resolve text styles for virtual entities which are not assigned to a DXF document. The argument doc always overrides the DXF document to which the entity is assigned to.

ezdxf.tools.fonts.get_font_measurements(ttf_path: str, map_shx=True) → ezdxf.tools.fonts.FontMeasurements

Get cached font measurements by TTF file name e.g. “Arial.ttf”.

Parameters:
  • ttf_path – raw font file name as stored in the Textstyle entity
  • map_shx – maps SHX font names to TTF replacement fonts, e.g. “TXT” -> “txt_____.ttf”
ezdxf.tools.fonts.build_system_font_cache(*, path=None, rebuild=True) → None

Build system font cache and save it to directory path if given. Set rebuild to False to just add new fonts. Requires the Matplotlib package!

A rebuild has to be done only after a new ezdxf installation, or new fonts were added to your system (which you want to use), or an update of ezdxf if you don’t use your own external font cache directory.

See also: ezdxf.options.font_cache_directory

ezdxf.tools.fonts.load(path=None, reload=False)

Load all caches from given path or from default location, defined by ezdxf.options.font_cache_directory or the default cache from the ezdxf.tools folder.

This function is called automatically at startup if not disabled by environment variable EZDXF_AUTO_LOAD_FONTS.

ezdxf.tools.fonts.save(path=None)

Save all caches to given path or to default location, defined by options.font_cache_directory or into the ezdxf.tools folder.