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

> Validate CAD geometry with Text-to-CAD. Learn about facts, planes, measurements, and alignment checks in our deterministic three-layer pipeline.

- Repository: [earthtojake/text-to-cad](https://github.com/earthtojake/text-to-cad)
- Tags: how-to-guide
- Published: 2026-08-03

---

**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](https://github.com/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`](https://github.com/earthtojake/text-to-cad/blob/main/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:

```bash
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`](https://github.com/earthtojake/text-to-cad/blob/main/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:

```bash
python scripts/snapshot my-part.step

```

As documented in [`skills/cad/references/snapshot-review.md`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad/references/positioning.md). The `inspect align` subcommand computes translation deltas between two selector references:

```bash
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`](https://github.com/earthtojake/text-to-cad/blob/main/inspection-and-validation.md), [`positioning.md`](https://github.com/earthtojake/text-to-cad/blob/main/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`:

```bash
python scripts/inspect --help
python scripts/snapshot --help

```

## Key Implementation Files

| File Path | Validation Role |
|:---|:---|
| [`skills/cad/SKILL.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad/SKILL.md) | Central workflow definition and required flags |
| [`skills/cad/references/inspection-and-validation.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad/references/inspection-and-validation.md) | Facts, planes, measurements, selector syntax |
| [`skills/cad/references/positioning.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad/references/positioning.md) | Datum conventions, alignment CLI, positioning semantics |
| [`skills/cad/references/snapshot-review.md`](https://github.com/earthtojake/text-to-cad/blob/main/skills/cad/references/snapshot-review.md) | PNG/GIF policy and visual-to-deterministic conversion |
| [`skills/cad/references/repair-loop.md`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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.