How to Convert Text Descriptions to 3D Models with text-to-cad

The text-to-cad repository provides a modular "skills" architecture that uses LLMs to transform natural language design briefs into production-ready STEP files through build123d Python source code, isolated agent scripts, and deterministic validation pipelines.

The earthtojake/text-to-cad project enables engineers and designers to convert text descriptions to 3D models using a unique agent-based system where each skill operates as a self-contained unit. Unlike traditional CAD automation, this approach treats natural language as the primary interface for generating parametric geometry, enforcing strict reproducibility through source-controlled Python scripts rather than binary file manipulation.

Understanding the Modular Skills Architecture

The repository implements an isolated skills architecture where each capability is encapsulated as a standalone agent under the skills/ directory. This design ensures that no skill imports code from another, preventing dependency drift and guaranteeing reproducible outputs.

Each skill exposes a CLI-style API through executable scripts in scripts/ and documents its behavior in a SKILL.md file. For CAD operations specifically, the skills/cad/SKILL.md file defines the complete specification for transforming text into geometry. Shared runtime utilities live in packages/cadpy/, packages/cadjs/, and packages/implicitjs/, which the bundling script at scripts/bundle/bundle.sh vendors into each skill to maintain consistency.

The CAD Skill Workflow

Converting text to 3D models follows a rigorous seven-step pipeline defined in skills/cad/SKILL.md. This workflow enforces non-negotiable rules: STEP is always the primary artifact, all geometry edits occur in source code never in generated files, and snapshot validation is mandatory before completion.

Step 1: Request Classification

The system first classifies the incoming request to determine whether the user needs a new part, an assembly, an inspection report, or a modification to an existing model. This classification dictates which scripts the LLM agent will invoke.

Step 2: Creating the CAD Brief

The agent generates a CAD brief following the template in references/cad-brief.md. This structured document extracts critical parameters including dimensions, units, material specifications, and feature intent from the natural language input, creating an unambiguous specification for the geometry generator.

Step 3: Generating build123d Source

The core generation happens in Python source files using the build123d library. The skill implements a gen_step() function that constructs geometry programmatically. This source-controlled approach ensures that every model is editable, diffable, and reproducible, unlike black-box CAD exports.

Step 4-7: Validation, Snapshot, and Export

After generating the STEP file using scripts/step, the pipeline runs scripts/inspect with flags like --facts, --planes, and --positioning to validate geometric correctness. The scripts/snapshot utility then generates PNG visual packets for human verification. Finally, if secondary formats are required, the system can export to STL, 3MF, or GLB as specified in references/supported-exports.md.

Core Components and Directory Structure

The repository organizes its components into distinct directories that separate generation logic from persistent artifacts:

• skills/cad/ – Contains the CAD skill implementation, including SKILL.md and the build123d generation scripts
• packages/cadpy/ – Core Python helpers for STEP generation, inspection, and export utilities
• models/ – Persistent storage for generated STEP, STL, URDF, and other CAD artifacts
• viewer/ – The Vite-based CAD Viewer UI that launches automatically when previewing models
• benchmarks/ and assets/ – Git LFS-tracked example models and validation datasets

Generating Your First 3D Model

To convert text descriptions to 3D models with text-to-cad, you interact with the CLI scripts or use the Python API directly.

CLI Workflow Example

The following example generates a rectangular block with a hole using the command-line interface:

# Create a design brief

cat > block_brief.txt <<EOF
Create a 100 mm × 60 mm × 20 mm block with a centered 8 mm through-hole.
Add a 2 mm chamfer on the top outer perimeter.
EOF

# Generate the STEP file and Python source

python scripts/step block_brief.txt --out block.step

# Validate geometry with inspection tools

python scripts/inspect refs block.step --facts --planes --positioning

# Generate visual snapshot for verification

python scripts/snapshot block.step --out block_snapshot.png

# Launch the browser-based viewer

cad-viewer block.step

Direct Python API Usage

For programmatic control, import the cadpy package and use build123d primitives:

from cadpy import build123d
from cadpy import cad_helpers

def gen_step():
    # Construct base geometry

    block = build123d.Box(100, 60, 20)
    hole = build123d.Cylinder(8, 20, align=(0, 0, 0))
    
    # Apply boolean operations and features

    block = block - hole
    block = block.chamfer(2, faces=block.top_faces())
    return block

# Persist to STEP format

cad_helpers.save_step(gen_step(), "block.step")

Exporting to Secondary Formats

While STEP remains the primary artifact, you can generate mesh formats for 3D printing or visualization:

# Export to STL for additive manufacturing

python scripts/step block_brief.txt --out block.stl --export stl

# Export to GLB for web viewing

python scripts/step block_brief.txt --out block.glb --export glb

Validation and Quality Assurance

The text-to-cad system enforces quality through automated validation rather than manual inspection of binary files. The scripts/inspect tool analyzes generated STEP files to report geometric facts, validate plane alignments, and check positioning tolerances. This eliminates the need to use git diff on binary CAD outputs, instead providing deterministic verification that the generated geometry matches the brief specifications.

The scripts/snapshot utility complements this by rendering visual packets that human reviewers can quickly scan for aesthetic and functional correctness before the model is stored in the models/ directory.

Summary

• The skills architecture isolates CAD generation logic into self-contained agents under skills/cad/, preventing cross-dependencies and ensuring reproducibility.
• build123d Python source serves as the single source of truth for geometry, with gen_step() functions generating STEP files through the scripts/step CLI.
• STEP is the mandatory primary artifact, with STL, 3MF, and GLB available as secondary exports via references/supported-exports.md specifications.
• Validation pipelines use scripts/inspect for geometric verification and scripts/snapshot for visual confirmation, enforcing the non-negotiable rules defined in skills/cad/SKILL.md.

Frequently Asked Questions

What is the primary file format used by text-to-cad?

According to the skills/cad/SKILL.md specification, STEP is the mandatory primary artifact for all CAD operations. The system generates .step files as the canonical representation of 3D geometry, with all other formats (STL, 3MF, GLB) treated as secondary exports derived from this source file.

How does text-to-cad ensure reproducibility in 3D model generation?

The repository enforces reproducibility through source-controlled Python generators using the build123d library. Rather than manipulating binary CAD files directly, all geometry creation happens in gen_step() functions within .py files. This approach allows version control systems to diff changes in model logic rather than binary outputs, and the isolated skills architecture ensures consistent runtime environments through the scripts/bundle/bundle.sh vendoring system.

Can I export models to STL or GLB format for 3D printing?

Yes, the CAD skill supports secondary exports to STL, 3MF, and GLB formats as documented in references/supported-exports.md. Use the --export flag with the scripts/step command to specify your desired format, though the system always generates the STEP file first to maintain the primary artifact requirement.

What is the role of the CAD Viewer in the workflow?

The CAD Viewer (skills/cad-viewer/SKILL.md) launches a local browser-based interface for previewing STEP, G-code, and robot description files. It is invoked automatically when running cad-viewer <file.step> or through the skill integration, providing immediate visual feedback on generated geometry without requiring external CAD software installation.

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