# Understanding STEP-First CAD Workflow vs STL/3MF/GLB Export Strategies in text-to-cad

> Explore the STEP-first CAD workflow in text-to-cad, comparing its benefits over STL/3MF/GLB export strategies. Understand its canonical format and B-Rep data advantage.

- Repository: [earthtojake/text-to-cad](https://github.com/earthtojake/text-to-cad)
- Tags: deep-dive
- Published: 2026-08-03

---

**The text-to-cad repository treats STEP as its canonical CAD format, using it as the single source of truth for all geometry while generating STL, 3MF, and GLB files as optional side-car exports from the same B-Rep data.**

The **text-to-cad** open-source project implements a **STEP-first pipeline** that prioritizes precision CAD data over mesh approximations. This architecture ensures that every downstream format—whether for 3D printing, web visualization, or manufacturing—derives from the same exact geometric representation, eliminating the drift and quality loss that plague mesh-first workflows.

## Core Architecture of the STEP-First Pipeline

The repository's CAD system centers on three layers: command-line interface, generation orchestration, and format-specific exporters.

### CLI Entry Point and Options

The `scripts/step` CLI in [`skills/cad/scripts/step/cli.py`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad/scripts/step/cli.py) parses user arguments and constructs a `StepImportOptions` object. This configuration container specifies which side-car formats to produce and defines mesh tolerances for any triangulated outputs.

The `StepImportOptions` class (defined in [`packages/cadpy/src/cadpy/catalog.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadpy/src/cadpy/catalog.py)) captures:

- `stl` — output path for stereolithography mesh
- `three_mf` — output path for 3D Manufacturing Format
- `glb` — output path for glTF binary format
- `mesh_tolerance` — linear deflection for triangulation
- `mesh_angular_tolerance` — angular deflection in degrees

### Generation Engine Orchestration

The `generate_step_targets` function in [`packages/cadpy/src/cadpy/generation.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadpy/src/cadpy/generation.py) drives the entire workflow:

1. **Resolves targets** — handles Python generators ([`GENERATOR.py`](https://github.com/earthtojake/text-to-cad/blob/main/GENERATOR.py)), raw STEP files (`MODEL.step`), or explicit pairs (`GENERATOR.py=OUT.step`)
2. **Generates STEP geometry** — calls `gen_step()` on Python generators or loads existing STEP files
3. **Creates GLB topology artifact** — always produces a hidden GLB containing `STEP_topology` for CAD Viewer inspection
4. **Dispatches side-car jobs** — conditionally runs STL, 3MF, and native GLB exporters

This centralized orchestration guarantees that mesh exports never bypass the STEP representation.

## STEP Scene Loading and Export

### Loading B-Rep Data

The [`packages/cadpy/src/cadpy/step_scene.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadpy/src/cadpy/step_scene.py) module implements `load_step_scene()`, which uses OpenCascade to read STEP files into a `LoadedStepScene` object. This in-memory structure preserves:

- Exact B-Rep topology (faces, edges, vertices)
- Assembly hierarchy and metadata
- Unit specifications and coordinate systems

All mesh extraction operations consume this loaded scene, ensuring consistent triangulation parameters across formats.

### STEP File Output

For Python generator targets, [`packages/cadpy/src/cadpy/step_export.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadpy/src/cadpy/step_export.py) writes STEP files from XCAF documents. The `StepExporter` class handles schema compliance and geometric validation. The `--skip-step-write` flag allows bypassing this step for performance-critical scenarios while still generating viewer artifacts and side-cars.

## Mesh Export Strategies: STL, 3MF, and GLB

Each mesh format receives identical geometric input from the loaded STEP scene, producing predictable, comparable outputs.

### STL Export ([`packages/cadpy/src/cadpy/stl.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadpy/src/cadpy/stl.py))

The STL module provides two primary functions:

- `export_part_stl_from_scene()` — exports a complete part with metadata
- `export_shape_stl()` — lower-level shape-to-mesh conversion

Both respect the linear and angular tolerances specified in `StepImportOptions`.

### 3MF Export ([`packages/cadpy/src/cadpy/threemf.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadpy/src/cadpy/threemf.py))

The 3MF implementation targets manufacturing workflows, preserving color and material annotations when present in the source STEP data. This format is increasingly preferred over STL for modern 3D printing pipelines due to its compact size and richer metadata support.

### Native GLB Export ([`packages/cadpy/src/cadpy/glb.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadpy/src/cadpy/glb.py))

Distinct from the hidden topology GLB, the native GLB export in [`glb.py`](https://github.com/earthtojake/text-to-cad/blob/main/glb.py) produces render-ready assets with PBR materials and optimized mesh compression. This serves web-based visualization and game engine import without requiring CAD software.

## Command-Line and API Usage

### CLI: Full STEP-First Workflow

Generate a STEP file with STL and GLB side-cars using controlled mesh tolerances:

```bash
scripts/step \
    my_part_generator.py \
    --stl ./meshes/my_part.stl \
    --glb ./meshes/my_part.glb \
    --mesh-tolerance 0.05 \
    --mesh-angular-tolerance 5

```

### Python API: Programmatic Control

For pipeline integration, use the `generate_step_targets` function directly:

```python
from cadpy.generation import generate_step_targets
from cadpy.catalog import StepImportOptions

opts = StepImportOptions(
    stl="output.stl",
    glb="output.glb",
    mesh_tolerance=0.1,
    mesh_angular_tolerance=10,
)

generate_step_targets(
    targets=["my_generator.py"],
    direct_step_kind="part",
    step_options=opts,
    force=True,
    verbose=True,
)

```

### Direct Mesh Export: Bypassing STEP Persistence

For scenarios where STEP file I/O is unnecessary, extract meshes directly from loaded scenes:

```python
from cadpy.step_scene import load_step_scene
from cadpy.stl import export_shape_stl
from pathlib import Path

scene = load_step_scene("example.step")
export_shape_stl(scene.export_shape(), Path("example.stl"))

```

Note that this shortcut sacrifices the guarantees of the STEP-first pipeline—you lose automatic versioning, hash-based regeneration checks, and the hidden GLB topology artifact required for CAD Viewer functionality.

## Why STEP-First Matters

### Precision Preservation

STEP encodes exact boundary representation (B-Rep) geometry with analytic surfaces. STL, 3MF, and GLB are triangulated approximations that discard parametric definitions. By making STEP the primary artifact, text-to-cad ensures that any derivative mesh represents the same underlying geometry to within specified tolerances, not an independent export that may diverge.

### Viewer Integration

The hidden GLB topology artifact (`STEP_topology`) enables sophisticated CAD Viewer features:

- Edge classification and highlighting
- Surface type inspection (planar, cylindrical, conical, etc.)
- Assembly structure navigation
- Hidden-mesh query operations

These capabilities require access to the original B-Rep topology, which mesh formats cannot provide.

### Workflow Consistency

Hash-based up-to-date checking in `generate_step_targets` prevents redundant computation. The `--force` flag overrides this when regeneration is required. This caching layer operates on STEP content, ensuring that mesh side-cars are regenerated whenever the underlying geometry changes.

## Performance and Trade-offs

| Scenario | Recommended Approach | Key Flag |
|----------|-------------------|----------|
| Standard CAD workflow | Full STEP-first pipeline | *(none)* |
| Web preview only | STEP-first with GLB side-car, skip STEP write | `--skip-step-write` |
| Large assembly batch processing | Python API with shared `StepImportOptions` | `force=True` |
| Quick mesh extraction | Direct scene loading | *(manual API)* |

For large assemblies where STEP serialization dominates runtime, `--skip-step-write` eliminates disk I/O while preserving viewer functionality through the hidden GLB topology artifact.

## Summary

- **STEP is canonical** in text-to-cad—all geometry flows through `LoadedStepScene` from [`packages/cadpy/src/cadpy/step_scene.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadpy/src/cadpy/step_scene.py)
- **Mesh formats are side-cars** generated from the same B-Rep source via exporters in [`stl.py`](https://github.com/earthtojake/text-to-cad/blob/main/stl.py), [`threemf.py`](https://github.com/earthtojake/text-to-cad/blob/main/threemf.py), and [`glb.py`](https://github.com/earthtojake/text-to-cad/blob/main/glb.py)
- **The hidden GLB topology artifact** supports CAD Viewer features regardless of STEP persistence
- **`StepImportOptions`** in [`packages/cadpy/src/cadpy/catalog.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadpy/src/cadpy/catalog.py) centralizes export configuration
- **`generate_step_targets`** in [`packages/cadpy/src/cadpy/generation.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadpy/src/cadpy/generation.py) orchestrates the complete pipeline
- **Tolerances control mesh quality** through `mesh_tolerance` and `mesh_angular_tolerance` parameters

## Frequently Asked Questions

### What is the STEP-first workflow in text-to-cad?

The STEP-first workflow designates STEP as the primary CAD output format, with all mesh exports (STL, 3MF, GLB) generated as secondary side-car files from the same loaded STEP geometry. This architecture lives in [`packages/cadpy/src/cadpy/generation.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadpy/src/cadpy/generation.py), where `generate_step_targets` always produces or loads STEP data before creating any triangulated representations. The approach guarantees that every mesh format derives from identical B-Rep source data.

### How does text-to-cad handle STL, 3MF, and GLB exports?

Each mesh format has a dedicated exporter module that receives a `LoadedStepScene` object and writes triangulated geometry. STL exports via [`packages/cadpy/src/cadpy/stl.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadpy/src/cadpy/stl.py), 3MF via [`threemf.py`](https://github.com/earthtojake/text-to-cad/blob/main/threemf.py), and native GLB via [`glb.py`](https://github.com/earthtojake/text-to-cad/blob/main/glb.py). All three respect the `mesh_tolerance` and `mesh_angular_tolerance` parameters from `StepImportOptions`, ensuring consistent mesh density across formats. These exports are dispatched conditionally based on CLI flags or API configuration.

### What is the hidden GLB topology artifact?

The hidden GLB topology artifact is a special output generated in every STEP-first workflow, containing `STEP_topology` data for CAD Viewer integration. Unlike the render-ready GLB from [`glb.py`](https://github.com/earthtojake/text-to-cad/blob/main/glb.py), this artifact preserves edge and surface classification from the original B-Rep. It enables viewer features like edge highlighting and surface inspection without requiring a separate mesh export step. The artifact is produced regardless of whether the STEP file is persisted to disk.

### When should I use --skip-step-write?

Use `--skip-step-write` when you need viewer functionality and mesh side-cars but want to eliminate STEP file I/O overhead. Common scenarios include large assembly batch processing, rapid prototyping iterations, or web preview pipelines where the canonical STEP file isn't required downstream. This flag still generates the hidden GLB topology artifact and any requested mesh formats, maintaining CAD Viewer compatibility without the disk write penalty.