Skills for using Build123D - a Python CAD library for creating parametric 3D models with code

version
0.1.0
GitHub stars
127

Install

/plugin install build123d@vibecad

Run it inside Claude Code after adding the marketplace with /plugin marketplace add rawwerks/VibeCAD.

Contents

Discovered from source

Skills 2

build123d CAD Modeling

Zero-Setup with uv

No installation required. Run any build123d script with:

uvx --from build123d python script.py

This automatically downloads build123d and runs your script. First run takes ~30s, subsequent runs are instant.

Install uv (if not already installed):

curl -LsSf https://astral.sh/uv/install.sh | sh

Critical: Imports

All exports are in the main module:

from build123d import Sphere, Box, Cylinder, export_gltf, export_step, export_stl

NEVER use from build123d.exporters import ... - this module does not exist.

Quick Start Example

#!/usr/bin/env python3
from build123d import Sphere, Box, export_gltf, Pos

# Create shapes
sphere = Sphere(radius=20)
box = Pos(15, 0, 0) * Box(10, 10, 10)

# Boolean union
result = sphere + box

# Export to GLB (for web viewers, Three.js)
export_gltf(result, "./model.glb", binary=True)
print("Exported model.glb")

Run it:

uvx --from build123d python my_model.py

Geometry Inspection (Optional)

To inspect geometry properties, add this to your script:

def inspect(shape):
    bbox = shape.bounding_box()
    print(f"Size: {bbox.max.X - bbox.min.X:.1f} x {bbox.max.Y - bbox.min.Y:.1f} x {bbox.max.Z - bbox.min.Z:.1f}")
    print(f"Volume: {shape.volume:.1f}")
    print(f"Faces: {len(shape.faces())}, Edges: {len(shape.edges())}")

inspect(result)

A full inspection harness is available in scripts/harness.py for advanced use.

Quick Reference

Shapes

Box(length, width, height)
Sphere(radius=20)
Cylinder(radius=10, height=25)
Cone(bottom_radius=15, top_radius=5, height=20)
Torus(major_radius=20, minor_radius=5)

Boolean Operations

union = shape1 + shape2           # Fuse
difference = shape1 - shape2      # Cut
intersection = shape1 & shape2    # Common volume

Positioning

from build123d import Pos, Rot
moved = Pos(x, y, z) * shape      # Translate
rotated = Rot(rx, ry, rz) * shape # Rotate (degrees)

Export

export_gltf(shape, "./out.glb", binary=True)  # GLB for web
export_step(shape, "./out.step")              # CAD interchange
export_stl(shape, "./out.stl")                # 3D printing

Examples by Capability

21 runnable examples in references/examples/:

Basics (01-08)

  • 01_simple_shapes.py - Box, Sphere, Cylinder, Cone, Torus
  • 02_boolean_operations.py - Union (+), difference (-), intersection (&)
  • 03_export_formats.py - GLB, STEP, STL, BREP export
  • 04_positioning.py - Pos(), Rot() transforms
  • 05_sketch_extrude.py - 2D sketch to 3D solid
  • 06_fillet_chamfer.py - Edge rounding and beveling
  • 07_csg_classic.py - Classic CSG operations
  • 08_hole_pattern.py - GridLocations for hole patterns

3D Operations

  • loft.py - Connect multiple profiles
  • vase.py - Revolve + edge filtering + shelling
  • tea_cup.py - Revolve + sweep for handle

Advanced Techniques

  • roller_coaster.py - Helix + Spline curves
  • packed_boxes.py - pack() algorithm
  • toy_truck.py - Joints for assembly
  • dual_color_3mf.py - Multi-color 3MF export

Run any example:

uvx --from build123d python references/examples/01_simple_shapes.py

Advanced Patterns

For builder mode, edge filtering, loft, sweep, revolve: See references/advanced-patterns.md

bd_warehouse - Parametric Parts Library

For threads, fasteners, simple gears, pipes, flanges, and bearings: See references/bd-warehouse-reference.md

uvx --from build123d --with bd_warehouse python script.py

Examples: 09_bd_warehouse_threads.py through 14_bd_warehouse_bearings.py

gggears - Advanced Gear Generation

For advanced parametric gears (spur, helical, bevel, planetary, cycloid, racks): See references/gggears-reference.md

uvx --from build123d --with "gggears @ git+https://github.com/GarryBGoode/gggears" python script.py

Examples: 15_gggears_spur.py through 20_gggears_rack.py

Quick example:

from gggears import SpurGear, UP
from build123d import export_gltf

gear1 = SpurGear(number_of_teeth=12, module=2.0, height=10.0)
gear2 = SpurGear(number_of_teeth=24, module=2.0, height=10.0)
gear1.mesh_to(gear2, target_dir=UP)

assembly = gear1.build_part() + gear2.build_part()
export_gltf(assembly, "./gears.glb", binary=True)

Post-Processing Pipeline

After exporting GLB, you can optimize and verify:

# 1. Optimize for web delivery (optional)
bunx @gltf-transform/cli optimize model.glb optimized.glb --compress draco

# 2. Render to image for visual verification
bunx render-glb model.glb preview.png

See the gltf-transform and render-glb plugins for full documentation.

Source Repositories

3D Model Comparison Tool

Compare CAD models using boolean operations to compute similarity metrics like IoU, Dice, precision, and recall. Useful for:

  • Evaluating ML-generated models against gold references
  • Comparing revisions of CAD designs
  • Computing metrics for training 3D generative models
  • Visualizing geometric differences

Quick Start

# Compare two STEP files
uvx --from build123d python scripts/model_diff.py reference.step generated.step

# JSON output for training pipelines
uvx --from build123d python scripts/model_diff.py ref.step gen.step --json --no-export

# Demo mode (no files needed)
uvx --from build123d python scripts/model_diff.py --demo

Supported Formats

FormatExtensionNotes
STEP.step, .stpRecommended - full CAD fidelity
BREP.brepOpenCASCADE native format
STL.stlMesh format - may have boolean issues

Output Metrics

Primary Metrics (for ML training)

MetricRangeDescription
IoU (Jaccard)0-1`
Dice (F1)0-1`2
Precision0-1`
Recall0-1`

Diagnostic Metrics

MetricDescription
volume_ratioB/A volume ratio (1.0 = same size)
center_offsetDistance between centers of mass
bbox_iouBounding box IoU (coarse alignment)
size_ratio_x/y/zPer-axis scale comparison
surface_ratioSurface area comparison

Interpretation

The tool provides automatic interpretation:

  • Over-generating: Low precision, high extra geometry
  • Under-generating: Low recall, missing geometry
  • Size issues: Volume ratio far from 1.0
  • Position issues: Large center offset

CLI Options

usage: model_diff.py [-h] [-o OUTPUT_DIR] [--json] [--no-export] [--demo]
                     [reference] [generated]

positional arguments:
  reference          Reference/gold model file (STEP, BREP, or STL)
  generated          Generated/predicted model file to compare

options:
  -o, --output-dir   Output directory for GLB files (default: .)
  --json             Output only JSON metrics (for pipelines)
  --no-export        Skip exporting GLB visualization files
  --demo             Run with built-in demo models

Output Files

When --no-export is not set, produces GLB files for visualization:

FileDescription
diff_reference.glbThe reference model (A)
diff_generated.glbThe generated model (B)
diff_missing.glbGeometry in A but not B (under-generation)
diff_extra.glbGeometry in B but not A (over-generation)
diff_common.glbGeometry in both (correct match)

Example: Training Pipeline Integration

# Batch evaluation
for gen in outputs/*.step; do
    uvx --from build123d python model_diff.py gold.step "$gen" --json --no-export
done | jq -s '{
    avg_iou: (map(.iou) | add / length),
    avg_precision: (map(.precision) | add / length),
    avg_recall: (map(.recall) | add / length)
}'

Example: Loss Function

# In your training code, use metrics for loss:
loss = (
    (1 - metrics['iou']) * 1.0 +           # Primary shape match
    abs(1 - metrics['volume_ratio']) * 0.5 + # Scale accuracy
    metrics['center_offset'] * 0.1           # Position accuracy
)

How It Works

The tool uses boolean operations from OpenCASCADE (via build123d):

Missing  = Reference - Generated  (A - B)
Extra    = Generated - Reference  (B - A)
Common   = Reference & Generated  (A ∩ B)
Union    = Reference + Generated  (A ∪ B)

IoU      = volume(Common) / volume(Union)
Dice     = 2 * volume(Common) / (volume(A) + volume(B))
Precision = volume(Common) / volume(B)
Recall    = volume(Common) / volume(A)

Sample Output

=================================================================
  3D MODEL COMPARISON REPORT
  Reference (A) vs Generated (B)
=================================================================

──────────────────────────── VOLUMES ────────────────────────────
  Reference (A):          51,433.629
  Generated (B):          45,904.426
  Intersection (A∩B):     42,292.031
  Missing (A-B):           9,141.598  (17.8% of A)
  Extra (B-A):             3,612.395  (7.9% of B)

──────────────────────── PRIMARY METRICS ────────────────────────
  IoU (Jaccard):              0.7683  (1.0 = identical)
  Dice (F1):                  0.8690  (1.0 = identical)
  Precision:                  0.9213  (correctness of B)
  Recall:                     0.8223  (coverage of A)

──────────────────────── INTERPRETATION ─────────────────────────
  △ Partial match (IoU > 50%)
  → Under-generating: 17.8% of A is missing
  → Undersized by 10.8%
=================================================================

Sponsors

Details

Marketplace
rawwerks/VibeCAD
Source
plugins/build123d
Category
Community
Keywords
cad, 3d, parametric, python, build123d

More from rawwerks/VibeCAD

All 3