# 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][sdformat] specification.
## Why SDFormat?
Among the many existing robot description formats, SDFormat provides a well-defined and maintained [versioned specification][sdformat_spec] that controls the available fields and their content.
[Open Robotics][open_robotics] already provides the C++ library [`gazebosim/sdformat`](https://github.com/gazebosim/sdformat) with initial support of [Python bindings][sdformat_python].
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][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 of SDFormat specifications [≥ 1.7][sdformat_spec_17]
- Serialization and deserialization support of SDF files
- In-memory layout based on `dataclasses`
- Syntax highlighting and auto-completion
- Support of programmatic creation of SDF files from Python APIs
- Transitive support of URDF through conversion to SDF[^urdf_to_sdf]
- Type validation of elements and attributes
- Automatic check of missing required elements
- Based on [`Fatal1ty/mashumaro`][mashumaro] for great serialization and deserialization performance
- Support of exporting the in-memory model description to URDF
[mashumaro]: https://github.com/Fatal1ty/mashumaro
[open_robotics]: https://www.openrobotics.org/
[pose_semantics]: http://sdformat.org/tutorials?tut=pose_frame_semantics_proposal&cat=pose_semantics_docs&
[sdformat]: http://sdformat.org/
[sdformat_python]: http://sdformat.org/tutorials?tut=python_bindings&cat=developers&
[sdformat_repo]: https://github.com/gazebosim/sdformat
[sdformat_spec]: http://sdformat.org/spec
[sdformat_spec_17]: http://sdformat.org/spec?elem=sdf&ver=1.7
[urdf]: http://wiki.ros.org/urdf
[^urdf_to_sdf]: Conversion can be done either using `ign sdf` included in Ignition Gazebo Fortress, or `gz sdf` included in Gazebo Sim starting from Garden.
## Installation
You can install the project with [`pypa/pip`][pip], preferably in a [virtual environment][venv]:
```bash
pip install git+https://github.com/ami-iit/rod
```
[pip]: https://github.com/pypa/pip/
[venv]: https://docs.python.org/3.8/tutorial/venv.html
## Examples
<details>
<summary>Serialize and deserialize SDF files</summary>
```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))
```
</details>
<details>
<summary>Create SDF models programmatically</summary>
```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))
```
```xml
<?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>
```
</details>
<details>
<summary>Exporting SDF to URDF</summary>
```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.sdf_to_urdf_string(
sdf=sdf,
pretty=True,
gazebo_preserve_fixed_joints=True,
)
print(urdf_string)
```
```xml
<?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>
```
</details>
## Similar 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
| [<img src="https://github.com/diegoferigo.png" width="40">][df] | [@diegoferigo][df] |
|:---------------------------------------------------------------:|:------------------:|
[df]: https://github.com/diegoferigo
## License
[BSD3](https://choosealicense.com/licenses/bsd-3-clause/)
Raw data
{
"_id": null,
"home_page": "https://github.com/ami-iit/rod",
"name": "rod",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "description,gazebo,parser,robot,robotics,ros,sdf,sdformat,simulator,simulation,urdf",
"author": "Diego Ferigo",
"author_email": "diego.ferigo@iit.it",
"download_url": "https://files.pythonhosted.org/packages/a9/ad/3a854b553baef760c1579b425873209ac881d4dfb15d2e1462eeb1ee5572/rod-0.2.0.tar.gz",
"platform": "any",
"description": "# RObot Description processor\n\n**The ultimate Python tool for RObot Descriptions processing.**\n\nROD is yet another library to operate on robot descriptions based on the [SDFormat][sdformat] specification.\n\n## Why SDFormat?\n\nAmong the many existing robot description formats, SDFormat provides a well-defined and maintained [versioned specification][sdformat_spec] that controls the available fields and their content.\n[Open Robotics][open_robotics] already provides the C++ library [`gazebosim/sdformat`](https://github.com/gazebosim/sdformat) with initial support of [Python bindings][sdformat_python].\nHowever, C++ dependencies in pure-Python projects are typically quite complicated to handle and maintain.\nHere ROD comes to rescue.\n\nURDF, thanks to native ROS support, is historically the most popular robot description used by the community.\nThe 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.\nLuckily, URDF models can be easily converted to SDF[^urdf_to_sdf].\nIf the URDF model is not compliant, the process errors with clear messages.\nFurthermore, modern versions of the converter produce a SDF description with standardized [pose semantics][pose_semantics],\nthat greatly simplifies the life of downstream developers that do not have to guess the reference frame or pose elements.\nLast but not least, the pose semantics also makes SDF aware of the concept of _frame_ that URDF is missing.\n\n## Features\n\n- Out-of-the-box support of SDFormat specifications [\u2265 1.7][sdformat_spec_17]\n- Serialization and deserialization support of SDF files\n- In-memory layout based on `dataclasses`\n- Syntax highlighting and auto-completion\n- Support of programmatic creation of SDF files from Python APIs\n- Transitive support of URDF through conversion to SDF[^urdf_to_sdf]\n- Type validation of elements and attributes\n- Automatic check of missing required elements\n- Based on [`Fatal1ty/mashumaro`][mashumaro] for great serialization and deserialization performance\n- Support of exporting the in-memory model description to URDF\n\n[mashumaro]: https://github.com/Fatal1ty/mashumaro\n[open_robotics]: https://www.openrobotics.org/\n[pose_semantics]: http://sdformat.org/tutorials?tut=pose_frame_semantics_proposal&cat=pose_semantics_docs&\n[sdformat]: http://sdformat.org/\n[sdformat_python]: http://sdformat.org/tutorials?tut=python_bindings&cat=developers&\n[sdformat_repo]: https://github.com/gazebosim/sdformat\n[sdformat_spec]: http://sdformat.org/spec\n[sdformat_spec_17]: http://sdformat.org/spec?elem=sdf&ver=1.7\n[urdf]: http://wiki.ros.org/urdf\n\n[^urdf_to_sdf]: Conversion can be done either using `ign sdf` included in Ignition Gazebo Fortress, or `gz sdf` included in Gazebo Sim starting from Garden.\n\n## Installation\n\nYou can install the project with [`pypa/pip`][pip], preferably in a [virtual environment][venv]:\n\n```bash\npip install git+https://github.com/ami-iit/rod\n```\n\n[pip]: https://github.com/pypa/pip/\n[venv]: https://docs.python.org/3.8/tutorial/venv.html\n\n## Examples\n\n<details>\n<summary>Serialize and deserialize SDF files</summary>\n\n```python\nimport pathlib\n\nfrom rod import Sdf\n\n# Supported SDF resources\nsdf_resource_1 = \"/path/to/file.sdf\"\nsdf_resource_2 = pathlib.Path(sdf_resource_1)\nsdf_resource_3 = sdf_resource_2.read_text()\n\n# Deserialize SDF resources\nsdf_1 = Sdf.load(sdf=sdf_resource_1)\nsdf_2 = Sdf.load(sdf=sdf_resource_2)\nsdf_3 = Sdf.load(sdf=sdf_resource_3)\n\n# Serialize in-memory Sdf object\nprint(sdf_3.serialize(pretty=True))\n```\n\n</details>\n\n<details>\n<summary>Create SDF models programmatically</summary>\n\n```python\nfrom rod import Axis, Inertia, Inertial, Joint, Limit, Link, Model, Sdf, Xyz\n\nsdf = Sdf(\n version=\"1.7\",\n model=Model(\n name=\"my_model\",\n link=[\n Link(name=\"base_link\", inertial=Inertial(mass=1.0, inertia=Inertia())),\n Link(name=\"my_link\", inertial=Inertial(mass=0.5, inertia=Inertia())),\n ],\n joint=Joint(\n name=\"base_to_my_link\",\n type=\"revolute\",\n parent=\"base_link\",\n child=\"my_link\",\n axis=Axis(xyz=Xyz(xyz=[0, 0, 1]), limit=Limit(lower=-3.13, upper=3.14)),\n ),\n ),\n)\n\nprint(sdf.serialize(pretty=True))\n```\n\n```xml\n<?xml version=\"1.0\" encoding=\"utf-8\"?>\n<sdf version=\"1.7\">\n <model name=\"my_model\">\n <link name=\"base_link\">\n <inertial>\n <mass>1.0</mass>\n <inertia>\n <ixx>1.0</ixx>\n <iyy>1.0</iyy>\n <izz>1.0</izz>\n <ixy>0.0</ixy>\n <ixz>0.0</ixz>\n <iyz>0.0</iyz>\n </inertia>\n </inertial>\n </link>\n <link name=\"my_link\">\n <inertial>\n <mass>0.5</mass>\n <inertia>\n <ixx>1.0</ixx>\n <iyy>1.0</iyy>\n <izz>1.0</izz>\n <ixy>0.0</ixy>\n <ixz>0.0</ixz>\n <iyz>0.0</iyz>\n </inertia>\n </inertial>\n </link>\n <joint name=\"base_to_my_link\" type=\"revolute\">\n <parent>base_link</parent>\n <child>my_link</child>\n <axis>\n <xyz>0 0 1</xyz>\n <limit>\n <lower>-3.13</lower>\n <upper>3.14</upper>\n </limit>\n </axis>\n </joint>\n </model>\n</sdf>\n```\n\n</details>\n\n<details>\n<summary>Exporting SDF to URDF</summary>\n\n```python\n# Generate first the 'sdf' object with the collapsed code\n# of the section 'Create SDF models programmatically'.\n\nfrom rod.urdf.exporter import UrdfExporter\n\nurdf_string = UrdfExporter.sdf_to_urdf_string(\n sdf=sdf,\n pretty=True,\n gazebo_preserve_fixed_joints=True,\n)\n\nprint(urdf_string)\n```\n\n```xml\n<?xml version=\"1.0\" encoding=\"utf-8\"?>\n<robot name=\"my_model\">\n <link name=\"base_link\">\n <inertial>\n <origin xyz=\"0.0 0.0 0.0\" rpy=\"0.0 0.0 0.0\"/>\n <mass value=\"1.0\"/>\n <inertia ixx=\"1.0\" ixy=\"0.0\" ixz=\"0.0\" iyy=\"1.0\" iyz=\"0.0\" izz=\"1.0\"/>\n </inertial>\n </link>\n <link name=\"my_link\">\n <inertial>\n <origin xyz=\"0.0 0.0 0.0\" rpy=\"0.0 0.0 0.0\"/>\n <mass value=\"0.5\"/>\n <inertia ixx=\"1.0\" ixy=\"0.0\" ixz=\"0.0\" iyy=\"1.0\" iyz=\"0.0\" izz=\"1.0\"/>\n </inertial>\n </link>\n <joint name=\"base_to_my_link\" type=\"revolute\">\n <origin xyz=\"0.0 0.0 0.0\" rpy=\"0.0 0.0 0.0\"/>\n <parent link=\"base_link\"/>\n <child link=\"my_link\"/>\n <axis xyz=\"0 0 1\"/>\n <limit effort=\"3.4028235e+38\" velocity=\"3.4028235e+38\" lower=\"-3.13\" upper=\"3.14\"/>\n </joint>\n</robot>\n```\n\n</details>\n\n## Similar projects\n\n- https://github.com/gazebosim/sdformat\n- https://github.com/mmatl/urdfpy\n- https://github.com/clemense/yourdfpy\n- https://github.com/ros/urdf_parser_py\n- https://github.com/FirefoxMetzger/python-sdformat/\n\n## Contributing\n\nPull requests are welcome. \nFor major changes, please open an issue first to discuss what you would like to change.\n\n## Maintainers\n\n| [<img src=\"https://github.com/diegoferigo.png\" width=\"40\">][df] | [@diegoferigo][df] |\n|:---------------------------------------------------------------:|:------------------:|\n\n[df]: https://github.com/diegoferigo\n\n## License\n\n[BSD3](https://choosealicense.com/licenses/bsd-3-clause/)\n",
"bugtrack_url": null,
"license": "BSD",
"summary": "The ultimate Python tool for RObot Descriptions processing.",
"version": "0.2.0",
"project_urls": {
"Changelog": "https://github.com/ami-iit/rod/releases",
"Homepage": "https://github.com/ami-iit/rod",
"Source": "https://github.com/ami-iit/rod",
"Tracker": "https://github.com/ami-iit/rod/issues"
},
"split_keywords": [
"description",
"gazebo",
"parser",
"robot",
"robotics",
"ros",
"sdf",
"sdformat",
"simulator",
"simulation",
"urdf"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "10e2f81de372829faa7ff52c0e4ea8e684908b9723bc115c910494b2b44c729f",
"md5": "e860f3873ad7057a3e763b51be145e26",
"sha256": "4df9cbcfb079b67d79bcc0b9143cc336c0531020159d24c4c1401dcfc33cb5c2"
},
"downloads": -1,
"filename": "rod-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e860f3873ad7057a3e763b51be145e26",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 37753,
"upload_time": "2024-03-08T14:45:04",
"upload_time_iso_8601": "2024-03-08T14:45:04.635992Z",
"url": "https://files.pythonhosted.org/packages/10/e2/f81de372829faa7ff52c0e4ea8e684908b9723bc115c910494b2b44c729f/rod-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a9ad3a854b553baef760c1579b425873209ac881d4dfb15d2e1462eeb1ee5572",
"md5": "37e7ed00a7f10306f9d7aede3028c24d",
"sha256": "34c907554fbfd93cb864c6c09fadf1c51526e8fadc3307aaea12b80503b61a68"
},
"downloads": -1,
"filename": "rod-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "37e7ed00a7f10306f9d7aede3028c24d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 36910,
"upload_time": "2024-03-08T14:45:06",
"upload_time_iso_8601": "2024-03-08T14:45:06.023643Z",
"url": "https://files.pythonhosted.org/packages/a9/ad/3a854b553baef760c1579b425873209ac881d4dfb15d2e1462eeb1ee5572/rod-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-08 14:45:06",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ami-iit",
"github_project": "rod",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "rod"
}
JSON
