# How to Customize the Output of Text‑to‑CAD: A Complete Guide to STEP, STL, 3MF, and GLB Exports

> Customize text-to-CAD output using CLI flags for STEP, STL, 3MF, and GLB exports. Control tolerances and mesh side-cars for precise 3D model generation.

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

---

**To customize the output of text‑to‑CAD, pass CLI flags to the `scripts/step` launcher to control STEP generation and export mesh side‑cars (STL, 3MF, GLB) with specific tolerances.**

The text‑to‑CAD repository (`earthtojake/text-to-cad`) follows a **STEP‑first architecture** where the primary artifact is always a STEP (or STP) file. All secondary formats are derived from this core solid model. Customization happens entirely through command‑line arguments—no source code modifications are required unless you are creating a new generator.

## Understanding the STEP‑First Architecture

Text‑to‑CAD treats the STEP file as the single source of truth. The pipeline in `scripts/step` first generates or imports a STEP solid, then optionally produces **mesh side‑cars** (STL, 3MF, and native GLB) on demand. This design ensures geometric fidelity is preserved in the primary artifact while allowing flexible downstream conversions.

The entry point for all customization is `scripts/step`, which parses arguments in [`packages/cadpy/src/cadpy/generation.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadpy/src/cadpy/generation.py) (see the flag handling around lines 170‑190). From there, the script routes to either Python‑based generation or direct STEP import.

## Customizing Primary STEP Generation

### Working with Generated Python Sources

When creating new geometry, you author a build123d Python source that implements `def gen_step(): …`. The `scripts/step` launcher executes this function to produce the primary STEP file.

Place your generator files in the `models/` directory and invoke the script with your desired side‑car flags:

```bash
python scripts/step models/bracket.py \
  --stl meshes/bracket.stl \
  --3mf meshes/bracket.3mf \
  --glb meshes/bracket.glb

```

As implemented in `earthtojake/text-to-cad`, the launcher extracts the `gen_step()` function, executes it in a controlled environment, and writes the resulting solid to the specified STEP path before processing any mesh exports.

### Direct STEP Import Mode

You can also customize the output of an existing STEP file without regeneration. Use the `--kind part` flag to import an external STEP and convert it to specific mesh formats:

```bash
python scripts/step --kind part imports/external_part.step \
  --glb meshes/external_part.glb

```

This mode skips Python execution entirely and reads the STEP geometry directly into the tessellation pipeline.

## Exporting Mesh Side‑Cars (STL, 3MF, GLB)

### Basic Export Flags

The `scripts/step` CLI accepts explicit file paths for each supported mesh format. You can export any combination of side‑cars or none at all:

- **`--stl <path>`**: Export tessellated STL
- **`--3mf <path>`**: Export 3MF (3D Manufacturing Format)
- **`--glb <path>`**: Export native GLB (Binary glTF)

These flags are defined in [`skills/cad/references/supported-exports.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad/references/supported-exports.md) and parsed in [`packages/cadpy/src/cadpy/generation.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadpy/src/cadpy/generation.py). If you omit all three flags, the script produces only the primary STEP file.

### Controlling Mesh Density with Tolerance Flags

Mesh quality is controlled by two precision parameters that adjust the tessellation algorithm:

- **`--mesh-tolerance`**: Linear deflection (maximum distance between mesh and surface)
- **`--mesh-angular-tolerance`**: Angular deflection (maximum angle between adjacent mesh normals)

For small, highly‑curved parts requiring fine detail, reduce both values:

```bash
python scripts/step models/small_gear.py \
  --stl meshes/small_gear.stl \
  --glb meshes/small_gear.glb \
  --mesh-tolerance 0.1 \
  --mesh-angular-tolerance 0.1

```

Higher values produce lighter files with fewer triangles; lower values increase fidelity at the cost of file size and processing time.

## Validating and Visualizing Output

### Geometry Inspection with scripts/inspect

After generating your STEP file, validate geometric facts, plane orientations, and positioning using `scripts/inspect`. This step is critical before handing off to the CAD viewer:

```bash
python scripts/inspect refs models/bracket.step --facts --planes --positioning

```

The inspection script (referenced in [`skills/cad/SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad/SKILL.md)) performs automated checks against the solid model to ensure manufacturability and dimensional accuracy.

### Creating Visual Snapshots

Generate PNG or GIF visual proof of the primary STEP using `scripts/snapshot`. According to the repository workflow documented in [`SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/SKILL.md), snapshots are mandatory after any STEP change:

```bash
python scripts/snapshot models/bracket.step

```

These images serve as visual regression tests and documentation artifacts alongside the CAD files.

## CLI Implementation Details

The command‑line interface is implemented in [`packages/cadpy/src/cadpy/generation.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadpy/src/cadpy/generation.py), where output paths are resolved and validated. The script ensures that parent directories for side‑car files exist before tessellation begins, and it validates that the generated Python source contains the required `gen_step()` signature (documented in [`skills/cad/references/step-generation.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad/references/step-generation.md)).

After running `scripts/step`, `scripts/inspect`, and `scripts/snapshot`, you hand off the artifacts to the CAD viewer using the `$cad-viewer` protocol:

```text
$cad-viewer https://<viewer-host>?dir=/absolute/project/models&file=bracket.step
$cad-viewer https://<viewer-host>?dir=/absolute/project/models/meshes&file=bracket.stl

```

## Summary

- **Primary output** is always a STEP file generated or imported via `scripts/step`.
- **Mesh side‑cars** (STL, 3MF, GLB) are produced on demand using `--stl`, `--3mf`, and `--glb` flags.
- **Mesh density** is controlled by `--mesh-tolerance` and `--mesh-angular-tolerance` for fine‑tuning tessellation quality.
- **Validation** requires `scripts/inspect` for geometric checks and `scripts/snapshot` for visual proof.
- **All customization** occurs through CLI arguments parsed in [`packages/cadpy/src/cadpy/generation.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadpy/src/cadpy/generation.py) without modifying core library code.

## Frequently Asked Questions

### Can I customize the output of text‑to‑CAD without modifying Python source files?

Yes. If you have an existing STEP file, use the `--kind part` flag with `scripts/step` to import it directly and export specific mesh formats. This requires no Python coding—only CLI arguments to specify input and output paths.

### How do I reduce the file size of exported STL or GLB meshes?

Increase the `--mesh-tolerance` and `--mesh-angular-tolerance` values. Higher tolerances allow the tessellator to use larger triangles, reducing vertex count and file size. For example, `--mesh-tolerance 0.5` produces a coarser mesh than the default.

### What is the difference between the STEP file and the mesh side‑cars?

The STEP file is the **primary solid model** containing exact boundary representation (BREP) geometry. Mesh side‑cars (STL, 3MF, GLB) are tessellated approximations derived from the STEP for specific use cases like 3D printing or web viewing. Always treat the STEP as the authoritative source.

### Where are the CLI flags for mesh export defined and validated?

The flags are documented in [`skills/cad/references/supported-exports.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad/references/supported-exports.md) and implemented in [`packages/cadpy/src/cadpy/generation.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadpy/src/cadpy/generation.py) (lines 170‑190). This module handles path resolution, validation, and routing to the appropriate tessellation backends for each format.