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 SDF[^urdf_to_sdf]. 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.
[^urdf_to_sdf]: Conversion can be done using the gz sdf command included in Gazebo Sim starting from Garden.
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 sdfcommand 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: ```bash conda install rod -c conda-forge ``` This will automatically install `sdformat` and `gz-tools`.Using pip
You can install ROD from PyPI with [`pypa/pip`][pip], preferably in a [virtual environment][venv]: ```bash pip install rod[all] ``` If you need URDF support, follow the [official instructions][gazebo_sim_docs] 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. [pip]: https://github.com/pypa/pip/ [venv]: https://docs.python.org/3.10/tutorial/venv.html [gazebo_sim_docs]: https://gazebosim.org/docsExamples
Serialize and deserialize SDF files
```python 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
```python 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)) ``` ```xmlExporting SDF to URDF
```python # 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) ``` ```xmlSimilar projects
- https://github.com/gazebosim/sdformat
- https://github.com/mmatl/urdfpy
- https://github.com/clemense/yourdfpy
- https://github.com/ros/urdf_parser_py
- https://github.com/FirefoxMetzger/python-sdformat/
Contributing
Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
Maintainers
 |
@diegoferigo |
|---|