# What Is the Role of the cadpy Package in text-to-cad?

> Discover the cadpy package role in text-to-cad: a core Python toolkit for STEP file parsing, GLB generation, and multi-part assembly. Transform text to 3D models.

- Repository: [earthtojake/text-to-cad](https://github.com/earthtojake/text-to-cad)
- Tags: internals
- Published: 2026-07-31

---

**The `cadpy` package functions as the core Python CAD toolkit within the text-to-cad ecosystem, providing STEP file parsing, GLB generation, multi-part assembly composition, and metadata tracking to transform textual specifications into production-ready geometric artifacts.**

Within the `earthtojake/text-to-cad` repository, the `cadpy` package serves as the foundational layer for all computer-aided design operations. This self-contained library isolates CAD processing logic from higher-level skill implementations, ensuring consistent geometry handling across the pipeline. Understanding the role of the cadpy package in text-to-cad is essential for developers extending the system's modeling capabilities or integrating new export formats.

## Core CAD Processing Capabilities

The `cadpy` package delivers a dependency-light, pure-Python interface for CAD manipulation. Beyond STEP and GLB handling, it provides thin wrappers for **3MF**, **STL**, and other mesh formats while maintaining a lightweight footprint free of heavy external CAD kernels. It handles the entire lifecycle of geometric data from ingestion to final export.

### STEP File Parsing and Geometry Extraction

At the heart of `cadpy` lies the ability to read and interpret **STEP files** (ISO 10303), the industry standard for CAD data exchange. The `load_step()` function in [`packages/cadpy/src/cadpy/api.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadpy/src/cadpy/api.py) ingests STEP archives and extracts topology, geometry, and metadata into native Python objects. This capability enables downstream agents to analyze model structure without relying on heavy external CAD kernels.

### GLB Generation and Web Viewer Export

To support web-based visualization, `cadpy` converts STEP geometry into **GLB (glTF Binary)** format. The `export_glb()` method and the low-level `glb_from_step()` function in [`packages/cadpy/src/cadpy/glb.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadpy/src/cadpy/glb.py) handle mesh optimization and binary serialization. This ensures that models produced by the text-to-cad pipeline render efficiently in the viewer component, bridging the gap between engineering data and web graphics.

### Multi-Part Assembly Management

Complex mechanical designs require compositional logic. The `Assembly` class in [`packages/cadpy/src/cadpy/assembly.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadpy/src/cadpy/assembly.py) provides utilities for combining multiple STEP parts into coherent scenes. It supports **URDF and SRDF** joint definitions, allowing agents to specify parent-child relationships and kinematic chains. The `assemble()` workflow logically groups components while maintaining individual part identities for downstream manufacturing steps.

### Metadata Provenance and Change Tracking

Reproducibility demands rigorous data lineage. The `generate_metadata()` function in [`packages/cadpy/src/cadpy/metadata.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadpy/src/cadpy/metadata.py) computes cryptographic hashes, timestamps, and source provenance for every model. This metadata layer enables change-tracking across iterations and ensures that generated artifacts carry embedded documentation about their origin and transformation history.

## Key Source Files in the cadpy Architecture

The package structure under `packages/cadpy/src/cadpy/` organizes functionality into discrete, single-responsibility modules. The package is deliberately **independent of other skill code** and is vendored into runtime bundles for the viewer and plugin components, ensuring a single source of truth for CAD processing across the repository.

- **[`api.py`](https://github.com/earthtojake/text-to-cad/blob/main/api.py)** ([`packages/cadpy/src/cadpy/api.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadpy/src/cadpy/api.py)): Exposes the high-level façade including `load_step()`, `export_glb()`, and `assemble()` for skill script consumption.

- **[`step_export.py`](https://github.com/earthtojake/text-to-cad/blob/main/step_export.py)** ([`packages/cadpy/src/cadpy/step_export.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadpy/src/cadpy/step_export.py)): Contains logic for transforming STEP geometry into intermediate mesh formats and preparing data for GLB serialization.

- **[`glb.py`](https://github.com/earthtojake/text-to-cad/blob/main/glb.py)** ([`packages/cadpy/src/cadpy/glb.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadpy/src/cadpy/glb.py)): Implements low-level GLB construction, binary buffer management, and topology optimization for web delivery.

- **[`assembly.py`](https://github.com/earthtojake/text-to-cad/blob/main/assembly.py)** ([`packages/cadpy/src/cadpy/assembly.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadpy/src/cadpy/assembly.py)): Defines the `Assembly` class and joint definition utilities for multi-part model composition.

- **[`metadata.py`](https://github.com/earthtojake/text-to-cad/blob/main/metadata.py)** ([`packages/cadpy/src/cadpy/metadata.py`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadpy/src/cadpy/metadata.py)): Provides hashing algorithms, UUID generation, and provenance reporting structures.

- **[`README.md`](https://github.com/earthtojake/text-to-cad/blob/main/README.md)** ([`packages/cadpy/README.md`](https://github.com/earthtojake/text-to-cad/blob/main/packages/cadpy/README.md)): Documents installation procedures, design goals, and package boundaries for contributors.

## Working with cadpy: Practical Examples

The following patterns demonstrate how skills and agents interact with `cadpy` to process CAD data.

### Loading and Inspecting STEP Metadata

```python
from cadpy.api import load_step

step_model = load_step("models/example_robot/robot.step")
print(step_model.metadata)          # → dictionary with author, UUID, timestamps

print(step_model.topology)          # → topology object for further queries

```

This snippet utilizes `load_step()` to ingest a robot model and access its metadata dictionary, providing immediate visibility into file provenance.

### Composing Multi-Part Assemblies

```python
from cadpy.assembly import Assembly
from cadpy.api import load_step

assembly = Assembly()
assembly.add_part(load_step("models/arm/shoulder.step"))
assembly.add_part(load_step("models/arm/elbow.step"))
assembly.define_joint("shoulder_elbow", parent="shoulder", child="elbow")
assembly.export_glb("output/robot.glb")   # produces a GLB ready for the viewer

```

Here, the `Assembly` class aggregates individual STEP components and defines kinematic relationships before exporting a unified GLB file.

### Generating GLB with Embedded Metadata

```python
from cadpy.glb import glb_from_step
from cadpy.metadata import generate_metadata

metadata = generate_metadata(source_path="models/wheel.step")
glb_bytes = glb_from_step("models/wheel.step", metadata=metadata)

with open("wheel.glb", "wb") as f:
    f.write(glb_bytes)

```

This example demonstrates the `generate_metadata()` and `glb_from_step()` pipeline, ensuring the output binary carries complete provenance information.

## Summary

- The `cadpy` package provides the foundational CAD processing layer for the `earthtojake/text-to-cad` repository, isolating geometry operations from skill logic.
- It handles **STEP file parsing**, **GLB export**, **multi-part assembly**, and **metadata tracking** through a pure-Python API.
- Key entry points include `load_step()` for ingestion, the `Assembly` class for composition, and `export_glb()` for web-ready output.
- Source files are organized under `packages/cadpy/src/cadpy/`, with [`api.py`](https://github.com/earthtojake/text-to-cad/blob/main/api.py), [`assembly.py`](https://github.com/earthtojake/text-to-cad/blob/main/assembly.py), [`glb.py`](https://github.com/earthtojake/text-to-cad/blob/main/glb.py), and [`metadata.py`](https://github.com/earthtojake/text-to-cad/blob/main/metadata.py) serving as the primary modules.
- The package is designed to be vendored into runtime bundles, ensuring consistent CAD capabilities across the viewer and plugin components.

## Frequently Asked Questions

### What is the primary function of cadpy in the text-to-cad pipeline?

The `cadpy` package functions as the geometric processing engine, converting raw STEP data and textual specifications into structured, exportable 3D assets. It abstracts file I/O, mesh conversion, and assembly logic into a unified toolkit that higher-level agents invoke to generate physical designs.

### How does cadpy convert STEP files to GLB format?

Conversion occurs through a two-stage process: [`step_export.py`](https://github.com/earthtojake/text-to-cad/blob/main/step_export.py) first translates STEP topology into intermediate mesh representations, then [`glb.py`](https://github.com/earthtojake/text-to-cad/blob/main/glb.py) serializes these meshes into binary GLB buffers using the `glb_from_step()` function. This pipeline preserves geometric fidelity while optimizing for web-viewer performance.

### Can cadpy operate independently from the larger text-to-cad system?

Yes. `cadpy` is intentionally designed as a self-contained, dependency-light package. While it serves as the CAD backbone for the `earthtojake/text-to-cad` repository, its modular structure and pure-Python implementation allow it to function as a standalone library for STEP processing and GLB generation in other projects.

### What types of metadata does cadpy generate for CAD models?

The [`metadata.py`](https://github.com/earthtojake/text-to-cad/blob/main/metadata.py) module generates cryptographic hashes, UUIDs, timestamps, and source file provenance. This metadata attaches to both intermediate Python objects and final exported files (such as GLB), enabling complete traceability from natural language prompt through to generated geometry.