Can Text-to-CAD Generate Complex Geometries? A Technical Analysis of the STEP-First Pipeline

Yes. The earthtojake/text-to-cad repository implements a STEP-first, parametric pipeline capable of generating arbitrarily complex 3D parts and assemblies including gear trains, impellers, and multi-component enclosures.

Unlike simple mesh generators, this system produces manufacturing-ready CAD data through a sophisticated workflow defined in skills/cad/SKILL.md. The architecture converts build123d Python source into validated STEP artifacts while preserving parametric relationships and assembly hierarchies required for professional mechanical engineering.

The STEP-First Architecture for Complex Geometry

The repository’s core innovation is its STEP-first workflow. Rather than generating polygons directly, the pipeline creates a precise boundary representation (B-rep) model first, then derives secondary meshes for visualization or 3D printing.

According to the source code in packages/cadpy/src/cadpy/generation.py, the generate_step_targets function orchestrates the entire process. This engine parses Python source files containing build123d primitives, constructs a LoadedStepScene object, applies mesh-resolution heuristics, and writes a validated STEP file alongside optional STL, 3MF, or GLB exports.

Core Generation Pipeline

From build123d Source to Validated STEP

The generation entry point lives in packages/cadpy/src/cadpy/generation.py. When you execute the CLI command python scripts/step <file.py>, the system imports your Python module and calls the gen_step() function you define.

Create a file named gen_part.py:

from build123d import Cube, Cylinder, Part

def gen_step():
    # Create a basic rectangular block with a hole

    part = Part()
    part += Cube(100, 60, 20)
    part -= Cylinder(8, 20, align=("center", "center", "bottom"))
    return part

Execute the generator:

python scripts/step gen_part.py

The CLI implementation in skills/cad/scripts/step/cli.py handles argument parsing and invokes generate_step_targets, which validates the geometry and emits gen_part.step plus default mesh sidecars.

Building Multi-Part Assemblies

The AssemblyHelper API

For complex geometries requiring multiple components, the repository provides the AssemblyHelper class in packages/cadpy/src/cadpy/assembly.py. This API allows you to declare joints, datums, and hierarchical transforms directly in Python, automatically translating them into a single STEP assembly with proper structure.

Create an assembly file:

# assembly.py

from build123d import Cylinder, Cube, AssemblyHelper

def gen_step():
    # Create two parts

    base = Cube(120, 120, 10)
    motor = Cylinder(30, 40)

    # Assemble them with a named datum

    assembly = AssemblyHelper("gearbox")
    assembly.add(base, name="base")
    assembly.add(motor, name="motor", location=("0,0,10"))  # place on top

    return assembly

Run with the assembly flag:

python scripts/step assembly.py --kind assembly

This produces a single STEP assembly encoding the placement relationships defined by AssemblyHelper, suitable for import into SolidWorks, Fusion 360, or other professional CAD tools.

Secondary Mesh Exports and Tolerance Control

STL, 3MF, and GLB Generation

The pipeline supports manufacturing and visualization workflows through controlled mesh tessellation. In skills/cad/scripts/step/cli.py, the CLI accepts flags for secondary exports that are forwarded to StepImportOptions in the generation engine.

Generate a part with specific mesh tolerances:

python scripts/step gen_part.py --stl part.stl --glb part.glb --mesh-tolerance 0.01

The --mesh-tolerance parameter controls the tessellation resolution passed to the mesh exporters (cadpy.stl, cadpy.threemf, cadpy.glb), ensuring you can optimize for either visualization quality or file size depending on your use case.

Validation and Snapshotting

After generation, you can inspect the resulting STEP file using built-in utilities:

python scripts/inspect refs gen_part.step --facts --planes
python scripts/snapshot gen_part.step

These commands run inspection utilities and generate PNG/GIF snapshots as required by the CAD skill’s "mandatory snapshot" policy defined in skills/cad/SKILL.md.

Real-World Complexity: Benchmark Examples

The repository’s benchmark suite demonstrates the pipeline’s capacity for industrial-grade complexity. The file benchmarks/10-planetary-gear-stage.md documents a complete multi-gear assembly with interlocking teeth and precise gear ratios, while benchmarks/08-centrifugal-impeller.md showcases a complex curved-blade impeller with organic surfaces that would be impossible to model with simple primitive stacking.

These examples utilize the same generate_step_targets pipeline and AssemblyHelper APIs described above, proving that text-to-cad can handle sophisticated mechanical geometries including:

• Gear trains with involute tooth profiles
• Turbomachinery with complex swept surfaces
• Multi-part enclosures with snap-fit joints and mounting bosses

Summary

• STEP-first architecture ensures geometric precision and interoperability with professional CAD systems
• generate_step_targets in packages/cadpy/src/cadpy/generation.py drives the core validation and export pipeline
• AssemblyHelper in packages/cadpy/src/cadpy/assembly.py enables hierarchical assembly definition with proper datum placement
• Secondary exporters support STL, 3MF, and GLB formats with configurable mesh tolerance
• Benchmark demonstrations include planetary gear stages and centrifugal impellers proving complex geometry capability

Frequently Asked Questions

What types of complex geometries can text-to-cad generate?

According to the earthtojake/text-to-cad source code, the system can produce arbitrarily complex 3D parts and assemblies including gear trains, impellers, and multi-part enclosures. The benchmarks directory contains working examples such as a planetary gear stage and a centrifugal impeller that demonstrate the pipeline's capability to handle sophisticated curved surfaces and mechanical assemblies.

How does text-to-cad manage assembly relationships between components?

The repository uses the AssemblyHelper class defined in packages/cadpy/src/cadpy/assembly.py to declare joints, datums, and hierarchical transforms directly in Python source code. This API automatically translates high-level placement relationships into a single validated STEP assembly file that preserves the structural hierarchy of the design.

What export formats are supported besides STEP?

The generation pipeline in packages/cadpy/src/cadpy/generation.py supports secondary mesh exports including STL, 3MF, and GLB formats through the StepImportOptions configuration. You can specify these outputs using command-line flags in skills/cad/scripts/step/cli.py such as --stl, --glb, and control tessellation quality with --mesh-tolerance.

How does the system ensure geometric validity of generated models?

The generate_step_targets function in packages/cadpy/src/cadpy/generation.py drives a validation pipeline that parses the build123d source, constructs a LoadedStepScene, and applies mesh-resolution heuristics before writing the final STEP artifact. This process ensures that generated geometries are manifold and compliant with STEP standards before secondary mesh exports are created.

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