pyvista-cad 0.0.1__tar.gz

pyvista_cad-0.0.1/.gitattributes

@@ -0,0 +1,19 @@
+# CAD / mesh fixtures are opaque payloads. Treat them as binary so git
+# never does EOL conversion, diff, or merge text munging on them.
+*.step binary
+*.stp binary
+*.dxf binary
+*.brep binary
+*.iges binary
+*.igs binary
+*.3mf binary
+*.ifc binary
+*.scad binary
+*.glb binary
+*.gltf binary
+*.stl binary
+*.obj binary
+*.ply binary
+*.vtk binary
+*.vtu binary
+*.vtp binary

pyvista_cad-0.0.1/.github/FUNDING.yml

@@ -0,0 +1 @@
+github: [banesullivan]

pyvista_cad-0.0.1/.github/dependabot.yml

@@ -0,0 +1,11 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

pyvista_cad-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,171 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v6
+      - run: uv sync --extra dev
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run mypy src/pyvista_cad
+
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-14, windows-latest]
+        # 3.14 is intentionally absent: every test extra transitively
+        # pulls `cadquery` (dev -> docs -> full -> cadquery), and
+        # `cadquery-ocp` ships no cp314 wheel for any platform/version,
+        # so the env is uninstallable on 3.14. Re-add once cadquery-ocp
+        # publishes cp314 wheels. requires-python stays `>=3.10`.
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+        # `dev,full` carries `step-light` (cascadio) so the cascadio STEP
+        # backend E2E runs in CI; `openscad` is installed via apt on Linux
+        # so the SCAD reader E2E runs there too. One combination gaining
+        # these is enough — the matrix shape is unchanged.
+        extras: ["dev", "dev,step", "dev,full,step-light"]
+        exclude:
+          - os: windows-latest
+            extras: "dev,full,step-light"
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Set up headless display
+        uses: pyvista/setup-headless-display-action@v4
+      - name: Install system packages for OCCT / gmsh backends
+        if: runner.os == 'Linux'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y \
+            libgl1-mesa-dev libglu1 libxft2 libxcursor-dev libxinerama1 \
+            libocct-data-exchange-dev libocct-foundation-dev xvfb openscad
+      - name: Install dependencies
+        run: uv sync --extra ${{ matrix.extras }}
+      - name: Run tests
+        run: uv run pytest tests/ --cov --cov-report=xml -v
+      - name: Upload coverage
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.13' && matrix.extras == 'dev,full,step-light'
+        uses: codecov/codecov-action@v5
+        with:
+          files: coverage.xml
+          fail_ci_if_error: false
+      - name: Upload image-cache failures
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: image-cache-failures-${{ matrix.os }}-py${{ matrix.python-version }}-${{ matrix.extras }}
+          path: tests/image_cache_failures/
+          if-no-files-found: ignore
+
+  lazy-imports:
+    # Mission goal #4: `import pyvista_cad` must not import build123d,
+    # cascadio, OCP, lib3mf, ifcopenshell, gmsh, FreeCAD, pyiges, geomdl.
+    # This job installs ONLY the core package (DXF-only via ezdxf) so a
+    # leaked import would actually be detectable (modules aren't on the
+    # path, ImportError would surface). The matrix-`test` job above runs
+    # with `[full]` and so cannot enforce this invariant.
+    name: Lazy-imports guardrail (minimal extras)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.13"
+      - name: Install minimal (core + pytest only, no optional backends)
+        # pytest-pyvista is a test plugin (not a CAD backend); it owns
+        # the `image_cache_dir` pytest ini option, so omitting it makes
+        # pytest fail at config time with strict-warnings enabled.
+        run: |
+          uv venv
+          uv pip install -e . pytest pytest-pyvista
+      - name: Run lazy-imports guardrail
+        run: uv run pytest tests/test_lazy_imports.py -v
+
+  benchmark:
+    # Ubuntu-only because cross-platform timing is noisy. The first
+    # green run on `main` establishes the baseline; the 5% regression
+    # gate lands in a follow-up once `bench.json` has been compared
+    # across at least two runs.
+    name: Benchmark (perf regression gate)
+    runs-on: ubuntu-latest
+    # Informational until the cross-run 5% regression gate lands: absolute
+    # wall-clock budgets are too noisy on shared runners to block CI.
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.13"
+      - uses: pyvista/setup-headless-display-action@v4
+      - name: Install [dev,full] for end-to-end perf cases
+        run: uv sync --extra dev --extra full
+      - name: Run benchmarks
+        # Absolute wall-clock budgets flake on shared runners; soft mode
+        # records breaches without failing the job. bench.json is still
+        # emitted for the planned cross-run regression gate.
+        env:
+          PYVISTA_CAD_PERF_SOFT: "1"
+        run: |
+          uv run pytest tests/perf/ \
+            --benchmark-only \
+            --benchmark-json=bench.json \
+            -v
+      - name: Upload benchmark JSON
+        uses: actions/upload-artifact@v4
+        with:
+          name: bench-json
+          path: bench.json
+          if-no-files-found: error
+
+  build:
+    runs-on: ubuntu-latest
+    needs: [lint, test]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v6
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    runs-on: ubuntu-latest
+    needs: [build]
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+    environment: release
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

pyvista_cad-0.0.1/.github/workflows/docs.yml

@@ -0,0 +1,87 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  build:
+    name: Build Sphinx docs + gallery
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.13"
+
+      - name: Set up headless display
+        uses: pyvista/setup-headless-display-action@v4
+
+      - name: Install system packages for OCCT-backed examples
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y \
+            libgl1-mesa-dev libglu1 libxft2 libxcursor-dev libxinerama1 \
+            libocct-data-exchange-dev libocct-foundation-dev xvfb pandoc openscad
+
+      - name: Install with [docs]
+        run: uv sync --extra docs
+
+      - name: Build documentation
+        run: uv run make -C doc html
+
+      - name: Prevent Jekyll processing on GH Pages
+        run: touch doc/_build/html/.nojekyll
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: doc/_build/html/
+
+  deploy:
+    name: Deploy to GitHub Pages
+    needs: build
+    if: github.event_name == 'push' && (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/v'))
+    runs-on: ubuntu-24.04
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+
+  doctest:
+    name: Doctest
+    runs-on: ubuntu-24.04
+    needs: build
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.13"
+      - uses: pyvista/setup-headless-display-action@v4
+      - name: Install system packages for OCCT-backed examples
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y \
+            libgl1-mesa-dev libglu1 libxft2 libxcursor-dev libxinerama1 \
+            libocct-data-exchange-dev libocct-foundation-dev xvfb pandoc openscad
+      - run: uv sync --extra docs
+      - run: uv run make -C doc doctest

pyvista_cad-0.0.1/.gitignore

@@ -0,0 +1,60 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+*.egg
+
+# Virtual environments
+.venv/
+
+# uv lockfile (library: resolve fresh, do not pin)
+uv.lock
+
+# Testing / coverage / benchmarks
+.coverage
+.pytest_cache/
+.benchmarks/
+.hypothesis/
+htmlcov/
+coverage.xml
+
+# Type checking / linting
+.mypy_cache/
+.ruff_cache/
+
+# Profiling
+*.prof
+
+# OS
+.DS_Store
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Agent / local tooling
+.claude/
+
+# Local-only notes, design docs, audits, benchmarks (not published)
+notes/
+
+# setuptools_scm-generated version file
+src/pyvista_cad/_version.py
+
+# Local env
+.env
+
+# pytest-pyvista regression failures
+tests/image_cache_failures/
+
+# Sphinx + Sphinx Gallery build artifacts
+doc/_build/
+doc/examples/
+doc/sg_execution_times.rst
+doc/api/_autosummary/
+doc/api/_backrefs/
+errors.txt

pyvista_cad-0.0.1/.pre-commit-config.yaml

@@ -0,0 +1,79 @@
+ci:
+  autoupdate_schedule: monthly
+
+# CAD/mesh fixtures are opaque binary-ish payloads. Whitespace,
+# end-of-file, line-ending, and spell hooks must never rewrite them.
+exclude: |
+  (?x)^(
+    .*\.(step|stp|dxf|brep|iges|igs|3mf|ifc|scad|glb|gltf|stl|obj|ply|vtk|vtu|vtp)
+  )$
+
+repos:
+  - repo: https://github.com/numpy/numpydoc
+    rev: v1.10.0
+    hooks:
+      - id: numpydoc-validation
+        files: ^src/pyvista_cad/
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: check-added-large-files
+        args: [--maxkb, "5000"]
+      - id: check-json
+      - id: check-merge-conflict
+      - id: check-shebang-scripts-are-executable
+      - id: check-toml
+      - id: check-yaml
+      - id: debug-statements
+      - id: detect-private-key
+      - id: trailing-whitespace
+      - id: check-docstring-first
+      - id: end-of-file-fixer
+      - id: mixed-line-ending
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.1
+    hooks:
+      - id: ruff-format
+      - id: ruff-check
+        args: ["--fix", "--show-fixes"]
+
+  - repo: https://github.com/rbubley/mirrors-prettier
+    rev: v3.8.1
+    hooks:
+      - id: prettier
+        types_or: [yaml, markdown, json]
+
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.30.0
+    hooks:
+      - id: gitleaks
+
+  - repo: https://github.com/python-jsonschema/check-jsonschema
+    rev: 0.36.1
+    hooks:
+      - id: check-github-workflows
+
+  - repo: https://github.com/ComPWA/taplo-pre-commit
+    rev: v0.9.3
+    hooks:
+      - id: taplo-format
+
+  - repo: https://github.com/streetsidesoftware/cspell-cli
+    rev: v9.2.0
+    hooks:
+      - id: cspell
+        # cspell-cli v9 needs Node >=20.18; pin so the hook does not
+        # fall back to whatever Node is on PATH (system Node may be 18).
+        language_version: "22.22.1"
+        args: ["--no-progress", "--no-summary"]
+
+  - repo: local
+    hooks:
+      - id: format-justfile
+        name: Format justfile
+        entry: just --fmt --unstable
+        language: system
+        files: "(^|/)justfile$|\\.just$"
+        pass_filenames: false

pyvista_cad-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The PyVista Developers
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyvista_cad-0.0.1/PKG-INFO

@@ -0,0 +1,219 @@
+Metadata-Version: 2.4
+Name: pyvista-cad
+Version: 0.0.1
+Summary: PyVista accessor and reader-registry plugin for CAD formats (STEP, IGES, BREP, DXF, 3MF, IFC, FCStd) and bridges to build123d, cadquery, OCP, and gmsh.
+Author-email: The PyVista Developers <info@pyvista.org>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/pyvista/pyvista-cad
+Project-URL: Documentation, https://pyvista.github.io/pyvista-cad/
+Project-URL: Issues, https://github.com/pyvista/pyvista-cad/issues
+Project-URL: Repository, https://github.com/pyvista/pyvista-cad
+Keywords: 3d,pyvista,cad,step,iges,brep,dxf,3mf,ifc,build123d,cadquery,opencascade
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: ezdxf>=1.3
+Requires-Dist: numpy>=1.24
+Requires-Dist: pooch>=1.8
+Requires-Dist: pyvista>=0.48.4
+Provides-Extra: step
+Requires-Dist: build123d>=0.7; extra == "step"
+Provides-Extra: step-light
+Requires-Dist: cascadio>=0.0.17; extra == "step-light"
+Provides-Extra: 3mf
+Requires-Dist: lib3mf>=2.3; extra == "3mf"
+Provides-Extra: ifc
+Requires-Dist: ifcopenshell>=0.7.0; extra == "ifc"
+Provides-Extra: iges
+Requires-Dist: pyiges[full]>=0.3; extra == "iges"
+Provides-Extra: gmsh
+Requires-Dist: gmsh>=4.13; extra == "gmsh"
+Provides-Extra: cadquery
+Requires-Dist: cadquery>=2.4; extra == "cadquery"
+Provides-Extra: trimesh
+Requires-Dist: pyvista-trimesh>=0.1; extra == "trimesh"
+Provides-Extra: full
+Requires-Dist: pyvista-cad[3mf,cadquery,gmsh,ifc,iges,step,trimesh]; extra == "full"
+Provides-Extra: docs
+Requires-Dist: pyvista-cad[full]; extra == "docs"
+Requires-Dist: cadquery>=2.4; extra == "docs"
+Requires-Dist: pandas>=2.0; extra == "docs"
+Requires-Dist: sphinx>=8.0; extra == "docs"
+Requires-Dist: sphinx-gallery>=0.18; extra == "docs"
+Requires-Dist: sphinx-design>=0.6; extra == "docs"
+Requires-Dist: sphinx-copybutton>=0.5; extra == "docs"
+Requires-Dist: sphinx-book-theme>=1.1; extra == "docs"
+Requires-Dist: myst-parser>=4.0; extra == "docs"
+Requires-Dist: sphinx-notfound-page>=1.1; extra == "docs"
+Requires-Dist: numpydoc>=1.10; extra == "docs"
+Requires-Dist: pypandoc>=1.13; extra == "docs"
+Requires-Dist: pyvista[jupyter]; extra == "docs"
+Provides-Extra: dev
+Requires-Dist: pyvista-cad[docs]; extra == "dev"
+Requires-Dist: mypy==2.1.0; extra == "dev"
+Requires-Dist: ruff==0.15.13; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-benchmark>=4.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: pytest-pyvista>=0.2; extra == "dev"
+Requires-Dist: hypothesis>=6.100; extra == "dev"
+Dynamic: license-file
+
+<p align="center">
+  <img src="https://github.com/pyvista/pyvista/raw/main/doc/source/_static/pyvista_logo.svg" alt="PyVista" width="400" />
+</p>
+
+# pyvista-cad
+
+[![CI](https://github.com/pyvista/pyvista-cad/actions/workflows/ci.yml/badge.svg)](https://github.com/pyvista/pyvista-cad/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/pyvista-cad.svg)](https://pypi.org/project/pyvista-cad/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+**CAD format reading, writing, and CAD-style plotting for [PyVista](https://github.com/pyvista/pyvista).**
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/pyvista/pyvista-cad/main/doc/_static/hero.png" alt="The same flange shown two ways: a generic mesh viewer drawing the raw triangulation on the left, and pyvista-cad drawing smoothly shaded faces with the model's topological edges on the right." width="90%">
+</p>
+
+`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
+
+| Extra          | Adds                    | Formats unlocked                    |
+| -------------- | ----------------------- | ----------------------------------- |
+| (base)         | ezdxf                   | DXF read + write, glTF read + write |
+| `[step]`       | build123d, cadquery-ocp | STEP, BREP, FCStd, build123d bridge |
+| `[step-light]` | cascadio                | STEP (read-only, faster, no colors) |
+| `[3mf]`        | lib3mf                  | 3MF read + write                    |
+| `[ifc]`        | ifcopenshell            | IFC read (with property sets)       |
+| `[iges]`       | pyiges[full]            | IGES read                           |
+| `[gmsh]`       | gmsh                    | gmsh bridge for FEA meshing         |
+| `[openscad]`   | (uses `openscad` CLI)   | SCAD read                           |
+| `[full]`       | all of the above        | every supported format              |
+
+**Python support:** 3.10 – 3.13. Python 3.14 is not yet supported: the
+`[step]`/`[full]` extras depend on `cadquery-ocp`, which publishes no
+cp314 wheels for any platform. 3.14 will be added once those wheels ship.
+
+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.
+
+```bash
+pip install pyvista-cad           # DXF and glTF only
+pip install pyvista-cad[step]     # add STEP, BREP, FCStd
+pip install pyvista-cad[full]     # everything
+```
+
+## Quick start
+
+```python
+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
+```
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/pyvista/pyvista-cad/main/doc/_static/readme_quickstart.png" alt="Two independent example fixtures. Left: a STEP part read with pv.read, drawn CAD-style with shaded faces and topological edges. Right: a DXF drawing split into colored per-layer blocks (body, centerlines, dimensions, holes)." width="90%">
+</p>
+
+## 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.
+
+```python
+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()
+```
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/pyvista/pyvista-cad/main/doc/_static/readme_cad_plotting.png" alt="The NIST AM Bench specimen. Left: cad.plot draws shaded faces with topological B-rep edges. Right: the same cached block colored by a height scalar with the viridis colormap, the topological edges still drawn." width="90%">
+</p>
+
+`.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. Needs the
+`[gmsh]` extra.
+
+```python
+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)
+    grid = pyvista_cad.from_gmsh()
+finally:
+    gmsh.finalize()
+
+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
+```
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/pyvista/pyvista-cad/main/doc/_static/readme_workflow.png" alt="A 3-part NIST build assembly. Three steps: the full assembly as read (CAD-style), the located PartCAD component highlighted against the muted rest, then that part meshed tetrahedrally with gmsh and crinkle-clipped to expose the colored tet interior." width="100%">
+</p>
+
+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
+
+| Task                                      | How                                                                                       |
+| ----------------------------------------- | ----------------------------------------------------------------------------------------- |
+| Read a STEP assembly with per-part colors | `pv.read('a.step')` returns a `MultiBlock`; each block has `cad.color` and `cad.label`    |
+| Split a DXF by layer                      | `pv.read('a.dxf').cad.split_by_layer()`                                                   |
+| Round-trip a 3MF print                    | `pyvista_cad.write_three_mf(mb, 'b.3mf')` (object color + units kept)                     |
+| Load an IFC building and filter walls     | `mb = pv.read('b.ifc'); walls = mb.cad.find(ifc_type='IfcWall')`                          |
+| Read IFC property sets                    | `json.loads(block.field_data['cad.psets'][0])` returns the source `Pset_*` / `Qto_*` dict |
+| Convert build123d to PyVista              | `pyvista_cad.from_build123d(part)` (preserves color, label, transform)                    |
+| Mesh a STEP for FEA in gmsh               | `pyvista_cad.to_gmsh(...)` then gmsh; see `examples/05_workflows/cad_to_fea_tet_mesh.py`  |
+| Generate a signed distance field from CAD | see `examples/05_workflows/cad_to_signed_distance.py`                                     |
+
+## 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.