:orphan:

.. _gallery:

Gallery
=======

End-to-end examples of the ``pyvista-cad`` API. Each section drills
into one concern: reading a format, writing a format, bridging
to another CAD library, working with CAD metadata, or composing a
full workflow.


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. thumbnail-parent-div-close

.. raw:: html

    </div>


Reading CAD formats
===================

Examples that take a CAD file on disk and produce a PyVista dataset.
Every reader is reachable through ``pv.read(...)`` once
``pyvista_cad`` is installed.


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="3MF is the modern interchange format for additive manufacturing. It carries per-object geometry, names, colors, and units in a single archive. This example loads a real 3MF from the 3MF Consortium sample set (BSD-2-Clause): a colored dodecahedron chain from the material extension.">

.. only:: html

  .. image:: /examples/01_readers/images/thumb/sphx_glr_read_3mf_thumb.png
    :alt:

  :doc:`/examples/01_readers/read_3mf`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Read a 3MF package</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="BREP is OpenCASCADE&#x27;s native shape serialization, the format every OCCT-backed tool (FreeCAD, build123d, cadquery) can round-trip losslessly. No openly licensed real-world .brep corpus exists, so this example takes a real STEP part, the NIST AM Bench 2022 LPBF bridge specimen (public domain, https://doi.org/10.18434/mds2-2607), serializes it to BREP, and reads it back into pyvista.PolyData.">

.. only:: html

  .. image:: /examples/01_readers/images/thumb/sphx_glr_read_brep_thumb.png
    :alt:

  :doc:`/examples/01_readers/read_brep`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Read a BREP solid</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="DXF is the dominant 2D interchange format: mechanical drawings, PCB outlines, architectural floor plans. This example loads a real DXF drawing from the ezdxf project (MIT) whose entities span three named layers (``0``, BLUE, RED), and shows how every drawable entity becomes a cell on a single pyvista.PolyData with its originating layer preserved on the cad.layer cell-data array.">

.. only:: html

  .. image:: /examples/01_readers/images/thumb/sphx_glr_read_dxf_thumb.png
    :alt:

  :doc:`/examples/01_readers/read_dxf`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Read a DXF drawing</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip=".FCStd is FreeCAD&#x27;s native document format: a zip archive carrying Document.xml plus one BREP per part. pyvista_cad.read_fcstd parses the manifest and tessellates the BREPs via OCP, no FreeCAD binary required.">

.. only:: html

  .. image:: /examples/01_readers/images/thumb/sphx_glr_read_fcstd_thumb.png
    :alt:

  :doc:`/examples/01_readers/read_fcstd`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Read a FreeCAD document</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="IFC (Industry Foundation Classes) is the dominant interchange format for buildings and infrastructure (BIM). This example loads a real BIM model, the buildingSMART &quot;Single-family house&quot; sample (CC-BY 4.0, buildingSMART International), and confirms that every product becomes one block in a pyvista.MultiBlock with cad.guid, cad.ifc_type, cad.label, and cad.material field data attached.">

.. only:: html

  .. image:: /examples/01_readers/images/thumb/sphx_glr_read_ifc_thumb.png
    :alt:

  :doc:`/examples/01_readers/read_ifc`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Read an IFC building</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="IGES (``.iges`` / .igs) is one of the older neutral CAD interchange formats, still common for legacy mechanical hand-offs and turbomachinery. pyvista_cad.read_iges wraps pyiges and tessellates analytic surfaces with geomdl.">

.. only:: html

  .. image:: /examples/01_readers/images/thumb/sphx_glr_read_iges_thumb.png
    :alt:

  :doc:`/examples/01_readers/read_iges`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Read an IGES file</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="pyvista_cad.read_scad shells out to the openscad CLI, captures the STL it emits, and returns it as a pyvista.PolyData. The OpenSCAD binary must be installed and on PATH.">

.. only:: html

  .. image:: /examples/01_readers/images/thumb/sphx_glr_read_scad_thumb.png
    :alt:

  :doc:`/examples/01_readers/read_scad`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Compile an OpenSCAD source file</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="STEP is the dominant neutral interchange format in mechanical CAD. This example loads a real STEP part, the NIST AM Bench 2022 LPBF bridge specimen (public domain, https://doi.org/10.18434/mds2-2607), and inspects the resulting pyvista.MultiBlock. Every STEP part becomes one block with its OCCT label and color attached as cad.label / cad.color field data.">

.. only:: html

  .. image:: /examples/01_readers/images/thumb/sphx_glr_read_step_thumb.png
    :alt:

  :doc:`/examples/01_readers/read_step`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Read a STEP part</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>


Writing CAD formats
===================

Examples that take a PyVista dataset and write it to a CAD file on
disk via :func:`pyvista_cad.write_dxf` or the ``.cad`` accessor.


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Export a printable part to 3MF. The 3MF format carries per-object names, units, and (where supported) colors: everything a modern slicer needs to put the part on the build plate.">

.. only:: html

  .. image:: /examples/02_writers/images/thumb/sphx_glr_write_3mf_thumb.png
    :alt:

  :doc:`/examples/02_writers/write_3mf`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Write a 3MF package</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Serialize a tessellated pyvista.PolyData as a faceted TopoDS_Compound in OpenCASCADE&#x27;s native BREP format. BREP is the canonical handoff to any OCCT-aware tool (FreeCAD, build123d, cadquery).">

.. only:: html

  .. image:: /examples/02_writers/images/thumb/sphx_glr_write_brep_thumb.png
    :alt:

  :doc:`/examples/02_writers/write_brep`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Write a BREP file</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Round-trip a real 2D drawing through PyVista back out to DXF. The layer assignment of every cell is preserved on the cad.layer array.">

.. only:: html

  .. image:: /examples/02_writers/images/thumb/sphx_glr_write_dxf_thumb.png
    :alt:

  :doc:`/examples/02_writers/write_dxf`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Write a DXF drawing</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Send a tessellated mesh back to a STEP file via OCCT&#x27;s STEPControl_Writer. The result is faceted (triangulated), not a B-rep reconstruction, ideal for downstream tools that accept STEP for visualization or CAM but do not require analytical surfaces.">

.. only:: html

  .. image:: /examples/02_writers/images/thumb/sphx_glr_write_step_faceted_thumb.png
    :alt:

  :doc:`/examples/02_writers/write_step_faceted`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Write a faceted STEP file</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>


Bridges to CAD kernels
======================

Round-trip data between PyVista and the major Python CAD kernels:
build123d, cadquery, raw OCP / TopoDS, gmsh, and trimesh. Each bridge
attaches ``cad.source_format`` to the resulting dataset so the origin is
traceable through downstream pipelines.


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Tessellate a build123d solid with OCCT&#x27;s incremental mesher and wrap the result as a pyvista.PolyData. The deflection knobs trade mesh density for accuracy on curved faces.">

.. only:: html

  .. image:: /examples/03_bridges/images/thumb/sphx_glr_from_build123d_box_thumb.png
    :alt:

  :doc:`/examples/03_bridges/from_build123d_box`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">build123d -> PyVista</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="A build123d Compound with labelled children becomes a pyvista.MultiBlock whose block names match the child labels. Per-block cad.label and cad.color field data are preserved.">

.. only:: html

  .. image:: /examples/03_bridges/images/thumb/sphx_glr_from_build123d_compound_thumb.png
    :alt:

  :doc:`/examples/03_bridges/from_build123d_compound`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">build123d Compound -> MultiBlock</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Convert a cadquery Workplane straight to a pyvista.PolyData by tessellating its underlying OCCT shape.">

.. only:: html

  .. image:: /examples/03_bridges/images/thumb/sphx_glr_from_cadquery_workplane_thumb.png
    :alt:

  :doc:`/examples/03_bridges/from_cadquery_workplane`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">cadquery -> PyVista</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Wrap a pyvista.PolyData as a build123d Compound of faceted triangles, then push it onward to STEP through build123d&#x27;s native exporter. This is the canonical &quot;scanned mesh into a CAD pipeline&quot; flow.">

.. only:: html

  .. image:: /examples/03_bridges/images/thumb/sphx_glr_to_build123d_thumb.png
    :alt:

  :doc:`/examples/03_bridges/to_build123d`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">PyVista -> build123d</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Send a tessellated pyvista.PolyData back into the OCCT world as a faceted TopoDS_Compound. Useful when downstream OCCT-based code expects shape objects rather than meshes, e.g. boolean operations or further OCCT-native exports.">

.. only:: html

  .. image:: /examples/03_bridges/images/thumb/sphx_glr_to_topods_thumb.png
    :alt:

  :doc:`/examples/03_bridges/to_topods`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">PyVista -> TopoDS_Compound</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Push a pyvista.PolyData surface into a gmsh model, then pull the result back as a pyvista.UnstructuredGrid. Use this when you need gmsh&#x27;s remesher, e.g. to clean up a noisy scan or to prepare a surface for a downstream FEA tet-mesher.">

.. only:: html

  .. image:: /examples/03_bridges/images/thumb/sphx_glr_via_gmsh_thumb.png
    :alt:

  :doc:`/examples/03_bridges/via_gmsh`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">gmsh round-trip</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>


Metadata, units, and layers
===========================

Examples that exercise the ``cad.*`` metadata schema: units handling,
DXF layer splits, color groupings, and the
:class:`pyvista_cad.CadMetadata` bag.


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="The .cad accessor adds walk, find, and flatten for hierarchical CAD assemblies. walk yields (path, block) pairs; find filters by metadata predicates; flatten collapses every leaf to a single-level MultiBlock with path-named blocks.">

.. only:: html

  .. image:: /examples/04_metadata/images/thumb/sphx_glr_assembly_tree_walk_thumb.png
    :alt:

  :doc:`/examples/04_metadata/assembly_tree_walk`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Walk and filter a real IFC assembly</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="3MF stores one &lt;object&gt; per mesh. When you write a pyvista.MultiBlock, every block name and cad.label is preserved on the way in and on the way out.">

.. only:: html

  .. image:: /examples/04_metadata/images/thumb/sphx_glr_color_aware_3mf_thumb.png
    :alt:

  :doc:`/examples/04_metadata/color_aware_3mf`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Per-object names round-trip through 3MF</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="A STEP file with multiple parts arrives as a pyvista.MultiBlock. Per-part labels and colors are attached as cad.label / cad.color field data. Use .cad.find and .cad.walk to navigate the tree.">

.. only:: html

  .. image:: /examples/04_metadata/images/thumb/sphx_glr_inspect_step_assembly_thumb.png
    :alt:

  :doc:`/examples/04_metadata/inspect_step_assembly`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Inspect a STEP assembly</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Use the .cad accessor to fan a single pyvista.PolyData back out into a pyvista.MultiBlock keyed by layer name. Each block contains only the cells originally drawn on that layer.">

.. only:: html

  .. image:: /examples/04_metadata/images/thumb/sphx_glr_split_by_layer_dxf_thumb.png
    :alt:

  :doc:`/examples/04_metadata/split_by_layer_dxf`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Split a DXF drawing by layer</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="The cad.units field-data slot records the document unit on read and write. units_conversion_factor returns the scalar to multiply points by to reach a target unit, so an mm-defined part can move into meters (for FEA) or inches (for US-customary CAM) without leaving the pipeline.">

.. only:: html

  .. image:: /examples/04_metadata/images/thumb/sphx_glr_units_and_conversion_thumb.png
    :alt:

  :doc:`/examples/04_metadata/units_and_conversion`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Units and unit conversion</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>


End-to-end workflows
====================

Examples that stitch readers, writers, bridges, and metadata into
realistic CAD-meets-mesh pipelines.


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="A real reverse-engineering question: a vendor ships a nominal CAD model of a part, and a depth camera reconstructs the part that actually arrived. Where, and by how much, does the as-built surface deviate from design?">

.. only:: html

  .. image:: /examples/05_workflows/images/thumb/sphx_glr_as_designed_vs_scan_thumb.png
    :alt:

  :doc:`/examples/05_workflows/as_designed_vs_scan`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">As-designed vs as-scanned deviation</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Drive a CAD shape through gmsh to obtain a tetrahedral mesh suitable for finite-element analysis, then bring the volumetric result back into PyVista as an pyvista.UnstructuredGrid.">

.. only:: html

  .. image:: /examples/05_workflows/images/thumb/sphx_glr_cad_to_fea_tet_mesh_thumb.png
    :alt:

  :doc:`/examples/05_workflows/cad_to_fea_tet_mesh`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">CAD shape to tetrahedral FEA mesh</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="A tessellated CAD part drives a signed-distance volume directly through PyVista&#x27;s compute_implicit_distance. The result is a volumetric scalar field useful for collision queries, mesh morphing, implicit modeling, or feeding marching-cubes-style reconstructions.">

.. only:: html

  .. image:: /examples/05_workflows/images/thumb/sphx_glr_cad_to_signed_distance_thumb.png
    :alt:

  :doc:`/examples/05_workflows/cad_to_signed_distance`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">CAD shape to signed-distance field</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="A common prototyping job: you need many copies of one part, so you nest them on a build plate and hand a single 3MF to the slicer with each instance named so the slicer tree mirrors the layout.">

.. only:: html

  .. image:: /examples/05_workflows/images/thumb/sphx_glr_parametric_to_3d_print_thumb.png
    :alt:

  :doc:`/examples/05_workflows/parametric_to_3d_print`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Real CAD part to a 3D-print 3MF plate</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>


Advanced topics
===============

Customizing tessellation, walking nested assemblies, and running
pyvista-cad in headless server environments.


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="A generic mesh viewer draws the triangulation: with show_edges=True you see every facet edge, an artifact of the tessellation tolerance that means nothing to a CAD user. What a CAD user wants is the model&#x27;s topological edges (the B-rep feature curves) over smoothly shaded faces, exactly like a CAD application&#x27;s viewport.">

.. only:: html

  .. image:: /examples/06_advanced/images/thumb/sphx_glr_cad_friendly_plot_thumb.png
    :alt:

  :doc:`/examples/06_advanced/cad_friendly_plot`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">CAD-friendly plotting</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="OCCT&#x27;s BRepMesh_IncrementalMesh exposes a linear and angular deflection knob. Coarser deflection yields fewer triangles; finer deflection yields smoother curves. read_step, read_brep, read_fcstd, and the build123d / cadquery bridges all forward these knobs.">

.. only:: html

  .. image:: /examples/06_advanced/images/thumb/sphx_glr_custom_tessellation_thumb.png
    :alt:

  :doc:`/examples/06_advanced/custom_tessellation`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Custom tessellation deflection</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="IFC files arrive as deeply-nested pyvista.MultiBlock trees (building / storey / element). For some downstream analyses you want one mesh, with each cell tagged by its source element. Combine the tree and carry an element id onto cell data so downstream code can filter by element without walking the tree.">

.. only:: html

  .. image:: /examples/06_advanced/images/thumb/sphx_glr_ifc_to_unstructured_grid_thumb.png
    :alt:

  :doc:`/examples/06_advanced/ifc_to_unstructured_grid`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Collapse an IFC building into a single UnstructuredGrid</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="The cad accessor on MultiBlock provides three traversal helpers: walk yields (path, block) pairs, find filters by glob or metadata predicates, and flatten collapses the tree to a single-level container with path-named entries.">

.. only:: html

  .. image:: /examples/06_advanced/images/thumb/sphx_glr_multiblock_walk_thumb.png
    :alt:

  :doc:`/examples/06_advanced/multiblock_walk`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Walk a real STEP assembly</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>


.. toctree::
   :hidden:
   :includehidden:


   /examples/01_readers/index.rst
   /examples/02_writers/index.rst
   /examples/03_bridges/index.rst
   /examples/04_metadata/index.rst
   /examples/05_workflows/index.rst
   /examples/06_advanced/index.rst