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.
  • BRep Graph, BRepGraph node counts, adjacency & shared edges, per-graph UIDs, and history tracking through operations.
    • BREP Graph: Durable Identity & UIDs: the deep dive on identity. The three UID flavours, minting and resolving, the one-graph-instance scope rule (#295), what preserves identity versus mints a new one, and persistence.
  • Gordon Surfaces, skin a surface through a network of profile + guide curves (Surface.gordon / gordonReport), with build diagnostics.
  • Surfaces from Points, fit a B-spline through a grid (fromPointGrid) or a scattered cloud (plateThrough), and deform-to-targets (nlPlateDeformed).
  • Working with Meshes, the Mesh type: build from arrays, inspect, mesh-level booleans, triangle↔face picking, toShape, and SceneKit / RealityKit / Metal interop.

Table of contents