SDF Skill Use Cases in text-to-cad: Validation, Rendering, and Viewer Integration

The SDF Skill provides a dedicated entry point for authoring and validating SDFormat files through three core capabilities: validation against schema and semantics, snapshot rendering for visual feedback, and seamless handoff to the CAD Viewer for collaborative review.

The SDF Skill in the earthtojake/text-to-cad repository streamlines the creation and verification of SDFormat (.sdf) files used by simulators like Gazebo. Defined in skills/sdf/SKILL.md, this skill leverages the cadgen distribution to handle XML-based robot and world descriptions without binding to specific simulator versions. Its architecture delegates heavy processing to lightweight Python validators and a shared JavaScript headless-browser renderer, enabling a complete authoring workflow from initial edit to final visual confirmation.

Core Capabilities of the SDF Skill

The skill exposes three primary functions that support distinct stages of the simulation asset lifecycle.

Validation and Quality Gates

The validation capability runs the cadgen sdf validate command to check document structure, name scopes, pose/frame graphs, joints, geometry, mesh URIs, inertials, sensors, and plugins. As implemented in packages/cadgen/src/cadgen/cli/sdf_validate.py, this performs lightweight static analysis before expensive simulator loading. Use this after editing any model-level or world-level SDF file to catch structural errors early, or integrate it into continuous integration pipelines to enforce compliance before code review.

Snapshot Rendering for Visual Feedback

Snapshot rendering generates PNG previews via cadgen sdf snapshot, utilizing the shared headless-browser runtime defined in packages/cadgen/src/cadgen/cli/sdf_snapshot.py. This allows developers to visualize mesh placement, scaling, and lighting without launching a full simulator session. The capability is essential for rapid iteration when authoring complex robot models or verifying world layouts before handing assets to downstream autonomy pipelines.

CAD Viewer Handoff

The skill automatically hands off validated SDF files to the CAD Viewer ($cad-viewer), producing a persistent URL for human review. This bridges the gap between automated validation and manual inspection, enabling teams to share visual references or conduct design reviews without requiring local simulator setup. The handoff occurs automatically after successful validation, returning a shareable link that integrates into documentation or issue trackers.

Complete SDF Authoring Workflow

The SDF Skill supports a structured seven-step workflow that maintains the .sdf file as the single source of truth. According to skills/sdf/references/sdf-workflow.md, practitioners follow this sequence:

1. Locate and edit the source .sdf file directly, following golden skeletons documented in skills/sdf/references/examples.md.
2. Create a design ledger as a comment block at the top of the file to record assumptions, units, and frame conventions (see skills/sdf/references/design-ledger.md).
3. Author XML explicitly, expressing every pose with relative_to and expressed_in attributes to ensure unambiguous transforms.
4. Validate using cadgen sdf validate <file.sdf> with optional --strict or --json flags for CI integration.
5. Run optional smoke tests via gz sdf --check or simulator-load checks when --gz-check is enabled.
6. Render a snapshot using cadgen sdf snapshot <file.sdf> preview.png for visual sanity checking.
7. Hand off to CAD Viewer to generate a permanent review link automatically.

Practical SDF Skill Use Cases

Beyond the core workflow, the SDF Skill addresses specific technical scenarios common in robotics simulation development.

Model-Level SDF Authoring Export reusable robot or object models with self-contained geometry and plugin definitions. The validation step ensures these models can be included by reference in larger world files without namespace collisions.

World-Level SDF Authoring Define physics settings, lighting environments, terrains, and multiple model placements. Snapshot rendering helps verify spatial relationships between static and dynamic elements before deployment.

Model-in-World Context Combine inline model definitions with world-specific context when tasks require both local model verification and global placement validation within a single file.

URDF to SDF Interoperability Generate SDF from existing URDF files to avoid duplicate geometry work, following guidelines in skills/sdf/references/interoperability.md. The validation step catches conversion artifacts like missing inertial properties or invalid joint limits.

CI Pipeline Quality Gates Enforce structural guardrails by running cadgen sdf validate --strict in pre-commit hooks or continuous integration workflows, preventing malformed SDF from entering production simulation environments.

Command-Line Examples

The following commands demonstrate practical usage patterns against the earthtojake/text-to-cad source code:

# Basic validation for structural correctness

cadgen sdf validate assets/robots/my_robot.sdf

# Strict validation treating warnings as failures, outputting JSON for CI parsing

cadgen sdf validate assets/robots/my_robot.sdf --strict --json > validation.json

# Optional Gazebo compatibility check (runs only if `gz` binary is present)

cadgen sdf validate assets/worlds/warehouse.sdf --gz-check auto

# Generate PNG snapshot for documentation or quick review

cadgen sdf snapshot assets/robots/my_robot.sdf preview.png

# Validation followed by automatic viewer handoff

cadgen sdf validate assets/robots/my_robot.sdf && echo "Viewer: $cad-viewer"

Summary

• The SDF Skill centralizes SDFormat file handling in the text-to-cad repository through validation, rendering, and viewer integration.
• Validation (cadgen sdf validate) checks document semantics and structure via packages/cadgen/src/cadgen/cli/sdf_validate.py.
• Snapshot rendering (cadgen sdf snapshot) provides rapid visual feedback without full simulator startup.
• Viewer handoff automates the creation of shareable review links upon successful validation.
• The skill supports model-level, world-level, and interoperability workflows while remaining simulator-version agnostic.

Frequently Asked Questions

How does the SDF Skill differ from running Gazebo directly?

The SDF Skill provides lightweight static analysis and rendering without requiring a full simulator installation. While you can optionally invoke gz sdf --check via the --gz-check flag, the primary validation runs through cadgen code in packages/cadgen/src/cadgen/sdf.py, making it faster for CI environments and independent of specific Gazebo versions.

Can I use the SDF Skill for URDF files?

Yes, though indirectly. The skill focuses on SDFormat, but the repository includes interoperability guidelines in skills/sdf/references/interoperability.md for converting URDF to SDF. Once converted, you validate the resulting .sdf file using the standard cadgen sdf validate workflow to ensure proper pose graphs and inertial properties.

What does the --strict flag do in validation?

The --strict flag, processed by packages/cadgen/src/cadgen/cli/sdf_validate.py, elevates warnings to fatal errors and enforces additional structural guardrails beyond basic schema validation. Use this in production pipelines to ensure that all design ledger requirements and frame conventions are explicitly satisfied.

Where is the snapshot rendering logic implemented?

Snapshot rendering logic resides in packages/cadgen/src/cadgen/cli/sdf_snapshot.py, which interfaces with a shared JavaScript headless-browser runtime. This architecture allows consistent PNG generation across platforms without requiring X11 or manual simulator screenshot scripting.

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