New in version 0.16.

This module provide tools for the recursive decomposition of nested block reference structures into a flat stream of DXF entities and converting DXF entities into geometric primitives of Path and MeshBuilder objects encapsulated into intermediate Primitive classes.

Changed in version 0.17: The Hatch entity is no special case anymore and has regular support by the make_primitive() function.


Do not expect advanced vectorization capabilities: Text entities like TEXT, ATTRIB, ATTDEF and MTEXT get only a rough border box representation. The text2path add-on can convert text into paths. VIEWPORT, IMAGE and WIPEOUT are represented by their clipping path. Unsupported entities: all ACIS based entities, XREF, UNDERLAY, ACAD_TABLE, RAY, XLINE. Unsupported entities will be ignored.

Text Boundary Calculation

Text boundary calculations are based on monospaced (fixed-pitch, fixed-width, non-proportional) font metrics, which do not provide a good accuracy for text height calculation and much less accuracy for text width calculation.

It is possible to improve this results by using font support from the Matplotlib package, but this is an optional feature and has to be activated explicit:

from  ezdxf import options

options.use_matplotlib_font_support = True

This is a global option for the current running Interpreter and it is active until deactivated:

options.use_matplotlib_font_support = False


This feature requires a working Matplotlib installation else an ImportError exception will be raised sooner or later. This feature also depends on the drawing add-on, which is installed by default. Using the Matplotlib font support adds runtime overhead at the first usage of any of the text related primitives.

See also

Global option to set the font caching directory: ezdxf.options.font_cache_directory

Install Matplotlib from command line:

pip3 install matplotlib

The Matplotlib font support will improve the results for TEXT, ATTRIB and ATTDEF. The MTEXT entity has many advanced features which would require a full “Rich Text Format” rendering and that is far beyond the goals and capabilities of this library, therefore the boundary box for MTEXT will never be as accurate as in a dedicated CAD application.

Flatten Complex DXF Entities

ezdxf.disassemble.recursive_decompose(entities: Iterable[DXFEntity]) → Iterable[DXFEntity]

Recursive decomposition of the given DXF entity collection into a flat DXF entity stream. All block references (INSERT) and entities which provide a virtual_entities() method will be disassembled into simple DXF sub-entities, therefore the returned entity stream does not contain any INSERT entity.

Point entities will not be disassembled into DXF sub-entities, as defined by the current point style $PDMODE.

These entity types include sub-entities and will be decomposed into simple DXF entities:






Decomposition of XREF, UNDERLAY and ACAD_TABLE entities is not supported.

Entity Deconstruction

These functions disassemble DXF entities into simple geometric objects like meshes, paths or vertices. The Primitive is a simplified intermediate class to use a common interface on various DXF entities.

ezdxf.disassemble.make_primitive(entity: DXFEntity, max_flattening_distance=None)Primitive

Factory to create path/mesh primitives. The max_flattening_distance defines the max distance between the approximation line and the original curve. Use max_flattening_distance to override the default value.

Returns an empty primitive for unsupported entities. The empty state of a primitive can be checked by the property is_empty. The path and the mesh attributes of an empty primitive are None and the vertices() method yields no vertices.

Changed in version 0.17: regular support for the Hatch entity.

ezdxf.disassemble.to_primitives(entities: Iterable[DXFEntity], max_flattening_distance: float = None) → Iterable[Primitive]

Yields all DXF entities as path or mesh primitives. Yields unsupported entities as empty primitives, see make_primitive().

  • entities – iterable of DXF entities

  • max_flattening_distance – override the default value

ezdxf.disassemble.to_meshes(primitives: Iterable[Primitive]) → Iterable[MeshBuilder]

Yields all MeshBuilder objects from the given primitives. Ignores primitives without a defined mesh.

ezdxf.disassemble.to_paths(primitives: Iterable[Primitive]) → Iterable[Path]

Yields all Path objects from the given primitives. Ignores primitives without a defined path.

ezdxf.disassemble.to_vertices(primitives: Iterable[Primitive]) → Iterable[Vec3]

Yields all vertices from the given primitives. Paths will be flattened to create the associated vertices. See also to_control_vertices() to collect only the control vertices from the paths without flattening.

ezdxf.disassemble.to_control_vertices(primitives: Iterable[Primitive]) → Iterable[Vec3]

Yields all path control vertices and all mesh vertices from the given primitives. Like to_vertices(), but without flattening.

class ezdxf.disassemble.Primitive

Interface class for path/mesh primitives.


Reference to the source DXF entity of this primitive.


The max_flattening_distance attribute defines the max distance in drawing units between the approximation line and the original curve. Set the value by direct attribute access. (float) default = 0.01

property path

Path representation or None, idiom to check if is a path representation (could be empty):

if primitive.path is not None:
property mesh

MeshBuilder representation or None, idiom to check if is a mesh representation (could be empty):

if primitive.mesh is not None:
property is_empty

Returns True if represents an empty primitive which do not yield any vertices.

abstract vertices() → Iterable[Vec3]

Yields all vertices of the path/mesh representation as Vec3 objects.