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

> Explore text-to-CAD usage examples. Convert natural language prompts into STEP, STL, and GLB files using the text-to-CAD pipeline for manufacturable 3D artifacts.

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

---

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

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

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

```

This CLI calls `cadpy.api.inspect_refs()` from [`packages/cadpy/src/cadpy/inspection.py`](https://github.com/earthtojake/text-to-cad/blob/main/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.

```bash

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

```bash

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

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

```

The viewer launcher, documented in [`viewer/README.md`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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.