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

> Learn how to convert text descriptions to 3D models using text-to-cad. This powerful tool transforms natural language briefs into production-ready STEP files with LLMs and Python.

- Repository: [earthtojake/text-to-cad](https://github.com/earthtojake/text-to-cad)
- Tags: how-to-guide
- Published: 2026-07-24

---

**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`](https://github.com/earthtojake/text-to-cad/blob/main/SKILL.md) file. For CAD operations specifically, the [`skills/cad/SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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:

```bash

# 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:

```python
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:

```bash

# 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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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.