Text-to-CAD Usage Examples: Converting Natural Language to STEP, STL, and GLB

The text-to-CAD pipeline transforms natural-language prompts into manufacturable 3D artifacts by executing isolated skills that generate Build123d Python code, validate geometry, and export industry-standard CAD formats.

The earthtojake/text-to-cad repository implements a modular architecture where self-contained skills under skills/ convert plain text or reference images into solid models. Each skill writes a Python generator containing a gen_step() function, processes it through the cadpy API, and hands the resulting STEP file to a local CAD Viewer for interactive review.

Core Text-to-CAD Workflow

A complete text-to-CAD session follows a predictable lifecycle from prompt to preview. The skill receives a user prompt—plain text, an image, or an existing STEP file—and constructs a Build123d script that defines the geometry programmatically.

The skill then executes scripts/step to emit a STEP file and optional GLB representation. Validation occurs via scripts/inspect, which analyzes geometry facts, planes, and positioning. Visual verification uses scripts/snapshot to generate PNG or animated GIF renders. Finally, the skill exports secondary manufacturing formats with scripts/export and hands the result to $cad-viewer for a live preview URL.

All CLI commands are thin wrappers around the reusable Python API defined in packages/cadpy/src/cadpy/api.py, ensuring consistent behavior across skills.

Skill Isolation and Package Structure

Each text-to-CAD skill operates in strict isolation. Skills never import code from sibling directories, preventing dependency conflicts when installing individual capabilities via the Skills CLI.

Shared geometry logic—including STEP generation, GLB topology construction, and mesh payload handling—lives in packages/cadpy and packages/cadpy_metadata. During the bundle process, these utilities are vendored into each skill, guaranteeing that a single skill installation contains all required runtime code. This architecture is documented in AGENTS.md and enforced by the build system.

CLI Usage Examples

The repository provides five primary scripts that constitute the text-to-CAD toolchain. Each script targets a specific phase of the geometry pipeline.

Generate STEP Files with scripts/step

The step script executes a Build123d Python file containing a gen_step() function and outputs a validated STEP file.

python scripts/step \
  --kind part \
  --output my_part.step \
  my_part.py

Under the hood, this delegates to cadpy.api.generate_step(), implemented in packages/cadpy/src/cadpy/generation.py. The function builds the STEP topology from the Python source and handles geometric validation before writing to disk.

Validate Geometry with scripts/inspect

Before exporting, inspect the model’s geometric properties, reference planes, and spatial positioning to ensure the generator produced valid topology.

python scripts/inspect refs my_part.step \
  --facts \
  --planes \
  --positioning

This CLI calls cadpy.api.inspect_refs() from packages/cadpy/src/cadpy/inspection.py, producing a human-readable report of bounding boxes, center of mass, and datum plane orientations.

Render Visual Previews with scripts/snapshot

Create static PNGs or animated GIFs for documentation and verification without opening external CAD software.

# Static PNG capture

python scripts/snapshot \
  --input my_part.step \
  --output /tmp/my_part.png

# Animated orbit GIF

python scripts/snapshot \
  --input my_part.step \
  --output /tmp/my_part.gif \
  --mode orbit

The snapshot functionality uses an internal GLB exporter combined with a Three.js renderer, defined in packages/cadpy/src/cadpy/snapshot.py, to generate web-ready visuals directly from STEP or GLB input.

Export Manufacturing Formats with scripts/export

Convert the canonical STEP file into mesh formats suitable for 3D printing or downstream CAM workflows.

# High-resolution STL for printing

python scripts/export \
  --input my_part.step \
  --format stl \
  --resolution 96 \
  --output my_part.stl

# 3MF for Windows 3D printing pipeline

python scripts/export \
  --input my_part.step \
  --format 3mf \
  --output my_part.3mf

# GLB for web viewers and AR applications

python scripts/export \
  --input my_part.step \
  --format glb \
  --output my_part.glb

Export commands ultimately invoke cadpy.glb.export_glb() or cadpy.stl.export_stl(), located in packages/cadpy/src/cadpy/glb.py, handling tessellation and metadata preservation during format conversion.

Launch the CAD Viewer for Interactive Review

Hand the generated artifact to the CAD Viewer to obtain a shareable preview URL.

cad-viewer link /abs/path/to/models/my_part.step

The viewer launcher, documented in viewer/README.md, reads the absolute model path, starts a Vite development server on demand, and prints a URL that agents can embed in responses for immediate 3D visualization.

Key Source Files and API Reference

Understanding the text-to-CAD architecture requires familiarity with these specific modules:

• skills/cad/SKILL.md – Defines high-level CAD skill conventions, command structures, and viewer hand-off rules for agent implementations.
• scripts/step – CLI entry point that wraps cadpy.api.generate_step() and manages the Build123d execution environment.
• scripts/inspect – CLI entry point for cadpy.api.inspect_refs(), providing geometry introspection and validation.
• packages/cadpy/src/cadpy/api.py – Central Python API exposing STEP generation, inspection, and export functions used by all CLI tools.
• benchmarks/01-rectangular-calibration-block.md – End-to-end example demonstrating a natural language prompt, generated STEP output, snapshot creation, and viewer integration.

Summary

• Text-to-CAD skills are self-contained units under skills/ that transform prompts into Build123d Python generators without cross-skill dependencies.
• The STEP generation pipeline relies on scripts/step calling cadpy.api.generate_step(), while scripts/inspect validates output using cadpy.api.inspect_refs().
• Visual verification is handled by scripts/snapshot, which renders STEP files to PNG or GIF using Three.js, and scripts/export converts STEP to STL, 3MF, or GLB via cadpy.glb.export_glb().
• The CAD Viewer (cad-viewer) provides immediate web-based preview capabilities by accepting absolute model paths and launching a local Vite server.
• All geometry utilities are centralized in packages/cadpy and vendored into skills at build time to maintain isolation.

Frequently Asked Questions

What input formats does the text-to-CAD system accept?

The system accepts plain text prompts, reference images, or existing STEP files. These inputs guide the skill's construction of a Build123d Python script that defines the final geometry through the required gen_step() function.

How does skill isolation prevent dependency conflicts?

Each skill under skills/ operates as a standalone module that never imports from sibling skills. Shared functionality from packages/cadpy and packages/cadpy_metadata is vendored into the skill during bundling, ensuring that installing one skill via the Skills CLI includes all necessary runtime code without requiring external dependencies from other skills, as specified in AGENTS.md.

What is the role of the cad-viewer command in the workflow?

The cad-viewer link command accepts an absolute path to a generated STEP or mesh file and launches a local Vite-based viewer. It returns a live URL that agents can provide to users for interactive 3D inspection, completing the hand-off from programmatic generation to human review.

Which Python API functions handle the core geometry operations?

The cadpy.api module in packages/cadpy/src/cadpy/api.py exposes generate_step() for STEP file creation, inspect_refs() for geometric validation, and delegates to export_glb() and export_stl() for mesh conversion. These functions form the backend for the scripts/step, scripts/inspect, and scripts/export CLIs.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}