API reference

The public API of pyvista-cad is everything exported from the top-level pyvista_cad namespace, plus the two .cad accessor classes. Importing pyvista_cad registers the .cad accessor on pyvista.DataSet and pyvista.MultiBlock and wires the CAD readers into pyvista.read().

Readers and writers

Format readers return a pyvista.PolyData or pyvista.MultiBlock; writers take one and a path. IGES and SCAD are read-only.

read_step(path, /, *[, linear_deflection, ...])	Read a STEP file as a pyvista.MultiBlock (or merged PolyData).
write_step(dataset, path, /, *[, write_assembly])	Write a pyvista.PolyData or pyvista.MultiBlock as STEP.
read_iges(path, /, *[, bsplines, surfaces, ...])	Read an IGES file using pyiges and return a pyvista dataset.
read_brep(path, /, *[, linear_deflection, ...])	Read a BREP file as a pyvista.PolyData.
write_brep(mesh, path, /, **_)	Write a pyvista.PolyData as a faceted BREP file.
read_dxf(path, /, *[, clean, keep_text, ...])	Read a DXF file as a pyvista.PolyData.
write_dxf(mesh, path, /, *[, layer, ...])	Write a pyvista.PolyData as a DXF file using ezdxf.
read_three_mf(path, /, **_)	Read a 3MF file as a pyvista.MultiBlock.
write_three_mf(dataset, path, /, *[, units])	Write a pyvista.PolyData or pyvista.MultiBlock as 3MF.
read_ifc(path, /, *[, include, use_world_coords])	Read an IFC file as a pyvista.MultiBlock.
read_fcstd(path, /, *[, linear_deflection, ...])	Read a FreeCAD document as a pyvista.MultiBlock.
read_scad(path, /, *[, binary, args, timeout])	Compile an OpenSCAD source file and return the resulting mesh.
read_gltf(path)	Read a glTF/GLB file and enrich it with manifest metadata.
enrich_gltf(dataset, path)	Attach glTF node names / extras to a dataset's field data.

Bridges to other CAD libraries

Convert between PyVista meshes and build123d, CadQuery, gmsh, and raw OCCT TopoDS shapes.

trimesh interop is provided by pyvista core (pyvista.from_trimesh(), pyvista.to_trimesh()) and by the pyvista-trimesh package’s .trimesh accessor (install pyvista-cad[trimesh]); pyvista-cad does not duplicate it.

from_build123d(shape, /, *[, ...])	Convert a build123d Shape or Compound to PyVista.
to_build123d(mesh)	Wrap a pyvista.PolyData as a faceted build123d.Compound.
from_cadquery(workplane, /, *[, ...])	Convert a cadquery.Workplane or Compound to PyVista.
to_cadquery(mesh)	Wrap a pyvista.PolyData as a faceted cadquery.Workplane.
from_topods(shape, /, *[, ...])	Tessellate a raw OCCT TopoDS_Shape into a pyvista.PolyData.
to_topods(mesh)	Build a faceted TopoDS_Compound from a pyvista.PolyData.
from_gmsh([model_name])	Pull the current gmsh model into a pyvista.UnstructuredGrid.
to_gmsh(mesh, *[, model_name])	Install a PyVista mesh as the current gmsh model (in place).

CAD-view conversion helpers

The free functions behind the CAD-friendly render: resolve a mesh or raw shape into a {'faces', 'edges'} pyvista.MultiBlock, or plot it directly.

add_cad(plotter, obj, *[, color, edges, ...])	Add obj to plotter rendered CAD-style.
plot_cad(obj, **kwargs)	One-shot CAD-friendly plot of obj (mirrors mesh.plot()).
as_cad_multiblock(obj, *[, ...])	Resolve obj to a {'faces', 'edges'} pyvista.MultiBlock.
flatten_to_cad_polydata(mb)	Collapse a topods_to_multiblock() result to one PolyData.
get_cad_edges(poly)	Return the edges PolyData stashed on poly, if any.
topods_to_edges(shape, *[, ...])	Extract topological edges of shape as a polyline mesh.
topods_to_multiblock(shape, *[, ...])	Tessellate shape preserving per-face identity and edges.

Accessors

pyvista-cad registers a dual .cad accessor: PyVista resolves .cad to CadDataSetAccessor on a pyvista.DataSet and to CadMultiBlockAccessor on a pyvista.MultiBlock, by object type. They share the metadata, split, conversion, and plotting surface; the MultiBlock accessor adds assembly-tree traversal (walk(), find(), assembly_tree(), flatten()).

Construct PyVista meshes from external CAD objects with the module-level from_build123d(), from_cadquery(), from_topods(), and from_gmsh() functions (see Bridges to other CAD libraries above). The accessor exposes only to_* (outgoing) conversions; it is bound to an existing dataset, so it has no from_* constructors.

CadDataSetAccessor(dataset)	The .cad accessor on every PyVista pyvista.DataSet.
CadMultiBlockAccessor(dataset)	The .cad accessor on every pyvista.MultiBlock.

CadDataSetAccessor members

CadDataSetAccessor.source_format	Originating CAD format ('STEP', 'DXF', ...) or None.
CadDataSetAccessor.units	Canonical unit string or None.
CadDataSetAccessor.label	Dataset-level label, or None.
CadDataSetAccessor.color	Dataset-level RGB color, or None.
CadDataSetAccessor.metadata	Live CadMetadata view.
CadDataSetAccessor.layers	Sorted unique DXF / cell-data layer names.
CadDataSetAccessor.has_brep_origin	Whether this dataset has a recoverable B-rep origin.
CadDataSetAccessor.tessellation_quality	Tessellation deflections last used to build this mesh.
CadDataSetAccessor.set_units(target, *[, ...])	Update cad.units, optionally rescaling point coordinates.
CadDataSetAccessor.set_metadata(*[, units, ...])	Write the standard cad.* metadata into this dataset.
CadDataSetAccessor.split_by_layer([layer_array])	Split into one block per cad.layer cell value.
CadDataSetAccessor.split_by_label([label_array])	Split a composite mesh by the values of a per-cell label array.
CadDataSetAccessor.split_by_color([color_array])	Split into one block per per-cell RGB color.
CadDataSetAccessor.exact_volume()	Return the exact volume from the cached TopoDS_Shape.
CadDataSetAccessor.center_of_mass()	Return the exact centre of mass from the cached TopoDS_Shape.
CadDataSetAccessor.to_build123d()	Wrap the dataset as a faceted build123d.Compound.
CadDataSetAccessor.to_cadquery()	Wrap the dataset as a faceted cadquery.Workplane.
CadDataSetAccessor.to_topods()	Build a faceted TopoDS shape from the dataset.
CadDataSetAccessor.to_gmsh(*[, model_name])	Install the dataset as the current gmsh model.
CadDataSetAccessor.to_dxf(path, /, *[, ...])	Write this dataset as a DXF file.
CadDataSetAccessor.to_3mf(path, /, *[, units])	Write to path as a 3MF file.
CadDataSetAccessor.to_brep(path, /)	Write to path as a faceted BREP file.
CadDataSetAccessor.to_step(path, /)	Write to path as a faceted STEP file.
CadDataSetAccessor.to_gltf(path, /)	Write to path as a glTF (.gltf / .glb) file.
CadDataSetAccessor.tessellate(*[, ...])	Re-tessellate this mesh from its cached originating B-rep.
CadDataSetAccessor.plot(**kwargs)	CAD-friendly plot: shaded faces + topological edges.
CadDataSetAccessor.cad_view(**kwargs)	Resolve to a {'faces', 'edges'} CAD-view MultiBlock.

CadMultiBlockAccessor members

CadMultiBlockAccessor.set_units(target, *[, ...])	Update cad.units on every block, optionally rescaling points.
CadMultiBlockAccessor.set_metadata(*[, ...])	Write the standard cad.* metadata onto this MultiBlock.
CadMultiBlockAccessor.walk()	Walk the MultiBlock tree depth-first.
CadMultiBlockAccessor.find([predicate, ...])	Filter the MultiBlock tree.
CadMultiBlockAccessor.flatten()	Collapse a nested MultiBlock into a flat MultiBlock of leaves.
CadMultiBlockAccessor.flatten_to_polydata()	Fuse the entire MultiBlock into one pyvista.PolyData.
CadMultiBlockAccessor.assembly_tree()	Return a pure-data view of the MultiBlock hierarchy.
CadMultiBlockAccessor.split_by_layer([...])	Combine and split into one block per layer.
CadMultiBlockAccessor.split_by_label([...])	Combine the assembly, then split by per-cell label value.
CadMultiBlockAccessor.split_by_color([...])	Combine and split into one block per per-cell color.
CadMultiBlockAccessor.exact_volume()	Sum exact volume across all BREP-cached leaves.
CadMultiBlockAccessor.to_build123d()	Wrap as a faceted build123d.Compound.
CadMultiBlockAccessor.to_cadquery()	Wrap as a faceted cadquery.Workplane.
CadMultiBlockAccessor.to_topods()	Build a faceted TopoDS shape from the combined assembly.
CadMultiBlockAccessor.to_gmsh(*[, model_name])	Install this MultiBlock as the current gmsh model.
CadMultiBlockAccessor.to_dxf(path, /, *[, ...])	Write this MultiBlock as a DXF file.
CadMultiBlockAccessor.to_3mf(path, /, *[, units])	Write to path as a 3MF file.
CadMultiBlockAccessor.to_brep(path, /)	Write to path as a faceted BREP file.
CadMultiBlockAccessor.to_step(path, /)	Write to path as a faceted STEP file.
CadMultiBlockAccessor.to_gltf(path, /)	Write to path as a glTF / GLB file.
CadMultiBlockAccessor.tessellate(*[, ...])	Re-tessellate the combined assembly from its cached B-rep.
CadMultiBlockAccessor.plot(**kwargs)	CAD-friendly plot: shaded faces + topological edges.
CadMultiBlockAccessor.cad_view(**kwargs)	Resolve to a {'faces', 'edges'} CAD-view MultiBlock.

Metadata

CadMetadata([source_format, ...])	Bag of CAD-flavored metadata derived from a PyVista dataset.
Units

Exceptions and warnings

CadError	Base class for all pyvista-cad errors.
CadReadError	Raised when a CAD file cannot be read.
CadWriteError	Raised when a CAD file cannot be written.
CadCacheError	Raised when a cached originating TopoDS_Shape is corrupt.
MetadataError	Raised when a cad.* metadata value fails validation.
OptionalDependencyError	Raised when an optional backend is needed but not installed.
TessellationError	Raised when OCCT tessellation fails for a given shape.
UnsupportedFormatError	Raised when a requested format is not supported.
CadWarning	Category for pyvista-cad data or feature-loss warnings.

Example data

Bundled fixture files and downloadable example datasets.

bracket_step_path()	Return the path to the bundled L-bracket STEP fixture.
drawing_dxf_path()	Return the path to the bundled 2D mechanical drawing DXF fixture.
assembly_3mf_path()	Return the path to the bundled two-part 3MF assembly fixture.
small_building_ifc_path()	Return the path to the bundled small building IFC fixture.

step_part_path()	Return the NIST AM Bench 2022 LPBF bridge specimen (STEP).
step_recoater_path()	Return the small NIST AM Bench recoater-guide fixture (STEP).
step_assembly_path()	Return the NIST AM Bench build-plate layout assembly (STEP).
iges_impeller_path()	Return a centrifugal impeller exported from SolidWorks (IGES).
ifc_building_path()	Return a single-family-house BIM model from buildingSMART (IFC4).
three_mf_colored_path()	Return the 3MF Consortium colored dodecahedron chain (3MF).
gltf_toycar_path()	Return the Khronos ToyCar reference asset (binary glTF).
dxf_drawing_path()	Return a multi-layer 2D DXF drawing (layers 0/BLUE/RED).
scad_threads_path()	Return a parametric ISO metric fastener library (OpenSCAD).
fcstd_nut_path()	Return an M3 nyloc lock nut from the FreeCAD parts library (FCStd).
scan_pair_paths()	Return as-designed CAD and as-scanned PLY of one T-LESS part.