Text-to-CAD: parametric source, geometry evidence and responsible handoff
Text-to-CAD quickstart: a parameterized sample block with an honest validation plan
Read a small cadgen model, understand when it builds and verify the resulting document without confusing import, generation and snapshotting.
What you will learn
- Write a brief you can check
- Calling builds; importing does not build the model
- Review the artifact actually produced
Before you start
- Basic Python functions, modules and file paths
- Understanding of units and the difference between a design and a physical part
Plan a bounded CAD exercise and distinguish source freshness, document inspection, visual review and manufacturing decisions.
Key takeaways
- The model body returns a shape, not a filename or dictionary.
- Calling the decorated model differs from importing it.
- Measure and snapshot the generated document itself.
Write a brief you can check
Choose a nonfunctional sample block with width 36 mm, depth 24 mm and height 4 mm. These are teaching dimensions, not recommended manufacturing tolerances. Record the expected bounding extents and positive volume, and exclude holes, assemblies and machine operation from the first exercise.
The model below follows the inspected contract: a parameterless decorated function returns a build123d shape and is called under the main guard. Parameters remain named constants. For reusable variants, put geometry in an ordinary factory and call it from separately identified models.
Calling builds; importing does not build the model
The guide states that the decorator declares outputs and calling the model builds them. Running sample.py should produce its declared sample.step; merely importing the model module does not invoke the build. Do not pass the Python script to a STEP inspection or snapshot command expecting it to generate geometry.
Inspect the generated STEP as a document. Begin with refs for facts and selectors, then validate for geometry soundness, and use targeted measurements for the brief’s dimensions. Reference resolution being okay does not establish a closed, correctly oriented positive-volume solid.
Review the artifact actually produced
After a successful build, snapshot the STEP and inspect the image for orientation, missing material and unexpected features. Keep the exact file path and validation results together. A missing or failed snapshot should remain a visible limitation rather than being replaced with an old attractive image.
This is a runnable-pattern example for an appropriately installed environment, not a claim that we built the block. Our executed tests cover only the lazy-import proxy with a fake dependency. No STEP, mesh or printer file was generated by this article’s authoring process.
Decision guide
| Criterion | Option A | Option B |
|---|---|---|
| Best when | You need predictable behavior and easy auditing | You need adaptive optimization and have reliable telemetry |
| Main risk | May leave performance on the table | Can become difficult to explain or debug |
Implementation steps
- 1
Write dimensions and explicit non-goals.
- 2
Save the model in a new practice directory.
- 3
Build it in the matching installed environment.
- 4
Validate, measure and review the exact output.
Copy-ready example
from cadgen import build123d as bd
from cadgen import step
WIDTH, DEPTH, HEIGHT = 36.0, 24.0, 4.0
@step
def sample():
return bd.Box(WIDTH, DEPTH, HEIGHT)
if __name__ == "__main__":
sample()Frequently asked questions
Why did importing sample.py not create a STEP file?
The documented build occurs when the decorated model is called, normally from its main guard.
Was this CAD example executed here?
No. It is based on the pinned model contract; only the separate proxy fixture ran.
Sources
- Text-to-CAD / skills/cad/SKILL.mdSource checked 2026-09-14