/build123d

name: build123d
description: CAD modeling with build123d Python library. Use when creating 3D models, exporting to GLB/STEP/STL, or doing boolean operations (union, difference, intersection). Triggers on: CAD, 3D modeling, sphere, box, cylinder, mesh export, GLB, STEP, STL, solid modeling, parametric design, threads, fasteners, bolts, nuts, screws, gears, pipes, flanges, bearings, bd_warehouse, spur gear, helical gear, bevel gear, planetary gear, ring gear, cycloid gear, rack and pinion, gggears, herringbone, gear mesh, gear train.

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

• **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