How to Generate STEP Files from build123d Python Source Using the CAD Skill

The CAD skill in the earthtojake/text-to-cad repository provides a command-line interface that converts Python scripts containing CAD geometry definitions into standard STEP files by executing a build() function and leveraging Open CASCADE technology.

This workflow allows you to programmatically generate STEP files from build123d Python source code using the open-source CAD skill. The earthtojake/text-to-cad project automates the bridge between parametric Python modeling and industry-standard geometry exchange formats used in manufacturing and mechanical design.

Structure Your build123d Python Source

The CAD skill expects your Python source file to expose a callable build() function that returns a scene object. This function serves as the entry point for constructing your geometry using the cadpy API.

Create a Python file (e.g., models/part/build123d.py) that defines the build() function returning a LoadedStepScene:

# models/part/build123d.py

from cadpy import AssemblySpec, LoadedStepScene, make_box

def build() -> LoadedStepScene:
    """Construct the CAD model and return a scene wrapper."""
    box = make_box(width=10, depth=20, height=5)
    return LoadedStepScene(step_path=None, root=box)

The build() function must require no arguments and return an object that can be converted to a cadpy.scene.LoadedStepScene.

Run the STEP Generation CLI

The skill provides a thin wrapper script at skills/cad/scripts/step/cli.py that handles the conversion process. Invoke the module using Python's -m flag from the repository root:

python -m skills.cad.scripts.step.cli \
    --module models/part/build123d.py \
    --output models/part/part.step

The CLI accepts two primary arguments:

• --module: The file system path (or dotted import path) to your Python source file that contains the build() function.
• --output: The destination path for the generated STEP file. If omitted, the CLI creates a STEP file with the same stem as the source in the same directory.

How the CLI Generates STEP Files Internally

According to the earthtojake/text-to-cad source code, the CLI performs three distinct operations to transform your Python script into a STEP file:

Dynamic Module Loading

The CLI uses importlib.util.spec_from_file_location to dynamically load your source file as a Python module. It constructs the module specification and creates a module object via importlib.util.module_from_spec, then executes the module to make the build() function available in the runtime namespace.

Scene Construction

Once loaded, the CLI invokes your module's build() function, which must return a cadpy.scene.LoadedStepScene. This scene object encapsulates the geometry hierarchy and metadata required for export.

Open CASCADE Export

The scene is passed to cadpy.step_export.export_step_from_source (which internally calls export_step_from_scene), located in packages/cadpy/src/cadpy/step_export.py. This function utilizes the Open CASCADE geometry kernel to write the standardized STEP file format to disk.

Complete Working Example

Here is a full workflow demonstrating the generation process:

# models/example/build123d.py

from cadpy import LoadedStepScene, make_box

def build() -> LoadedStepScene:
    """Define a simple parametric box."""
    geometry = make_box(width=50, depth=30, height=10)
    return LoadedStepScene(step_path=None, root=geometry)

Execute the conversion:

python -m skills.cad.scripts.step.cli \
    --module models/example/build123d.py \
    --output models/example/output.step

Verify the result programmatically:

import pathlib

step_file = pathlib.Path("models/example/output.step")
assert step_file.exists()
print(f"STEP file generated: {step_file.stat().st_size} bytes")

Summary

• The CAD skill CLI entry point at skills/cad/scripts/step/cli.py converts Python scripts to STEP files.
• User scripts must expose a build() function that returns a LoadedStepScene from cadpy.scene.
• The CLI uses importlib for dynamic loading and supports both file paths and dotted module names.
• Core export logic resides in packages/cadpy/src/cadpy/step_export.py and relies on Open CASCADE technology.
• The resulting STEP files are compatible with standard CAD viewers and downstream manufacturing tools.

Frequently Asked Questions

What function must my build123d script include to work with the CLI?

Your Python source file must define a public build() function that takes no arguments and returns a cadpy.scene.LoadedStepScene object. The CLI dynamically imports your module and executes this function to retrieve the geometry before exporting to STEP format.

Can I use a dotted Python import path instead of a file path for the --module argument?

Yes, the --module parameter accepts both file system paths (e.g., models/part/build123d.py) and import-style dotted paths (e.g., models.part.build123d). The CLI handles both formats using importlib utilities to locate and load the source code.

Which underlying library handles the actual STEP file writing?

The export process relies on Open CASCADE technology through the cadpy package. Specifically, the function export_step_from_scene in packages/cadpy/src/cadpy/step_export.py manages the conversion from the internal scene representation to the standardized STEP format.

Where is the CLI entry point defined in the repository?

The command-line interface is implemented in skills/cad/scripts/step/cli.py. This script serves as the thin wrapper that orchestrates module loading, scene building, and the final export to STEP using the underlying cadpy infrastructure.

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