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 aMonospaceFont
.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
- ttf_path – raw font file name as stored in the
-
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¶
- A Visual Guide to the Anatomy of Typography: https://visme.co/blog/type-anatomy/
- Anatomy of a Character: https://www.fonts.com/content/learning/fontology/level-1/type-anatomy/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”
- ttf_path – raw font file name as stored in the
-
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 inTextstyle
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”
- ttf_path – raw font file name as stored in the
-
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 theezdxf.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.