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

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, 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, which exposes high-level primitives like Box, Cylinder, and Extrude. When execution completes, 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 file defines Float, Int, and Choice classes. These objects specify default values, valid ranges, and human-readable labels:

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, 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.

# 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 and execute it directly:

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:

cadgen step build models/gearbox.py

This command invokes the logic in 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:

cadgen viewer

The viewer implementation in packages/cadgen/src/cadgen/viewer/main.py consumes snapshot files produced by run_snapshot in 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.

# 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 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 processes Python scripts and triggers geometry builds.
• Automatic regeneration: The daemon in packages/cadgen/src/cadgen/daemon/server.py monitors file changes and re-executes models when parameters update.
• Export pipeline: 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 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 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 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 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.

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