Link Search Menu Expand Document
OCCTSwift

OCCTSwift Cookbook

Task-oriented, example-rich guides for the OCCTSwift Swift API — one page per area, each a short bit of prose followed by runnable Swift snippets. This is the Swift-side counterpart to OCCT’s own dox/user_guides/ (which document the C++ API and are indexed on context7 as /open-cascade-sas/occt). Goal: make the Swift surface answerable by context7 too — see issue #210.

Conventions

  • Every example is runnable Swift in a ```swift block, using the real current API (fallible factories return optionals — examples unwrap with guard/if let, never force-unwrap). Examples double as living docs; keep them compiling against the shipped API.
  • One canonical place per topic. These pages hold usage; the Swift→OCCT mapping table lives in ../../API_REFERENCE.md, concepts in occt-concepts.md. Link, don’t duplicate.
  • Replicate OCCT’s examples. Where OCCT’s user guide shows a C++/Tcl example, port it to Swift so the same task is discoverable from either side.

Figures (rendered headlessly via OCCTSwiftViewport)

OCCTSwift ships no renderer — visualization is OFF in the xcframework (BUILD_MODULE_Visualization=OFF, see ../../visualization-research.md). Figures for these pages are produced out-of-repo by OCCTSwiftViewport’s headless Metal renderer (OffscreenRenderer, mesh-extraction path) and committed under images/. Each figure is built from the same OCCTSwift API the page shows, so the picture and the code never drift.

Render workflow — the figures are generated by the CookbookRender example in the OCCTSwiftViewport repo (it depends on the kernel + OCCTSwiftTools + Viewport, which OCCTSwift itself cannot, to avoid a dependency cycle):

cd OCCTSwiftViewport/Examples/CookbookRender
swift run CookbookRender <path-to-OCCTSwift>/docs/guides/cookbook/images

Add a scene there (one function per figure) when you add a page. macOS-only (Metal).

The same tool also exports a GLB per sample (via Exporter.writeGLTF, into models/), which the pages embed with Google’s <model-viewer> web component for an interactive 3D view (orbit / zoom), using the static PNG as the loading poster. Code → figure → 3D model all come from the one snippet.

Pages

  • Booleans — union / subtracting / intersection, fuzzy value, glue, timeout, self-intersection checks.
  • Threads — threadedShaft / threadedHole, ISO-68 / Unified specs, the boolean-free smooth build, runout & multi-start.
  • Helices & Springs — Wire.helix, sweeping a circle into a coiled spring, tapered / variable-section coils, and why threads can’t be built this way.
  • Lofting & Sweeps — extrude, revolve, sweep along a path, loft (ruled / smooth / point-capped), and multi-section pipe shells.
  • Helical Sweeps — helicalSweep helicoids, threadedRod worms/screws from a custom profile, and why you can’t boolean a helicoid onto a shaft.
  • Healing & Validity — isValid / isValidSolid / isSelfIntersecting, analyze, orientedForward, and the repair ops (healed / fixed / unified / sewn).
  • Meshing & Export — mesh (deflection), the Mesh type, mesh.toShape, and STL / OBJ / STEP / IGES / BREP / glTF export + import.
  • XCAF Assemblies — Document trees, components & instancing, names / colors / materials, and structured STEP / GLB round-trip.
  • Topology Graph — TopologyGraph node counts, adjacency & shared edges, durable UIDs, and history tracking through operations.
  • Gordon Surfaces — skin a surface through a network of profile + guide curves (Surface.gordon / gordonReport), with build diagnostics.

Table of contents