How to Create Robot Description Files (URDF) with text-to-cad: A Complete Guide

text-to-cad provides a dedicated URDF skill that converts a minimal Python generator function into a fully-validated robot description file without requiring ROS dependencies.

The earthtojake/text-to-cad repository includes a specialized URDF skill that streamlines how engineers create robot description files (URDF) with text-to-cad workflows. This self-contained pipeline eliminates external build steps and ROS dependencies while producing .urdf files compatible with any ROS 2 or MoveIt 2 stack.

The URDF Skill Architecture

The URDF generation pipeline consists of three core components located in skills/urdf/scripts/urdf/:

• source.py – Houses the read_urdf_source parser and validator that constructs the UrdfSource model
• cli.py – Implements the urdf command-line interface that orchestrates generation and validation
• __main__.py – Provides the module entry point for python -m skills.urdf.scripts.urdf

This architecture ensures that every generated file passes rigorous validation checks before reaching your robotics stack.

Writing a URDF Generator Script

To create robot description files with text-to-cad, you must write a Python script that defines a callable gen_urdf() function. The skill supports three return formats: an xml.etree.ElementTree.Element representing the root <robot> tag, a raw XML string, or a dictionary containing the XML.

Using ElementTree for Structured Generation

The most robust approach constructs the URDF using Python's built-in XML library:

# my_robot.py

import xml.etree.ElementTree as ET

def gen_urdf() -> ET.Element:
    """Return a minimal URDF describing a single link."""
    robot = ET.Element("robot", {"name": "my_robot"})

    # Link with a visual box

    link = ET.SubElement(robot, "link", {"name": "base_link"})
    visual = ET.SubElement(link, "visual")
    geometry = ET.SubElement(visual, "geometry")
    box = ET.SubElement(geometry, "box", {"size": "0.2 0.2 0.1"})

    return robot

Returning Raw XML Strings

For simple robots or template-based generation, return the XML directly as a string:

def gen_urdf():
    return """<?xml version="1.0"?>
    <robot name="my_robot">
      <link name="base_link"/>
    </robot>"""

Using Dictionary Envelopes for Metadata

When you need to supply additional metadata alongside the XML, wrap the string in a dictionary:

def gen_urdf():
    return {"xml": """<robot name="my_robot"><link name="base_link"/></robot>"""}

Generating URDF Files from the Command Line

Once your generator script is complete, use the urdf CLI to produce the final file. The interface automatically calls gen_urdf(), writes the output, and validates the result using read_urdf_source from source.py.

Generate a .urdf file with the default output path:

urdf my_robot.py

This creates my_robot.urdf in the same directory as your script. To specify a custom location:

urdf my_robot.py -o ./robots/my_robot.urdf

Understanding the Validation Pipeline

According to the text-to-cad source code, the read_urdf_source validator in source.py performs comprehensive integrity checks before accepting the generated file. These validations include:

• Robot name consistency and formatting
• Link and joint relationship integrity
• Geometry tags and mesh reference validity
• Numeric range verification for dimensions and positions
• Tree structure validation ensuring no orphaned joints or circular references

If validation fails, the CLI raises informative errors that pinpoint the specific line or structural issue in your generator script.

Summary

• text-to-cad provides a self-contained URDF skill in the earthtojake/text-to-cad repository that requires no ROS installation.
• Create a Python script defining gen_urdf() that returns an ElementTree.Element, XML string, or {"xml": string} dictionary.
• Invoke the urdf CLI to generate and automatically validate your .urdf file against read_urdf_source checks.
• The pipeline validates robot names, link/joint consistency, geometry references, and tree structure before output.

Frequently Asked Questions

What dependencies are required to create robot description files with text-to-cad?

The URDF skill requires only standard Python libraries. The validation pipeline in source.py uses built-in XML parsing and custom logic to check link/joint consistency and geometry tags without relying on ROS, xacro, or external CATKIN workspaces.

Can I use XML libraries other than ElementTree in my generator script?

Yes. While xml.etree.ElementTree is recommended for programmatic construction, the gen_urdf() function may return any format that results in a valid XML string or Element object. You could use lxml or template engines like Jinja2, provided the final return value conforms to one of the three supported output types.

How does text-to-cad validate URDF files?

The cli.py module automatically passes generated content to read_urdf_source in source.py, which constructs an UrdfSource model. This validator checks for robot name presence, valid mesh references, numeric range compliance for dimensions, and proper tree structure to ensure the URDF is immediately usable in ROS 2 or MoveIt 2 environments.

Is ROS required to use the generated URDF files?

No. The text-to-cad URDF skill operates independently of ROS installations. However, the generated files conform to standard URDF specifications and can be used directly with any ROS 2 robot_state_publisher, Gazebo, or MoveIt 2 configuration without additional modification.

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