How to Validate CAD Geometry Using Scripts: A Complete Guide to text-to-cad's Validation Tools

The text-to-cad repository provides self-contained Python scripts that validate SDF, DXF, G-code, and GLB/STEP files through functions like validate_sdf_xml, validate_gcode_file, and validate_step_topology_artifact, returning structured ValidationResult objects suitable for CI pipelines and automated workflows.

The text-to-cad open-source project ships a comprehensive suite of geometry validation tools designed to verify CAD asset integrity programmatically. Whether you are processing robotic simulation files, 2D manufacturing blueprints, or 3D printing instructions, these scripts enable you to validate CAD geometry using scripts directly within Python applications or continuous integration environments.

Core Validation Architecture

All validators in the repository follow a consistent four-step architectural pattern. First, the source file or manifest is parsed and loaded. Second, a ValidationResult object is instantiated to collect errors, warnings, and informational messages. Third, the validator walks the data structure using focused helper functions that detect specific rule violations. Finally, the populated ValidationResult is returned, allowing callers to decide whether to abort or continue processing.

The repository organizes validators by CAD format:

• SDF validator — Located in plugins/cad/skills/sdf/scripts/sdf/validation.py, this parser checks SDF XML files for required elements, numeric values, mesh URIs, joint definitions, and reference cycles. The entry point validate_sdf_xml builds a ValidationResult and traverses the DOM tree using helpers like _validate_link and _validate_joint.

• DXF validator — Found in plugins/cad/skills/dxf/scripts/packages/cadpy/src/cadpy/validators.py, this inspector validates DXF manifests for geometric consistency, checking bounding-box coordinates, selector counts, and mesh presence through utilities such as assert_bbox_coordinate and geometry_summary_from_manifest.

• G-code validator — Implemented in plugins/cad/skills/gcode/scripts/gcode_tool.py, the validate_gcode_file function parses additive manufacturing instructions line-by-line, ensuring extrusion commands remain within printer build volumes, confirming positive feed rates, and checking for empty files.

• GLB/STEP validator — Provided in packages/cadpy/src/cadpy/step_targets.py, the validate_step_topology_artifact function confirms that generated GLB and STEP artifacts contain valid topological structures and that their bounding boxes match expected dimensions.

Validating SDF XML Files

The SDF validator processes XML-based robot and environment definitions used in simulation engines. Located in plugins/cad/skills/sdf/scripts/sdf/validation.py, the validate_sdf_xml function accepts XML content and a source path, returning a detailed ValidationResult.

from pathlib import Path
from plugins.cad.skills.sdf.scripts.sdf.validation import validate_sdf_xml, raise_for_validation_errors

xml_content = Path("robot.sdf").read_text()
result = validate_sdf_xml(xml_content, source_path=Path("robot.sdf"))

# Inspect specific issues

for warning in result.warnings:
    print(f"⚠️  {warning.code}: {warning.message}")

# Or raise immediately on any error or warning

raise_for_validation_errors(result, strict=True)

Validating DXF Geometry and Manifests

For 2D CAD workflows, the DXF validator provides utilities to inspect manifest JSON files. The geometry_summary_from_manifest function extracts bounding box and statistical data, while assert_bbox_coordinate enforces dimensional constraints with clear, typed error messages.

from plugins.cad.skills.dxf.scripts.packages.cadpy.src.cadpy.validators import (
    geometry_summary_from_manifest,
    assert_bbox_coordinate,
)

manifest = {
    "bbox": {"min": [-0.05, -0.05, 0.0], "max": [0.05, 0.05, 0.1]},
    "stats": {"shapeCount": 10, "faceCount": 120},
}

summary = geometry_summary_from_manifest(manifest)

# Validate specific bounding box constraints

assert_bbox_coordinate(summary["bbox"], "z", "max", 0.1)

Validating G-Code for 3D Printing

The G-code validator ensures manufacturing instructions are safe and feasible for specific printer profiles. The validate_gcode_file function raises GcodeValidationError when commands exceed build volumes or specify invalid feed rates.

from plugins.cad.skills.gcode.scripts.gcode_tool import validate_gcode_file

printer_profile = {"build_volume": [0.2, 0.2, 0.2]}
result = validate_gcode_file("print.gcode", printer_profile)

if not result.is_ok:
    print("Validation failed:", result.errors)
else:
    print("✅ G-code is valid and within build volume")

Validating STEP and GLB Topology

For 3D model exchange formats, the validator in packages/cadpy/src/cadpy/step_targets.py checks that artifacts contain valid topological structures. The validate_step_topology_artifact function verifies bounding box dimensions against expected specifications.

from cadpy.step_targets import validate_step_topology_artifact

# Validate a generated STEP file

result = validate_step_topology_artifact(
    file_path="model.step",
    expected_bbox={"min": [0, 0, 0], "max": [0.1, 0.1, 0.1]}
)

Command-Line Interface

Each validation skill includes CLI wrappers for shell integration. While exact command names follow the repository's skill naming conventions, typical usage patterns include:

# Validate SDF robot definition

python -m plugins.cad.skills.sdf.scripts.sdf.validation robot.sdf

# Validate DXF manifest

cad-viewer dxf validate --manifest model.json

# Validate G-code against printer profile

cad-viewer gcode validate --file print.gcode --profile ender3.json

Continuous Integration Integration

These validators integrate seamlessly into CI pipelines. The repository's test suites in tests/python/skills/sdf/test_validation.py and tests/python/skills/gcode/test_gcode_tool.py demonstrate automated validation patterns.

Example GitHub Actions workflow:

name: CAD Validation
on: [push, pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - run: pip install -r requirements.txt
      - name: Validate SDF files
        run: |
          python -c "
from pathlib import Path
from plugins.cad.skills.sdf.scripts.sdf.validation import validate_sdf_xml, raise_for_validation_errors
result = validate_sdf_xml(Path('robot.sdf').read_text(), source_path=Path('robot.sdf'))
raise_for_validation_errors(result, strict=True)
print('✅ All SDF files valid')
          "

Summary

• The text-to-cad repository provides specialized validators for SDF, DXF, G-code, and GLB/STEP formats, each implemented as self-contained Python modules with no cross-skill dependencies.
• All validators follow a consistent pattern: parse input, create a ValidationResult, walk the structure with helper functions, and return structured feedback containing errors, warnings, and infos.
• Key entry points include validate_sdf_xml in plugins/cad/skills/sdf/scripts/sdf/validation.py, validate_gcode_file in plugins/cad/skills/gcode/scripts/gcode_tool.py, and validate_step_topology_artifact in packages/cadpy/src/cadpy/step_targets.py.
• The raise_for_validation_errors utility enables strict mode validation that raises exceptions immediately upon detecting issues.
• These tools integrate directly into CI/CD pipelines to catch geometric errors before production deployment.

Frequently Asked Questions

What CAD formats does the text-to-cad validation suite support?

The validation suite supports SDF (XML simulation formats), DXF (2D CAD manifests), G-code (3D printing instructions), and GLB/STEP (3D model exchange formats). Each format has a dedicated validator module located in plugins/cad/skills/ or packages/cadpy/.

How do I run validation checks programmatically in Python?

Import the specific validator for your format and call its main validation function. For SDF files, use validate_sdf_xml from plugins.cad.skills.sdf.scripts.sdf.validation. For G-code, use validate_gcode_file from plugins.cad.skills.gcode.scripts.gcode_tool. Each returns a ValidationResult object containing lists of errors and warnings that you can inspect or pass to raise_for_validation_errors.

Can I use these validators in a CI/CD pipeline?

Yes. The validators are designed for automated testing and return exit codes suitable for CI systems. You can invoke them through Python scripts in GitHub Actions, GitLab CI, or similar platforms, as demonstrated in the repository's test files located in tests/python/skills/sdf/test_validation.py and tests/python/skills/gcode/test_gcode_tool.py.

What is the difference between strict and non-strict validation modes?

In strict mode (enabled by passing strict=True to raise_for_validation_errors), the validator raises exceptions immediately upon encountering any error or warning. Non-strict mode allows you to inspect the ValidationResult object manually and decide programmatically whether to proceed based on the severity of issues found.

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