MeshExchange

The ezdxf.addons.meshex module provides functions to exchange meshes with other tools in the following file formats:

  • STL: import/export, supports only triangles as faces

  • OFF: import/export, supports ngons as faces and is more compact than STL

  • OBJ: import/export, supports ngons as faces and can contain multiple meshes in one file

  • PLY: export only, supports ngons as faces

  • OpenSCAD: export as polyhedron, supports ngons as faces

  • IFC4: export only, supports ngons as faces

The source or target object is always a MeshBuilder instance and therefore the supported features are also limited by this class. Only vertices and faces are exchanged, colors, textures and explicit face- and vertex normals are lost.

Note

This add-on is not a replacement for a proper file format interface for this data formats! It’s just a simple way to exchange meshes with other tools like OpenSCAD or MeshLab.

Warning

The meshes created by the ezdxf.addons.pycsg add-on are usually not suitable for export because they often violate the vertex-to-vertex rule: A vertex of a face cannot lie on the edge of another face. This was one of the reasons to create this addon to get an interface to OpenSCAD.

Example for a simple STL to DXF converter:

import sys
import ezdxf
from ezdxf.addons import meshex

try:
    mesh = meshex.stl_readfile("your.stl")
except (meshex.ParsingError, IOError) as e:
    print(str(e))
    sys.exit(1)

doc = ezdxf.new()
mesh.render_mesh(doc.modelspace())
doc.saveas("your.dxf")

See also

Example script meshex_export.py at github.

Import

ezdxf.addons.meshex.stl_readfile(filename: str | PathLike) → MeshTransformer

Read ascii or binary STL file content as ezdxf.render.MeshTransformer instance.

Raises:

ParsingError – vertex parsing error or invalid/corrupt data

ezdxf.addons.meshex.stl_loads(content: str) → MeshTransformer

Load a mesh from an ascii STL content string as ezdxf.render.MeshTransformer instance.

Raises:

ParsingError – vertex parsing error

ezdxf.addons.meshex.stl_loadb(buffer: bytes) → MeshTransformer

Load a mesh from a binary STL data ezdxf.render.MeshTransformer instance.

Raises:

ParsingError – invalid/corrupt data or not a binary STL file

ezdxf.addons.meshex.off_readfile(filename: str | PathLike) → MeshTransformer

Read OFF file content as ezdxf.render.MeshTransformer instance.

Raises:

ParsingError – vertex or face parsing error

ezdxf.addons.meshex.off_loads(content: str) → MeshTransformer

Load a mesh from a OFF content string as ezdxf.render.MeshTransformer instance.

Raises:

ParsingError – vertex or face parsing error

ezdxf.addons.meshex.obj_readfile(filename: str | PathLike) → list[MeshTransformer]

Read OBJ file content as list of ezdxf.render.MeshTransformer instances.

Raises:

ParsingError – vertex or face parsing error

ezdxf.addons.meshex.obj_loads(content: str) → list[MeshTransformer]

Load one or more meshes from an OBJ content string as list of ezdxf.render.MeshTransformer instances.

Raises:

ParsingError – vertex parsing error

Export

ezdxf.addons.meshex.stl_dumps(mesh: MeshBuilder) → str

Returns the STL data as string for the given mesh. This function triangulates the meshes automatically because the STL format supports only triangles as faces.

This function does not check if the mesh obey the STL format rules:

  • The direction of the face normal is outward.

  • The face vertices are listed in counter-clockwise order when looking at the object from the outside (right-hand rule).

  • Each triangle must share two vertices with each of its adjacent triangles.

  • The object represented must be located in the all-positive octant (non-negative and nonzero).

ezdxf.addons.meshex.stl_dumpb(mesh: MeshBuilder) → bytes

Returns the STL binary data as bytes for the given mesh.

For more information see function: stl_dumps()

ezdxf.addons.meshex.off_dumps(mesh: MeshBuilder) → str

Returns the OFF data as string for the given mesh. The OFF format supports ngons as faces.

ezdxf.addons.meshex.obj_dumps(mesh: MeshBuilder) → str

Returns the OBJ data as string for the given mesh. The OBJ format supports ngons as faces.

ezdxf.addons.meshex.ply_dumpb(mesh: MeshBuilder) → bytes

Returns the PLY binary data as bytes for the given mesh. The PLY format supports ngons as faces.

ezdxf.addons.meshex.scad_dumps(mesh: MeshBuilder) → str

Returns the OpenSCAD polyhedron definition as string for the given mesh. OpenSCAD supports ngons as faces.

Important

OpenSCAD requires the face normals pointing inwards, the method flip_normals() of the MeshBuilder class can flip the normals inplace.

ezdxf.addons.meshex.ifc4_dumps(mesh: MeshBuilder, entity_type=IfcEntityType.POLYGON_FACE_SET, *, layer: str = 'MeshExport', color: tuple[float, float, float] = (1.0, 1.0, 1.0)) → str

Returns the IFC4 string for the given mesh. The caller is responsible for checking if the mesh is a closed or open surface (e.g. mesh.diagnose().euler_characteristic == 2) and using the appropriate entity type.

Parameters:

  • mesh – MeshBuilder

  • entity_type – IfcEntityType

  • layer – layer name as string

  • color – entity color as RGB tuple, values in the range [0,1]

Warning

IFC4 is a very complex data format and this is a minimal effort exporter, so the exported data may not be importable by all CAD applications.

The exported IFC4 data can be imported by the following applications:

  • BricsCAD

  • FreeCAD (IfcOpenShell)

  • Allplan

  • Tekla BIMsight

ezdxf.addons.meshex.export_ifcZIP(filename: str | PathLike, mesh: MeshBuilder, entity_type=IfcEntityType.POLYGON_FACE_SET, *, layer: str = 'MeshExport', color: tuple[float, float, float] = (1.0, 1.0, 1.0))

Export the given mesh as zip-compressed IFC4 file. The filename suffix should be .ifcZIP. For more information see function ifc4_dumps().

Parameters:

  • filename – zip filename, the data file has the same name with suffix .ifc

  • mesh – MeshBuilder

  • entity_type – IfcEntityType

  • layer – layer name as string

  • color – entity color as RGB tuple, values in the range [0,1]

Raises:

IOError – IO error when opening the zip-file for writing

class ezdxf.addons.meshex.IfcEntityType(value, names=_not_given, *values, module=None, qualname=None, type=None, start=1, boundary=None)
POLYGON_FACE_SET

“SurfaceModel” representation usable for open or closed surfaces.

CLOSED_SHELL

“Brep” representation usable for closed surfaces.

OPEN_SHELL

“SurfaceModel” representation usable for open surfaces.