Validating CAD Geometry: Facts, Planes, Measurements, and Alignment Checks in Text-to-CAD

The text-to-cad repository implements a deterministic three-layer validation pipeline—inspection, snapshot review, and repair loops—to verify CAD geometry through programmatic fact extraction, plane analysis, and read-only alignment checks.

The CAD skill in earthtojake/text-to-cad transforms natural-language requests into STEP-first geometry, then enforces rigorous validation before any model leaves the pipeline. This article explains how the repository validates CAD geometry facts, planes, measurements, and alignment checks using a reproducible, code-driven workflow.

The Three-Layer Validation Architecture

The validation sequence is explicitly defined in skills/cad/SKILL.md and splits into three logical layers that execute in order. Each layer addresses a distinct failure mode: programmatic correctness, visual plausibility, and source traceability.

Layer 1: Inspection and Validation

After STEP generation or import, the scripts/inspect CLI performs deterministic geometric analysis. According to the CAD skill's required workflow, this step runs with three critical flags:

python scripts/inspect refs my-part.step --facts --planes --positioning

Each flag activates a specific validation dimension:

• Facts – Extracts scalar geometric properties: volume, bounding box dimensions, and surface area. These values become assertions in your CAD brief (e.g., "volume must equal 1250 mm³").
• Planes – Identifies the principal XY, YZ, and ZX planes of the model. This enables planar queries such as checking whether a face is parallel to the XY plane or measuring perpendicular distances from datum planes.
• Positioning – Runs read-only alignment validation between selector-pair references without mutating the model.

The inspection logic is detailed in skills/cad/references/inspection-and-validation.md, which defines selector syntax (#o1.2.f1 for object 1, part 2, face 1) and measurement semantics.

Layer 2: Snapshot Review

Visual validation is mandatory. The scripts/snapshot CLI generates PNG or GIF images of the primary STEP artifact:

python scripts/snapshot my-part.step

As documented in skills/cad/references/snapshot-review.md, this step catches anomalies that deterministic checks miss—intersecting faces, unexpected voids, or orientation errors. The snapshot must attach to the final response and serves as a human-readable audit trail.

Layer 3: Repair Loop

When facts, planes, or alignment checks fail, the pipeline enforces source-code correction. Per skills/cad/references/repair-loop.md, developers edit the build123d Python generator rather than the generated STEP file, then re-run the full validation sequence. This guarantees traceability: every validation failure maps to a single source change.

Alignment Checks with Selector References

Positioning validation uses datum conventions defined in skills/cad/references/positioning.md. The inspect align subcommand computes translation deltas between two selector references:

python scripts/inspect align my-assembly.step #o1.2 #o2.1

This read-only operation validates relative positioning—critical for assemblies—without modifying geometry. The output reports translation deltas that can be asserted against design specifications.

Complete End-to-End Workflow

The CAD skill's required workflow (see skills/cad/SKILL.md#L70-L71) sequences seven explicit steps:

Step	Action	Command/Artifact
1	Classify request type	Natural language parsing
2	Load relevant references	inspection-and-validation.md, positioning.md
3	Write CAD brief	Dimensions, units, validation targets
4	Generate STEP, run inspection	python scripts/inspect refs --facts --planes --positioning
5	Visual confirmation	python scripts/snapshot
6	Repair and re-run if failed	Edit build123d source, repeat 4–5
7	Hand off to CAD Viewer	$cad-viewer with final STEP/STL/3MF/GLB

All commands execute through the repository's Python interpreter. Full CLI documentation is available via --help:

python scripts/inspect --help
python scripts/snapshot --help

Key Implementation Files

File Path	Validation Role
skills/cad/SKILL.md	Central workflow definition and required flags
skills/cad/references/inspection-and-validation.md	Facts, planes, measurements, selector syntax
skills/cad/references/positioning.md	Datum conventions, alignment CLI, positioning semantics
skills/cad/references/snapshot-review.md	PNG/GIF policy and visual-to-deterministic conversion
skills/cad/references/repair-loop.md	Source-code correction protocol
skills/cad/scripts/inspect	CLI entry for facts, planes, and alignment checks
skills/cad/scripts/snapshot	CLI entry for visual snapshot generation

Summary

• Three-layer validation ensures programmatic correctness (facts, planes, positioning), visual plausibility (snapshots), and source traceability (repair loops).
• Read-only alignment checks use selector references (#o1.2.f1) to validate assembly positioning without geometry mutation.
• Source-code repair mandates editing build123d generators rather than STEP files, maintaining deterministic reproducibility.
• CLI tools (scripts/inspect, scripts/snapshot) integrate into a seven-step workflow defined in skills/cad/SKILL.md.

Frequently Asked Questions

What geometric properties does the facts flag extract?

Facts extract scalar properties from STEP geometry: volume, bounding box dimensions (min/max X, Y, Z), and surface area. These values enable quantitative assertions in CAD briefs and automated pass/fail validation.

How do planar queries work in the validation pipeline?

The planes flag identifies the principal XY, YZ, and ZX planes of each model. These datums enable queries like "is face #o1.2.f1 parallel to the XY plane?" or "what is the perpendicular distance from point #o1.1.v3 to the YZ plane?"—essential for dimensional validation.

Why is snapshot review mandatory when deterministic checks exist?

Visual artifacts—intersecting faces, unexpected voids, orientation mirroring—often evade programmatic detection. The snapshot requirement in skills/cad/references/snapshot-review.md guarantees human-readable verification and creates audit artifacts for downstream review.

What happens when alignment checks fail between assembly components?

Per skills/cad/references/repair-loop.md, developers edit the build123d source code that generated the assembly, adjust positioning parameters, and re-run the full validation pipeline. The STEP file itself is never hand-edited, ensuring all changes are version-controlled and reproducible.

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