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

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

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:

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 and parsed in 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:

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:

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

The inspection script (referenced in 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, snapshots are mandatory after any STEP change:

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

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

$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 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 and implemented in 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.

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