pyvista-cad

CAD format reading, writing, and CAD-style plotting for PyVista.

pyvista-cad adds CAD-format support to PyVista: STEP, IGES, BREP, DXF, 3MF, IFC, FreeCAD .fcstd, OpenSCAD .scad, and glTF. It registers a .cad accessor on every pv.DataSet / pv.MultiBlock and wires reader entries into pv.read(...). It also adds CAD-style rendering: smoothly shaded faces with the model's topological B-rep edges instead of triangle-mesh noise, via .cad.plot() and a plotter.cad component. No monkey-patching, no forks, no direct VTK calls.

Install matrix

[full] is kept as an alias of [all], so existing installs and pinned requirement files keep resolving.

Python support: 3.10 – 3.14.

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

FEA meshing via gmsh is intentionally out of scope. gmsh is GPLv2+ and would virally license any closed-source product that linked it, so pyvista-cad's dependency set stays fully permissive (MIT / BSD / Apache, plus LGPL-with-exception for the OpenCascade and IFC backends). For CAD-to-tet workflows, drive gmsh directly and read the resulting .msh file back with pv.read (PyVista routes .msh through meshio); the scikit-gmsh package wraps the live-model API if you prefer that.

pip install pyvista-cad           # DXF and glTF only
pip install pyvista-cad[step]     # add STEP, BREP, FCStd
pip install pyvista-cad[all]      # everything

Quick start

import pyvista as pv
import pyvista_cad  # registers the .cad accessor and reader entries

mesh = pv.read('part.step')  # MultiBlock of parts with cad.color, cad.label
mesh.plot(show_edges=True)

floorplan = pv.read('floor.dxf')  # PolyData with Layer cell data
layers = floorplan.cad.split_by_layer()  # MultiBlock keyed on layer

CAD-friendly plotting

A generic mesh viewer draws the triangulation. With show_edges=True you see every facet edge, an artifact of the tessellation tolerance. A CAD application instead shows smoothly shaded faces with the model's topological edges (the B-rep feature curves) on top. pyvista-cad reproduces that: analytic surface normals so a coarse mesh still shades round, topological edges recovered from the cached B-rep, triangle edges hidden.

import pyvista as pv
import pyvista_cad
from pyvista_cad.examples import downloads

mb = pyvista_cad.read_step(downloads.step_part_path())  # NIST AM Bench specimen

mb.cad.plot()  # shaded faces + topological edges

# Or compose it into a scene, color faces by a scalar, keep the edges:
part = mb[0]  # a cached block keeps its B-rep
part['height'] = part.points[:, 2]
pl = pv.Plotter()
pl.cad.add(part, scalars='height', cmap='viridis')
pl.show()

.cad.plot() and the plotter.cad component accept a MultiBlock, PolyData, raw TopoDS, or a build123d / cadquery object; a plain mesh with no B-rep origin degrades to crease feature edges.

Real-world workflow

Load a STEP assembly, locate a part, drive it through gmsh to a tetrahedral FEA mesh, then clip to expose the interior. pv.read handles the resulting .msh file natively via meshio, so no extra PyVista dependency is needed.

import gmsh
import pyvista as pv
import pyvista_cad
from pyvista_cad.examples import downloads

assembly = pv.read(downloads.step_assembly_path())  # 3-part NIST build assembly
print(assembly.cad.assembly_tree())  # nested dict of block names
matches = assembly.cad.find('*PartCAD')  # glob -> list of (path, block)
path, part = matches[0]

gmsh.initialize()
try:
    gmsh.model.occ.importShapes(downloads.step_part_path())
    gmsh.model.occ.synchronize()
    gmsh.option.setNumber('Mesh.MeshSizeMax', 2.0)
    gmsh.model.mesh.generate(3)
    gmsh.write('part.msh')
finally:
    gmsh.finalize()

grid = pv.read('part.msh')  # via meshio
grid = grid.extract_cells(grid.celltypes == 10)  # keep VTK_TETRA
clip = grid.clip(normal='x', crinkle=True)
clip.save('part_tets.vtu')  # full tet mesh round-trips

The Quick start uses bundled offline fixtures (bracket_step_path(), a parametric L-bracket committed as STEP; drawing_dxf_path(), a layered 2D drawing). The other examples pull real, openly licensed parts from pyvista_cad.examples.downloads (cached on first fetch) — the NIST AM Bench LPBF specimen and its 3-part build assembly.

Common tasks

Licensing

pyvista-cad is MIT. Every runtime dependency is either permissive (MIT / BSD / Apache) or LGPL with the OpenCascade exception. No GPL code is pulled in by any extra, which makes the package safe to use in closed-source / proprietary products subject to the standard LGPL dynamic-link obligations. See LICENSES.md for the full dependency-by-dependency breakdown, the LGPL compliance notes, and the rationale for not depending on gmsh.

IGES backends

read_iges has two readers behind it.

import pyvista_cad

mesh = pyvista_cad.read_iges('scan.igs', backend='ocp', linear_deflection=0.1)
mesh.cad.plot()

The default is unchanged, so pv.read('part.igs') still goes through pyiges. pv.read accepts no reader keywords, so selecting the OCCT backend means calling read_iges directly.

Speed

pyiges parses and evaluates surfaces in Python; OCCT does both in C++. Best of three warm runs on pyvista_cad.examples.downloads.iges_impeller_path() (4.0 MB, 4615 entities, a SolidWorks export):

The two defaults are not the same mesh density, so the 36x at defaults is partly a coarser mesh. Matched at roughly equal cell count the gap is about 5x, and it grows with file size because the Python-side cost scales with entity count. Numbers are from one machine; treat the ratios as the signal, not the absolute times.

Trimmed surfaces

pyiges dispatches IGES type 128 (rational B-spline surface) and has no handler for type 144 (trimmed parametric surface), so it tessellates the full underlying surface and ignores the trimming curves. OCCT applies them. On the impeller above that shows up in the extent:

Files whose trimming curves follow the natural surface boundary read the same either way, which is why the small tests/data/impeller.iges fixture agrees between backends.

Reach for 'ocp' on anything from a scanner or a CMM. Use 'pyiges' when you need the per-entity level numbers.

Fidelity and limitations

Round-trip fidelity varies by format. Tessellated formats (STEP, IGES, BREP, FCStd) discretize analytic surfaces on read; the originating B-rep is cached so tessellate() can refine it. DXF and 3MF round-trip geometry and metadata within documented tolerances. IGES and SCAD are read-only.