Disassemble

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.

Warning

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 the font support from the optional Matplotlib package.

Install Matplotlib from command line:

C:\> 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.

Using the Matplotlib font support adds runtime overhead, therefore it is possible to deactivate the Matplotlib font support by setting the global option:

options.use_matplotlib_font_support = False

Flatten Complex DXF Entities

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

Recursive decomposition of the given DXF entity collection into a flat stream of DXF entities. 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:

  • INSERT

  • DIMENSION

  • LEADER

  • MLEADER

  • MLINE

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

This function does not apply the clipping path created by the XCLIP command. The function returns all entities and ignores the clipping path polygon and no entity is clipped.

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.

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

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

Parameters:

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

entity

Reference to the source DXF entity of this primitive.

max_flattening_distance

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 | None

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

if primitive.path is not None:
    process(primitive.path)
property mesh: MeshBuilder | None

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

if primitive.mesh is not None:
    process(primitive.mesh)
property is_empty: bool

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.

bbox(fast=False) → BoundingBox

Returns the BoundingBox of the path/mesh representation. Returns the precise bounding box for the path representation if fast is False, otherwise the bounding box for Bézier curves is based on their control points.