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

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 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) 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 drives the entire workflow:

1. Resolves targets — handles Python generators (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 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 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)

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)

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)

Distinct from the hidden topology GLB, the native GLB export in 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:

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:

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:

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
• Mesh formats are side-cars generated from the same B-Rep source via exporters in stl.py, threemf.py, and glb.py
• The hidden GLB topology artifact supports CAD Viewer features regardless of STEP persistence
• StepImportOptions in packages/cadpy/src/cadpy/catalog.py centralizes export configuration
• generate_step_targets in 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, 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, 3MF via threemf.py, and native GLB via 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, 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.

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