
build123d
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@vibecadRun it inside Claude Code after adding the marketplace with /plugin marketplace add rawwerks/VibeCAD.
Contents
Discovered from sourceSkills 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, Torus02_boolean_operations.py- Union (+), difference (-), intersection (&)03_export_formats.py- GLB, STEP, STL, BREP export04_positioning.py- Pos(), Rot() transforms05_sketch_extrude.py- 2D sketch to 3D solid06_fillet_chamfer.py- Edge rounding and beveling07_csg_classic.py- Classic CSG operations08_hole_pattern.py- GridLocations for hole patterns
3D Operations
loft.py- Connect multiple profilesvase.py- Revolve + edge filtering + shellingtea_cup.py- Revolve + sweep for handle
Advanced Techniques
roller_coaster.py- Helix + Spline curvespacked_boxes.py- pack() algorithmtoy_truck.py- Joints for assemblydual_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
- build123d: https://github.com/gumyr/build123d
- bd_warehouse: https://github.com/gumyr/bd_warehouse
- gggears: https://github.com/GarryBGoode/gggears
- render-glb: https://github.com/rawwerks/render-glb
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
| Format | Extension | Notes |
|---|---|---|
| STEP | .step, .stp | Recommended - full CAD fidelity |
| BREP | .brep | OpenCASCADE native format |
| STL | .stl | Mesh format - may have boolean issues |
Output Metrics
Primary Metrics (for ML training)
| Metric | Range | Description |
|---|---|---|
| IoU (Jaccard) | 0-1 | ` |
| Dice (F1) | 0-1 | `2 |
| Precision | 0-1 | ` |
| Recall | 0-1 | ` |
Diagnostic Metrics
| Metric | Description |
|---|---|
volume_ratio | B/A volume ratio (1.0 = same size) |
center_offset | Distance between centers of mass |
bbox_iou | Bounding box IoU (coarse alignment) |
size_ratio_x/y/z | Per-axis scale comparison |
surface_ratio | Surface 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:
| File | Description |
|---|---|
diff_reference.glb | The reference model (A) |
diff_generated.glb | The generated model (B) |
diff_missing.glb | Geometry in A but not B (under-generation) |
diff_extra.glb | Geometry in B but not A (over-generation) |
diff_common.glb | Geometry 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