MeshBuilder

The MeshBuilder is a helper class to create Mesh entities. Stores a list of vertices, a list of edges where an edge is a list of indices into the vertices list, and a faces list where each face is a list of indices into the vertices list.

The MeshBuilder.render() method, renders the mesh into a Mesh entity. The Mesh entity supports ngons in AutoCAD, ngons are polygons with more than 4 vertices.

The basic MeshBuilder class does not support transformations.

class ezdxf.render.MeshBuilder
vertices

List of vertices as Vector or (x, y, z) tuple

edges

List of edges as 2-tuple of vertex indices, where a vertex index is the index of the vertex in the vertices list.

faces

List of faces as list of vertex indices, where a vertex index is the index of the vertex in the vertices list. A face requires at least three vertices, Mesh supports ngons, so the count of vertices is not limited.

copy()

Returns a copy of mesh.

faces_as_vertices() → Iterable[List[Vector]]

Iterate over all mesh faces as list of vertices.

edges_as_vertices() → Iterable[Tuple[Vector, Vector]]

Iterate over all mesh edges as tuple of two vertices.

add_vertices(vertices: Iterable[Vertex]) → Sequence[int]

Add new vertices to the mesh, each vertex is a (x, y, z) tuple or a Vector object, returns the indices of the vertices added to the vertices list.

e.g. adding 4 vertices to an empty mesh, returns the indices (0, 1, 2, 3), adding additional 4 vertices returns the indices (4, 5, 6, 7).

Parameters

vertices – list of vertices, vertex as (x, y, z) tuple or Vector objects

Returns

indices of the vertices added to the vertices list

Return type

tuple

add_edge(vertices: Iterable[Vertex]) → None

An edge consist of two vertices [v1, v2], each vertex is a (x, y, z) tuple or a Vector object. The new vertex indices are stored as edge in the edges list.

Parameters

vertices – list of 2 vertices : [(x1, y1, z1), (x2, y2, z2)]

add_face(vertices: Iterable[Vertex]) → None

Add a face as vertices list to the mesh. A face requires at least 3 vertices, each vertex is a (x, y, z) tuple or Vector object. The new vertex indices are stored as face in the faces list.

Parameters

vertices – list of at least 3 vertices [(x1, y1, z1), (x2, y2, z2), (x3, y3, y3), ...]

add_mesh(vertices=None, faces=None, edges=None, mesh=None) → None

Add another mesh to this mesh.

A mesh can be a MeshBuilder, MeshVertexMerger or Mesh object or requires the attributes vertices, edges and faces.

Parameters

  • vertices – list of vertices, a vertex is a (x, y, z) tuple or Vector object

  • faces – list of faces, a face is a list of vertex indices

  • edges – list of edges, an edge is a list of vertex indices

  • mesh – another mesh entity

has_none_planar_faces() → bool

Returns True if any face is none planar.

render(layout: BaseLayout, dxfattribs: dict = None, matrix: Matrix44 = None, ucs: UCS = None)

Render mesh as Mesh entity into layout.

Parameters

  • layout – BaseLayout object

  • dxfattribs – dict of DXF attributes e.g. {'layer': 'mesh', 'color': 7}

  • matrix – transformation matrix of type Matrix44

  • ucs – transform vertices by UCS to WCS

render_polyface(layout: BaseLayout, dxfattribs: dict = None, matrix: Matrix44 = None, ucs: UCS = None)

Render mesh as Polyface entity into layout.

New in version 0.11.1.

Parameters

  • layout – BaseLayout object

  • dxfattribs – dict of DXF attributes e.g. {'layer': 'mesh', 'color': 7}

  • matrix – transformation matrix of type Matrix44

  • ucs – transform vertices by UCS to WCS

render_3dfaces(layout: BaseLayout, dxfattribs: dict = None, matrix: Matrix44 = None, ucs: UCS = None)

Render mesh as Face3d entities into layout.

New in version 0.12.

Parameters

  • layout – BaseLayout object

  • dxfattribs – dict of DXF attributes e.g. {'layer': 'mesh', 'color': 7}

  • matrix – transformation matrix of type Matrix44

  • ucs – transform vertices by UCS to WCS

render_normals(layout: BaseLayout, length: float = 1, relative=True, dxfattribs: dict = None)

Render face normals as Line entities into layout, useful to check orientation of mesh faces.

Parameters

  • layout – BaseLayout object

  • length – visual length of normal, use length < 0 to point normals in opposite direction

  • relative – scale length relative to face size if True

  • dxfattribs – dict of DXF attributes e.g. {'layer': 'normals', 'color': 6}

classmethod from_mesh(other) → ezdxf.render.mesh.MeshBuilder

Create new mesh from other mesh as class method.

Parameters

other – mesh of type MeshBuilder and inherited or DXF Mesh entity or any object providing attributes vertices, edges and faces.

classmethod from_polyface(other: Union[Polymesh, Polyface]) → MeshBuilder

Create new mesh from a Polyface or Polymesh object.

New in version 0.11.1.

classmethod from_builder(other: MeshBuilder)

Create new mesh from other mesh builder, faster than from_mesh() but supports only MeshBuilder and inherited classes.

MeshTransformer

Same functionality as MeshBuilder but supports inplace transformation.

class ezdxf.render.MeshTransformer

Subclass of MeshBuilder

subdivide(level: int = 1, quads=True, edges=False) → MeshTransformer

Returns a new MeshTransformer object with subdivided faces and edges.

Parameters

  • level – subdivide levels from 1 to max of 5

  • quads – create quad faces if True else create triangles

  • edges – also subdivide edges if True

transform(matrix: Matrix44)

Transform mesh inplace by applying the transformation matrix.

Parameters

matrix – 4x4 transformation matrix as Matrix44 object

translate(x: float = 0, y: float = 0, z: float = 0)

Translate mesh inplace.

Parameters

  • x – translation in x-axis

  • y – translation in y-axis

  • z – translation in z-axis

scale(sx: float = 1, sy: float = 1, sz: float = 1)

Scale mesh inplace.

Parameters

  • sx – scale factor for x-axis

  • sy – scale factor for y-axis

  • sz – scale factor for z-axis

scale_uniform(s: float)

Scale mesh uniform inplace.

Parameters

s – scale factor for x-, y- and z-axis

rotate_x(angle: float)

Rotate mesh around x-axis about angle inplace.

Parameters

angle – rotation angle in radians

rotate_y(angle: float)

Rotate mesh around y-axis about angle inplace.

Parameters

angle – rotation angle in radians

rotate_z(angle: float)

Rotate mesh around z-axis about angle inplace.

Parameters

angle – rotation angle in radians

rotate_axis(axis: Vertex, angle: float)

Rotate mesh around an arbitrary axis located in the origin (0, 0, 0) about angle.

Parameters

  • axis – rotation axis as Vector

  • angle – rotation angle in radians

transform_to_wcs(ucs: UCS)

Transform local UCS vertices to WCS vertices.

Parameters

ucs – user coordinate system

MeshVertexMerger

Same functionality as MeshBuilder, but created meshes with unique vertices and no doublets, but MeshVertexMerger needs extra memory for bookkeeping and also does not support transformations. Location of merged vertices is the location of the first vertex with the same key.

This class is intended as intermediate object to create a compact meshes and convert them to MeshTransformer objects to apply transformations to the mesh:

mesh = MeshVertexMerger()

# create your mesh
mesh.add_face(...)

# convert mesh to MeshTransformer object
return MeshTransformer.from_builder(mesh)
class ezdxf.render.MeshVertexMerger(precision: int = 6)

Subclass of MeshBuilder

Mesh with unique vertices and no doublets, but needs extra memory for bookkeeping.

MeshVertexMerger creates a key for every vertex by rounding its components by the Python round() function and a given precision value. Each vertex with the same key gets the same vertex index, which is the index of first vertex with this key, so all vertices with the same key will be located at the location of this first vertex. If you want an average location of and for all vertices with the same key look at the MeshAverageVertexMerger class.

Parameters

precision – floating point precision for vertex rounding

MeshAverageVertexMerger

This is an extended version of MeshVertexMerger. Location of merged vertices is the average location of all vertices with the same key, this needs extra memory and runtime in comparision to MeshVertexMerger and this class also does not support transformations.

class ezdxf.render.MeshAverageVertexMerger(precision: int = 6)

Subclass of MeshBuilder

Mesh with unique vertices and no doublets, but needs extra memory for bookkeeping and runtime for calculation of average vertex location.

MeshAverageVertexMerger creates a key for every vertex by rounding its components by the Python round() function and a given precision value. Each vertex with the same key gets the same vertex index, which is the index of first vertex with this key, the difference to the MeshVertexMerger class is the calculation of the average location for all vertices with the same key, this needs extra memory to keep track of the count of vertices for each key and extra runtime for updating the vertex location each time a vertex with an existing key is added.

Parameters

precision – floating point precision for vertex rounding