Skip to main content

RObot Description processor

The ultimate Python tool for RObot Descriptions processing.

ROD is yet another library to operate on robot descriptions based on the SDFormat specification.

Why SDFormat?

Among the many existing robot description formats, SDFormat provides a well-defined and maintained versioned specification that controls the available fields and their content. Open Robotics already provides the C++ library gazebosim/sdformat with initial support of Python bindings. However, C++ dependencies in pure-Python projects are typically quite complicated to handle and maintain. Here ROD comes to rescue.

URDF, thanks to native ROS support, is historically the most popular robot description used by the community. The main problem of URDF is that it is not a specification, and developers of URDF descriptions might produce models and parsers that do not comply to any standard. Luckily, URDF models can be easily converted to SDF1. If the URDF model is not compliant, the process errors with clear messages. Furthermore, modern versions of the converter produce a SDF description with standardized pose semantics, that greatly simplifies the life of downstream developers that do not have to guess the reference frame or pose elements. Last but not least, the pose semantics also makes SDF aware of the concept of frame that URDF is missing.

Features

  • Out-of-the-box support for SDFormat specifications ≥ 1.10.
  • Serialization and deserialization support for SDF files.
  • In-memory layout based on dataclasses.
  • Syntax highlighting and auto-completion.
  • Programmatic creation of SDF files from Python APIs.
  • Transitive support for URDF through conversion to SDF.
  • Type validation of elements and attributes.
  • Automatic check of missing required elements.
  • High-performance serialization and deserialization using Fatal1ty/mashumaro.
  • Export in-memory model description to URDF.

Installation

[!TIP] ROD does not support out-of-the-box URDF files. URDF support is obtained by converting URDF files to SDF using the gz sdf command provided by sdformat and gz-tools. Ensure these tools are installed on your system if URDF support is needed (more information below).

Using conda (recommended)

Installing ROD using conda is the recommended way to obtain a complete installation with out-of-the-box support for both URDF and SDF descriptions:

conda install rod -c conda-forge

This will automatically install sdformat and gz-tools.

Using pixi

pixi definitely provides the quickest way to start using ROD. You can run the tests by executing:

pixi run test

or install the default dependencies with:

pixi install

check out the pyproject.toml file for the list of all available features and read the pixi documentation for more information.

Using pip

You can install ROD from PyPI with pypa/pip, preferably in a virtual environment:

pip install rod[all]

If you need URDF support, follow the official instructions to install Gazebo Sim on your operating system, making sure to obtain sdformat ≥ 13.0 and gz-tools ≥ 2.0.

You don't need to install the entire Gazebo Sim suite. For example, on Ubuntu, you can only install the libsdformat13 gz-tools2 packages.

Examples

Serialize and deserialize SDF files
import pathlib

from rod import Sdf

# Supported SDF resources
sdf_resource_1 = "/path/to/file.sdf"
sdf_resource_2 = pathlib.Path(sdf_resource_1)
sdf_resource_3 = sdf_resource_2.read_text()

# Deserialize SDF resources
sdf_1 = Sdf.load(sdf=sdf_resource_1)
sdf_2 = Sdf.load(sdf=sdf_resource_2)
sdf_3 = Sdf.load(sdf=sdf_resource_3)

# Serialize in-memory Sdf object
print(sdf_3.serialize(pretty=True))
Create SDF models programmatically
from rod import Axis, Inertia, Inertial, Joint, Limit, Link, Model, Sdf, Xyz

sdf = Sdf(
    version="1.7",
    model=Model(
        name="my_model",
        link=[
            Link(name="base_link", inertial=Inertial(mass=1.0, inertia=Inertia())),
            Link(name="my_link", inertial=Inertial(mass=0.5, inertia=Inertia())),
        ],
        joint=Joint(
            name="base_to_my_link",
            type="revolute",
            parent="base_link",
            child="my_link",
            axis=Axis(xyz=Xyz(xyz=[0, 0, 1]), limit=Limit(lower=-3.13, upper=3.14)),
        ),
    ),
)

print(sdf.serialize(pretty=True))
<?xml version="1.0" encoding="utf-8"?>
<sdf version="1.7">
  <model name="my_model">
    <link name="base_link">
      <inertial>
        <mass>1.0</mass>
        <inertia>
          <ixx>1.0</ixx>
          <iyy>1.0</iyy>
          <izz>1.0</izz>
          <ixy>0.0</ixy>
          <ixz>0.0</ixz>
          <iyz>0.0</iyz>
        </inertia>
      </inertial>
    </link>
    <link name="my_link">
      <inertial>
        <mass>0.5</mass>
        <inertia>
          <ixx>1.0</ixx>
          <iyy>1.0</iyy>
          <izz>1.0</izz>
          <ixy>0.0</ixy>
          <ixz>0.0</ixz>
          <iyz>0.0</iyz>
        </inertia>
      </inertial>
    </link>
    <joint name="base_to_my_link" type="revolute">
      <parent>base_link</parent>
      <child>my_link</child>
      <axis>
        <xyz>0 0 1</xyz>
        <limit>
          <lower>-3.13</lower>
          <upper>3.14</upper>
        </limit>
      </axis>
    </joint>
  </model>
</sdf>
Exporting SDF to URDF
# Generate first the 'sdf' object with the collapsed code
# of the section 'Create SDF models programmatically'.

from rod.urdf.exporter import UrdfExporter

urdf_string = UrdfExporter(pretty=True, gazebo_preserve_fixed_joints=True).to_urdf_string(
    sdf=sdf
)

print(urdf_string)
<?xml version="1.0" encoding="utf-8"?>
<robot name="my_model">
  <link name="base_link">
    <inertial>
      <origin xyz="0.0 0.0 0.0" rpy="0.0 0.0 0.0"/>
      <mass value="1.0"/>
      <inertia ixx="1.0" ixy="0.0" ixz="0.0" iyy="1.0" iyz="0.0" izz="1.0"/>
    </inertial>
  </link>
  <link name="my_link">
    <inertial>
      <origin xyz="0.0 0.0 0.0" rpy="0.0 0.0 0.0"/>
      <mass value="0.5"/>
      <inertia ixx="1.0" ixy="0.0" ixz="0.0" iyy="1.0" iyz="0.0" izz="1.0"/>
    </inertial>
  </link>
  <joint name="base_to_my_link" type="revolute">
    <origin xyz="0.0 0.0 0.0" rpy="0.0 0.0 0.0"/>
    <parent link="base_link"/>
    <child link="my_link"/>
    <axis xyz="0 0 1"/>
    <limit effort="3.4028235e+38" velocity="3.4028235e+38" lower="-3.13" upper="3.14"/>
  </joint>
</robot>

Command Line Interface

ROD provides a command line interface (CLI) for processing robot description files. You can use the CLI to display file attributes or convert files between URDF and SDF formats.

Usage

  • Display the attributes of an SDF file:
rod --file /path/to/file.sdf --show
  • Convert an SDF file to URDF:
rod --file /path/to/file.sdf -o /path/to/file.urdf

Similar projects

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

People

Author

@diegoferigo

Maintainers

@flferretti @CarlottaSartore

License

BSD3

  1. Conversion can be done using the gz sdf command included in Gazebo Sim starting from Garden. ↩

Metadata

Release files for rod 0.5.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for rod 0.5.0
File Size Uploaded Provenance Actions
rod-0.5.0.tar.gz 37.4 kB With provenance Details for rod-0.5.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for rod 0.5.0
File Interpreter ABI Platform Actions
rod-0.5.0-py3-none-any.whl Python 3 none any Details for rod-0.5.0-py3-none-any.whl

Total release size: 79.3 kB

Release files / rod-0.5.0.tar.gz

Download URL rod-0.5.0.tar.gz
Size 37.4 kB
Tags Source
SHA-256 checksum
How to use checksums
2b33adf32551578bcfd17759f650dde33693a3d70879df9094ea7654589395ea
BLAKE2b-256 checksum
How to use checksums
6da7f4bf0e604cea9052a973ec4a3ef2e56611dce71fe5d62398d479ef9569f4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Mar 30, 2026.

Transparency log

Release files / rod-0.5.0-py3-none-any.whl

Download URL rod-0.5.0-py3-none-any.whl
Size 41.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
06126a331e1d94526b070590782e00b2fd68eff12e9f156a2eb8f9abafcc49ed
BLAKE2b-256 checksum
How to use checksums
7685272ba2170076a96f8e0ef164ee8f6a40b58f97366558db1e16c282daf6a9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Mar 30, 2026.

Transparency log

Security for rod 0.5.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for rod-0.5.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Mar 30, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.5.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page