# How to Generate Parametric Models with text-to-cad: A Complete Developer Guide

> Generate parametric models from Python scripts using text-to-cad. This developer guide shows how to convert code to CAD, automatically rebuild geometry, and export to STEP or GLB.

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

---

**text-to-cad transforms Python scripts into parametric 3D CAD models by executing user code through the `cadgen` package, automatically rebuilding geometry when parameters change and exporting to STEP or GLB formats.**

The `earthtojake/text-to-cad` repository provides a code-first CAD environment where engineers define geometry through Python primitives rather than graphical interfaces. The system watches for parameter modifications and regenerates models instantly, bridging the gap between computational design and traditional CAD workflows.

## Understanding the cadgen Architecture

The core functionality resides in the `cadgen` Python package located under `packages/cadgen`. This package handles script parsing, geometry construction, and artifact generation through a modular pipeline.

In [`packages/cadgen/src/cadgen/cli/_run_model.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadgen/src/cadgen/cli/_run_model.py), the CLI entry point parses the script's `if __name__ == "__main__"` block and initiates the build process. The actual geometry construction occurs in [`packages/cadgen/src/cadgen/generation.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadgen/src/cadgen/generation.py), which exposes high-level primitives like `Box`, `Cylinder`, and `Extrude`. When execution completes, [`packages/cadgen/src/cadgen/snapshot_cli.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadgen/src/cadgen/snapshot_cli.py) serializes the generated solids into industry-standard formats including STEP, GLB, and URDF.

## Defining Parametric Behavior

True parametric modeling requires the system to recognize variables as tunable inputs rather than static values. The `cadgen.param` module provides typed parameter objects that embed metadata for validation and UI generation.

### Using Parameter Types

The [`packages/cadgen/src/cadgen/param.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadgen/src/cadgen/param.py) file defines `Float`, `Int`, and `Choice` classes. These objects specify default values, valid ranges, and human-readable labels:

```python
from cadgen.param import Float, Choice

# Define a parametric cylinder

radius: Float = Float(default=10.0, min=1.0, max=50.0, label="Radius")
height: Float = Float(default=30.0, min=5.0, max=100.0, label="Height")
material: Choice = Choice(choices=["aluminum", "steel"], default="aluminum", label="Material")

```

When the `cadgen` daemon detects changes to these values in [`packages/cadgen/src/cadgen/daemon/server.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadgen/src/cadgen/daemon/server.py), it automatically re-executes the model script and regenerates output files.

## Creating Your First Parametric Model

A minimal parametric model requires three components: parameter declarations, a build function, and a main execution block.

```python

# cylinder.py

from cadgen import Cylinder, Transform
from cadgen.param import Float

# ---- Parameters -------------------------------------------------

radius: Float = Float(default=10.0, min=1.0, max=50.0, label="Radius")
height: Float = Float(default=30.0, min=5.0, max=100.0, label="Height")

# ----------------------------------------------------------------

def build():
    # Create geometry using parameter objects

    cyl = Cylinder(radius=radius, height=height)
    # Position the cylinder so it sits on the origin plane

    return Transform(cyl, translate=(0, 0, height / 2))

if __name__ == "__main__":
    build()

```

Save this script as [`cylinder.py`](https://github.com/earthtojake/text-to-cad/blob/main/cylinder.py) and execute it directly:

```bash
python cylinder.py

```

The execution triggers `cadgen.cli._run_model` to process the file, generating `cylinder.step` and `cylinder.glb` in the working directory.

## Running Models via CLI

For production workflows, the `cadgen` CLI provides explicit control over export formats and build locations.

### Building STEP Files Explicitly

To generate a specific format without running the Python interpreter manually:

```bash
cadgen step build models/gearbox.py

```

This command invokes the logic in [`packages/cadgen/src/cadgen/cli/step_build.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadgen/src/cadgen/cli/step_build.py), which internally calls `_run_model` and routes the output to `gearbox.step` and `gearbox.glb`.

### Live Preview with the CAD Viewer

The integrated viewer watches model files for edits and updates the 3D viewport automatically:

```bash
cadgen viewer

```

The viewer implementation in [`packages/cadgen/src/cadgen/viewer/main.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadgen/src/cadgen/viewer/main.py) consumes snapshot files produced by `run_snapshot` in [`packages/cadgen/src/cadgen/snapshot_cli.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadgen/src/cadgen/snapshot_cli.py). When you modify parameter values in the source file while the viewer runs, the daemon detects the change and refreshes the scene within seconds.

## Advanced Parametric Workflows

Complex assemblies combine multiple primitives and conditional logic based on parameter values.

```python

# robot_chassis.py

from cadgen import Box, Cylinder, Union, Transform
from cadgen.param import Float, Choice

# Parameters

wheel_diameter: Float = Float(default=50, label="Wheel Diameter")
wheel_type: Choice = Choice(choices=["solid", "spoked"], default="solid")
chassis_length: Float = Float(default=200, min=100, max=400)

def wheel():
    base = Cylinder(radius=wheel_diameter / 2, height=10)
    if wheel_type == "spoked":
        # Create spoke geometry using Boolean operations

        spokes = Union(*[Box(size=(2, 30, 2)).translate((0, 0, 5)) for _ in range(6)])
        return base + spokes
    return base

def robot():
    chassis = Box(size=(chassis_length, 150, 20))
    left_wheel = wheel().translate((0, -80, 10))
    right_wheel = wheel().translate((0, 80, 10))
    return Union(chassis, left_wheel, right_wheel)

if __name__ == "__main__":
    robot()

```

This example demonstrates how `Choice` parameters alter geometry topology, not just dimensions. The `Union` operation in [`packages/cadgen/src/cadgen/generation.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadgen/src/cadgen/generation.py) handles the Boolean addition of the spokes to the wheel base.

## Summary

- **Parameter definition**: Use `Float`, `Int`, and `Choice` from `cadgen.param` to expose tunable variables that the system tracks.
- **Execution entry point**: The `_run_model` function in [`packages/cadgen/src/cadgen/cli/_run_model.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadgen/src/cadgen/cli/_run_model.py) processes Python scripts and triggers geometry builds.
- **Automatic regeneration**: The daemon in [`packages/cadgen/src/cadgen/daemon/server.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadgen/src/cadgen/daemon/server.py) monitors file changes and re-executes models when parameters update.
- **Export pipeline**: [`snapshot_cli.py`](https://github.com/earthtojake/text-to-cad/blob/main/snapshot_cli.py) serializes geometry to STEP, GLB, and URDF formats for manufacturing and visualization.
- **Live preview**: The viewer in [`packages/cadgen/src/cadgen/viewer/main.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadgen/src/cadgen/viewer/main.py) provides real-time feedback without manual export steps.

## Frequently Asked Questions

### How does text-to-cad differ from traditional OpenSCAD workflows?

While OpenSCAD uses a domain-specific language, text-to-cad leverages standard Python with the `cadgen` library, allowing import of scientific computing packages like NumPy and SciPy. The parameter system in `cadgen.param` provides typed metadata that OpenSCAD's variables lack, enabling automatic UI generation and validation constraints.

### Can I integrate text-to-cad models into existing Python engineering pipelines?

Yes. Since `cadgen` operates as a standard Python package, you can import model functions into larger applications. The geometry constructors in [`packages/cadgen/src/cadgen/generation.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadgen/src/cadgen/generation.py) return objects that support standard Python operations, allowing computational scripts to generate CAD artifacts programmatically without CLI invocation.

### What file formats does text-to-cad support for export?

The `run_snapshot` function in [`packages/cadgen/src/cadgen/snapshot_cli.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadgen/src/cadgen/snapshot_cli.py) generates STEP files for CAD interoperability, GLB for web viewers and game engines, and URDF for robotics simulation. You can trigger specific formats via CLI flags or receive all formats by default when running scripts directly.

### How does the live viewer handle large parametric assemblies?

The viewer in [`packages/cadgen/src/cadgen/viewer/main.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadgen/src/cadgen/viewer/main.py) loads snapshot files generated by the daemon process. For complex models, it performs incremental updates rather than full scene reloads, though performance depends on the polygon count of the generated STEP geometry. The system prioritizes parameter responsiveness over real-time rendering fidelity for manufacturing-grade models.