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