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

> Effortlessly create robot description files URDF using text-to-cad. Convert Python functions to validated URDF without ROS dependencies. Get your complete guide today.

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

---

**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`](https://github.com/earthtojake/text-to-cad/blob/main/source.py)** – Houses the `read_urdf_source` parser and validator that constructs the `UrdfSource` model
- **[`cli.py`](https://github.com/earthtojake/text-to-cad/blob/main/cli.py)** – Implements the `urdf` command-line interface that orchestrates generation and validation  
- **[`__main__.py`](https://github.com/earthtojake/text-to-cad/blob/main/__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:

```python

# 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:

```python
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:

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

Generate a `.urdf` file with the default output path:

```bash
urdf my_robot.py

```

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

```bash
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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/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`](https://github.com/earthtojake/text-to-cad/blob/main/cli.py) module automatically passes generated content to `read_urdf_source` in [`source.py`](https://github.com/earthtojake/text-to-cad/blob/main/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.