File format
[TOC]
The SMURF format uses URDF at its heart for defining the kinematic model of a robot. URDF was created in the ROS world and contains only sparse information beyond the "mechanical skeleton" of a robot. Thus, the SMURF format encompasses additional files adding all information that is needed by MARS and in fact any custom-defined data one wants to assign to arbitrary parts of the robot. Thus, Phobos is designed to assist the user in building a viable URDF robot model in Blender and annotate all additional information in SMURF which allows the simulation of the robot in MARS or any custom-tailored tools.
| Format | Extensions | Import | Export | Info |
|---|---|---|---|---|
| SMURF | .smurf | x | always | consists of URDF and JSON extensions |
| URDF | .urdf | x | x | XML format to describe robot kinematics |
| SDF | .sdf | x | x | the main model format of the Gazebo simulation |
| x | the kinematic structure of the robot model |
Phobos exports some more formats like SRDF, YAML, submechanisms etc. However, as these are not widely known or used, these are not listed here.
Since release 1.0 Phobos is able to import, edit and export SDF models. SDF is developed as part of the simulation suite Gazebo, which is widely used for robotic applications in the ROS world. It is an advanced format, that contains many additional features and custom scripts, that have reached a complexity, Phobos can not (yet) deal with. For the moment, basic models and most of the common functionality (links, visuals, collisions, sensors, inertias etc.) is implemented. More can be included if there is sufficient interest from the community to support further development.
URDF (the Unified Robot Description Format) enjoys some wide acceptance in the robotics community. It is a rather basic format, that has its own flaws, but is supported my most frameworks for robotic applications. As such, it is deeply connected to Phobos, which acts as an editor for URDF models. Phobos fulfills this job to a high level, allowing the user to import, edit and export models, that are Git compatible and intuitive. However, there are more useful features, which will be available only when using other formats (such as SMURF and SDF).
| Format | Extensions | Import | Export | Info |
|---|---|---|---|---|
| Wavefront | .obj | x | x | |
| STereoLithography | .stl | x | x | often the best option to export from CAD |
| COLLADA | .dae | x | x | digital assets exchange |
Note, that you can basically import any mesh file, that Blender can import. There are add-ons out there, which might help you with your specific format. The mesh formats above are listed mainly for their export functionality in the model export of Phobos.
Meshes can be exported in different orientations in Blender. It is possible to define which axis points up and which forward when forming a right-handed frame. Simulators may use different conventions when importing meshes. Therefore we had a look on several simulators in the Phobos' Habitat to ensure compatibility.
The details:
Mesh formats
STL saves vertices in the following format:
facet normal -1.000000 0.000000 0.000000
outer loop
vertex 0.000000 0.000000 3.000000
vertex 0.000000 2.000000 0.000000
vertex 1.000000 0.000000 0.000000
endloop
When using the convention Z is Up and Y is Forward, the STL base frame has the same orientation as intended by the mesh. See the format example which shows a face that was created with vertices on all axis with different distances from the origin: x = 1 y =2 z =3.
OBJ saves vertices in the following format:
o zupyforward
v 0.000000 2.000000 0.000000
v 1.000000 0.000000 0.000000
v 0.000000 0.000000 3.000000
...
Equally to STL the OBJ origin is the same as the origin during creation when using the export convention Z is Up and Y is Forward.
In DAE vertices are saved in the following format:
...
<library_geometries>
<geometry id="zupyforward-mesh" name="zupyforward">
<mesh>
<source id="zupyforward-mesh-positions">
<float_array id="zupyforward-mesh-positions-array" count="255">0.000000 2.000000 0.000000 1.000000 0.000000 0.000000 0.000000 0.000000 3.000000 ...</float_array>
<technique_common>
<accessor source="#zupyforward-mesh-positions-array" count="85" stride="3">
<param name="X" type="float"/>
<param name="Y" type="float"/>
<param name="Z" type="float"/>
</accessor>
</technique_common>
</source>
...
...
...Again DAE uses the same origin as STL and OBJ.
Test procedure/data
To test the simulators we created a testing URDF.
I created the mesh above in blender to identify the axes when loaded. (Color coding: RGB = XYZ)The length and points of the arms display the axis by their length and vertices at their end: x=1, y=2, z=3
This mesh is included in the following URDF:
<robot name="mesh_orientation_tester" version="1.0">
<link name="root">
<visual name="zupyforward">
<origin rpy="0.0 0.0 0.0" xyz="0.0 0.0 0.0"/>
<geometry>
<mesh filename="zupyforward.dae" scale="1.0 1.0 1.0"/>
</geometry>
</visual>
<collision name="zupyforward_collision">
<origin rpy="0.0 0.0 0.0" xyz="0.0 0.0 0.0"/>
<geometry>
<mesh filename="zupyforward.dae" scale="1.0 1.0 1.0"/>
</geometry>
</collision>
</link>
</robot>The mesh I exchanged vs their DAE/STL/OBJ version during testing.
As URDF/SDF give transformations from root->link->mesh the orientation of the mesh is clearly defined. One could expect that the mesh will be placed accordingly. As the test URDF, presented above, has only zero transformations and the mesh is oriented in all tested mesh formats without any orientation, I'd expect that in all simulators the X-arm of the mesh will point in X-direction, Y-arm in Y-direction and Z-arm in Z-direction.
Note: OSG Based software may have a flaw on importing meshes and there rotations. This is an issue already known for quite a while: https://osg-users.openscenegraph.narkive.com/nhqajNbb/coordinate-system-in-all-readerwriters
pyBullet
pyBullet version: build time: May 20 2022 19:44:17
import pybullet as pb
pb.connect(pb.GUI)
pb.loadURDF("mesh_orientation_tester.urdf")
PyBullet fulfils the expectation for all formats.
MARS
MARS version: [8ae15f9](https://github.com/rock-simulation/mars/tree/8ae15f9360b2764b510d5b6635192b441e0be48a) ```bash mars_app -s mesh_orientation_tester.urdf ``` In the images X is pointing in to the right, Y up and Z into the screen. MARS fulfils the expectation for STL and DAE, but obj seems to be loaded differently. Here showing only the visual representation.
NOTE: This issue has been fixed since 8ae15f9
NOTE: MARS v2 might interpret the meshes as gazebo and bullet.
GAZEBO
Gazebo version: 7.0.0 For Gazebo I had to adapt the URDF a little, but those changes doesn't affect the behaviour of mesh interpretation: - giving absoulte pathes for the meshes - adding an inertial to the linkRegarding the loading of meshes Gazebo beaves exactly as expected. In the images the Origin-Frame of Gazebo is pointing as follows: X is pointing away from the viewer into the screen plane, Y is pointing to the left and Z is pointing upwards. The greyish stuff in front is the shadow of the test mesh.
Back to top.
