Generate URDF model from CREO Parametric mechanisms.
Since it is under development, we cannot guarantee that the user interface of creo2urdf will not implement breaking changes. Be aware of this if you start using the code contained in this repository
9.0.8.011.0.3.0
- To export the urdf of the robot, the CREO mechanism has to follow these guidelines.
- The joints are assumed to be in position 0.
- Right now it can handle only REVOLUTE, PRISMATIC, FIXED and BALL joints.
Note
The BALL joints are not supported in the URDF, for this reason they are exported as a chain of three REVOLUTE joints, with axis orthogonal each other, intersecting in one point, and with the two middle links of the chain with mass zero.
Note
The provided dll has not been unlocked, and we cannot unlock it; see:
Therefore, the Toolkit and Object Toolkit licence is required for using it
Download creo2urdf.zip from the assets of the latest release, and extract it in the folder you like.
This archive contains the dll of the plugin and the text folder for running it.
Follow the Usage section instructions for completing the installation.
Right now the creo2urdf plugin needs its dependencies to be compiled and linked statically:
- Download vcpkg:
git clone https://github.com/microsoft/vcpkg - Bootstrap vcpkg:
.\vcpkg\bootstrap-vcpkg.bat
- Export
CREO_INSTALL_PATHpointing to the Creo9 installation folder, e.g.C:\Program Files\PTC\Creo 9.0.8.0\Common Files - Pass
-DCMAKE_TOOLCHAIN_FILE=[path to vcpkg]/scripts/buildsystems/vcpkg.cmake -DVCPKG_TARGET_TRIPLET=x64-windows-static-mdto the creo2urdf compilation. - Run the CMake
configurestep, then build the project:- Within Visual Studio, you can do: Project > Configure creo2urdf, then Build > Build all
For those who use the CMake integration in Visual Studio, the -DCMAKE_TOOLCHAIN_FILE option should not be passed to CMake command arguments. Instead, the vcpkg.cmake file path must be passed in CMake toolchain file.
Note
creo2urdf uses a vcpkg.json for installing the specific version of the dependencies needed for the compilation.
The version of vcpkg used is specified here.
- Put in your CREO working directory the
protk.datthat is automatically generated by CMake in${PROJECT_BINARY_DIR}(e.g.C:\Users\ngenesio\mesh-iit\creo2urdf\build\x64-Release). Or create it by hand as follow:
name creo2urdf
Startup dll
Allow_stop True
Delay_start False
exec_file \path\to\creo2urdf.dll
text_dir \path\to\creo2urdf\src\creo2urdf\text
END
- Open CREO Parametric: on the first time, you will need to accept the plugin registration
- Load the assembly mechanism of which you want to export the urdf
- Press the button
- Select a yaml and csv configuration files with a format explained in the following sections, and the folder where both the urdf the meshes will be saved.
The folder examples contains a simple assembly with two links, called joints_assembled.asm.
You can open the assembly in Creo and then test the installation by clicking on the Creo2Urdf button.
The plugin will ask you to select the related .yaml (2bars.yaml) and .csv (2bars.csv) files, which are provided in the folder.
If the export process was successful, you should see "model.urdf" and the stl of the meshes.
The YAML format is used to pass parameters to the plugin to customized the conversion process. The parameters accepted by the plugin are documented in the following.
The YAML can eventually include other YAML files using the includes parameter, if so, the included files are merged with the main file.
All internal groups are merged if they are maps, they are overwritten only if an element is not a map, taking precedence over the main file in case of conflicts.
Note
The includes parameter is not mandatory, but if it is present, it must be a list of strings, containing relative path respect the directory of the main YAML file.
| Attribute name | Type | Default Value | Description |
|---|---|---|---|
includes |
List of strings | "" | List of paths relative to the main YAML directory |
| Attribute name | Type | Default Value | Description |
|---|---|---|---|
warningsAreFatal |
Boolean | true | Used for throwing fatal errors in case some steps in the exportation of the urdf are failing. |
| Attribute name | Type | Default Value | Description |
|---|---|---|---|
urdfNumericalPrecision |
Integer | Not set | Optional. Number of decimal places for all numerical values in the exported URDF. Valid range: 1-15. Recommended: 8. If omitted or 0, the exporter uses the minimum number of digits required to represent exactly the floating point values in output |
| Attribute name | Type | Default Value | Description |
|---|---|---|---|
robotName |
String | model name set in the file PhysicalModelingXMLFile | Used for setting the model name, i.e. the parameter <robot name="..."> in the URDF model file. |
rename |
Map | {} (Empty Map) | Maps CAD names, path-qualified component names, and joint keys to the desired URDF names. |
componentNames |
Array | [] (Empty Array) | Assigns URDF link names to specific component occurrences using their assembly paths. See below. |
componentNames is an optional top-level YAML list that assigns a final URDF link name to an individual part occurrence. It works for both unique and repeated CAD parts. It is an alternative to naming links through rename, useful when you want to select a component directly by its path instead of its CAD name.
Each entry has two required fields:
| Field | Type | Description |
|---|---|---|
path |
Array of integers | Complete sequence of component feature IDs from the exported root assembly to the part. Copy it from component-inventory.yaml. |
name |
String | Final URDF link name. It must be nonempty and unique among the exported links. |
For example, if the inventory contains two occurrences of BAR at [59] and [81], you can configure:
componentNames:
- path: [59]
name: bar_1
- path: [81]
name: bar_2
rename:
BARLONGER: bar_longer
BAR_59--BARLONGER: bar_1_bar_longer_revolute_joint
BARLONGER--BAR_81: bar_longer_bar_2_revolute_jointThis assigns the same link names as BAR_59: bar_1 and BAR_81: bar_2 under rename. You can mix the two mechanisms for different links. If both select the same occurrence, componentNames takes precedence: its name is the final name and is not passed through rename again. Components omitted from this list follow the normal rename and automatic naming rules below.
Use the assigned names (bar_1, bar_2) wherever the configuration expects a URDF link name, such as root, linkFrames[].linkName, or frameReferenceLink. Joint keys in rename still use the CAD occurrence names from the inventory's cadName field, as shown above; link aliases do not change those keys. CSV entries and sensor jointName use the final joint names.
For a part inside a subassembly, include the full path, for example [40, 12], rather than just [12]. Paths are relative to the assembly being exported and should be checked after restructuring or replacing components. Unknown paths, repeated entries for the same path, empty names, or duplicate final link names abort the export with a diagnostic.
Multiple occurrences of the same Creo part are supported. Internally, each link is identified by the complete sequence of component feature IDs from the root assembly. For example, [40, 12] and [75, 12] identify distinct occurrences even when both refer to the same part inside a repeated subassembly. The path is relative to the assembly being exported; it is not a global UUID and must be checked after restructuring or replacing components.
The exporter writes component-inventory.yaml in the output directory, listing each part's path, CAD model, disambiguated cadName, and resolved URDF name. Use cadName as the link key in rename and to compose joint keys. The inventory is also written without resolved names if name resolution fails. Use these paths to assign readable names:
root: base_link
linkFrames:
- linkName: base_link
frameName: CSYS
- linkName: moving_link
frameName: CSYS
rename:
LINK_40: base_link
LINK_75: moving_link
LINK_40--LINK_75: hingeThe example assumes two occurrences of the CAD model LINK. The numbers above are examples; copy the actual IDs and cadName values from your inventory. Use the resolved URDF names in root, linkFrames, mass/inertia/color/collision assignments, sensors, and frameReferenceLink. For a moving joint named hinge, the CSV must contain a hinge row.
Naming rules:
- Link naming precedence is: explicit
componentNamesalias, path-qualifiedrenamekey (LINK_40_12), unique CAD-namerenamekey, automatic name.componentNamesremains optional for explicit path selection. - Unique CAD names keep the existing
renamebehavior and default names. A path-qualified key can also be used for a unique part (for example,BASE_90: base_link), and takes precedence overBASE: .... - Repeated parts without aliases use
<CAD-name>_<path>, such asLINK_40_12. - If a generated CAD occurrence name collides with another name (for example,
LINKat[40]and an actual CAD model namedLINK_40), the generated name receives_occ_<path>, such asLINK_40_occ_40. Additional trailing underscores are added if needed to avoid further collisions. Unique CAD model names remain unchanged. Copy the resultingcadNamefrom the inventory for link and joint rename keys;componentNamesaliases remain independent of these names. - A bare
renamekey for a repeated part (such asLINK) is ambiguous: useLINK_40andLINK_75instead. If retained, every occurrence must have an explicit path-qualified rename orcomponentNamesalias. An occurrence without a rename otherwise retains its automatic name. - Joint keys always use
<parent-cadName>--<child-cadName>, independently ofcomponentNamesand link renames. EachcadNameis the original CAD name if unique, or<CAD-name>_<path>if repeated. Examples:BASE--ARM,BASE--LINK_75, andLINK_40_12--LINK_75_12. Without a joint rename, this key is also the exported joint name. - Unknown
componentNamespaths, duplicate output names, ambiguous rename selectors and ambiguous joint renames abort export with a diagnostic. If a qualified key also matches another CAD model name, select the occurrences using explicitcomponentNamespaths instead.
Repeated coordinate-system names can be exported independently:
exportedFrames:
- frameName: SCSYS_SENSOR
frameReferenceLink: base_link
exportedFrameName: base_sensor_frame
- frameName: SCSYS_SENSOR
frameReferenceLink: moving_link
exportedFrameName: moving_sensor_frameOmitting frameReferenceLink is allowed only when the CAD frame exists on exactly one occurrence. With exportAllUseradded, repeated frame names receive the occurrence-path suffix. Sensors resolve their frame on frameReferenceLink (defaulting to their linkName); they can also reference an exported frame name. Force/torque sensors resolve their configured jointName, rather than searching for a joint by datum name alone. Reference links used for sensor frames must be rigidly attached to the sensor's target link.
Mesh files for repeated parts receive an occurrence-path suffix, allowing different link frames and properties per occurrence. Unique parts retain their existing mesh filenames. When exportMeshes is disabled, provide files using these same names.
The exporter still supports one link pair/constraint set per component feature. Conflicting constraint references are rejected instead of choosing one pair implicitly. Geometry references to assembly-level datums do not create additional URDF links.
Tests for identity and naming can run without Creo or its SDK:
cmake -S tests -B build/identity-tests
cmake --build build/identity-tests
ctest --test-dir build/identity-tests --output-on-failureFor runtime validation in Creo, export an existing example first, then an assembly containing two occurrences of the same part joined by a pin joint. Check that it produces two links, the intended parent/child joint, distinct mesh filenames, and distinct frame/sensor poses. Repeat with a duplicated subassembly to exercise full paths. The compiler and naming tests do not validate Creo's runtime constraint references.
| Attribute name | Type | Default Value | Description |
|---|---|---|---|
root |
String | First body in the file | Changes the root body of the tree |
originXYZ |
List | empty | Changes the position of the root body |
originRPY |
List | empty | Changes the orientation of the root body |
| Attribute name | Type | Default Value | Description |
|---|---|---|---|
epsilon |
Float | 4*(Machine eps) | Set a custom value for testing whether a number is close to zero |
| Attribute name | Type | Default Value | Description |
|---|---|---|---|
linkFrames |
Array | empty | Structure mapping the link names to the displayName of their desired frame. Unfortunatly in URDF the link frame origin placement is not free, but it is constrained to be placed on the parent joint axis, hence this option is for now reserved to the root link and to links connected to their parent by a fixed joint |
exportAllUseradded |
Boolean | False | If true, export all frames starting w/ SCSYS in the output URDF as fake links i.e. fake link with zero mass connected to a link with a fixed joint. |
exportedFrames |
Array | empty | Array of displayName of UserAdded frames to export. This are exported as fixed URDF frames, i.e. fake link with zero mass connected to a link with a fixed joint. |
exportFirstBaseLinkAdditionalFrameAsFakeURDFBase |
Boolean | false | Controls the iDynTree::ModelExporterOptions::exportFirstBaseLinkAdditionalFrameAsFakeURDFBase option for the iDynTree URDF exporter. If this YAML parameter is omitted, creo2urdf defaults this iDynTree option to false (this is a change from creo2urdf <= v0.5.11 which defaulted to true). This change aims to reduce confusion (see issue #140, issue #1201). Set this YAML parameter to true to restore the behavior of creo2urdf <= v0.5.11 . |
| Attribute name | Type | Default Value | Description |
|---|---|---|---|
linkName |
String | Mandatory | name of the link for which we want to set the frame |
frameName |
String | Mandatory | displayName of the frame that we want to use as link frame. This frame should be attached to the frameReferenceLink link. The default value for frameReferenceLink is linkName |
frameReferenceLink |
String | empty | frameReferenceLink at which the frame is attached. If frameReferenceLink is empty, it will default to linkName |
| Attribute name | Type | Default Value | Description |
|---|---|---|---|
frameName |
String | Mandatory | displayName of the frame in which the sensor measure is expressed. The selected frame should be attached to the referenceLink link, but referenceLink can be be omitted if the frameName is unique in the model. |
frameReferenceLink |
String | empty | frameReferenceLink at which the frame is attached. If referenceLink is empty, it will be selected the first USERADDED frame with the specified frameName |
exportedFrameName |
String | sensorName | Name of the URDF link exported by the exportedFrames option |
additionalTransformation |
List | Empty | Additional transformation applied to the exported frame, it is expressed as [x, y, z, r, p, y] according to the semantics and units of the SDF convention for expressing poses. If the unmodified transformation of the additionalFrame is indicated as linkFrame_H_additionalFrameOld, this parameter specifies the additionalFrameOld_H_additionalFrame transform, and the final transform exported in the URDF is computed as linkFrame_H_additionalFrame = linkFrame_H_additionalFrameOld*additionalFrameOld_H_additionalFrame . If not specified it is assume to be the [0, 0, 0, 0, 0, 0] element and the specified frame is exported in the URDF unmodified. |
| Attribute name | Type | Default Value | Description |
|---|---|---|---|
filenameformat |
String | %s | Used for translating the filenames in the exported XML to the URDF filenames, using a formatting string. Example: "package://my_package//folder/%sb" - resolves to the package name and adds a "b" at the end to indicate a binary stl. |
forcelowercase |
Boolean | False | Used for translating the filenames. Ff True, it forces all filenames to be lower case. |
scale |
String | None | If this parameter is defined, the scale attribute of the mesh in the URDF will be set to its value. Example: "0.01 0.01 0.01" - if your meshes were saved using centimeters as units instead of meters. |
stringToRemoveFromMeshFileName |
String | None | This parameter allows to specify a string that will be removed from the mesh file names. Example: "_prt" |
assignedCollisionGeometry |
Array | None | Structure for redefining the collision geometry for a given link. |
assignedColors |
Map | {} (Empty Map) | If a link is in this map, the color found in the SimMechanics file is substituted with the one passed through this map. The color is represented by a 4 element vector of containing numbers from 0 to 1 representing the red, green, blue and alpha component. |
meshFormat |
String | stl_binary |
Format of the meshes exported. Allowed values: stl_binary, stl_ascii, step |
exportMeshes |
Boolean | True | If false, the meshes will not be exported. |
meshQuality |
Integer | 3 | Quality of the meshes exported. The value is between 1 and 10, where 1 is the lowest quality and 10 is the highest, see the ptc creo docs on pfcCoordSysExportInstructions::SetQuality method. NOTE: this is valid for the stl meshes. |
| Attribute name | Type | Default Value | Description |
|---|---|---|---|
linkName |
String | Mandatory | Name of the link for which the collision geometry is specified. |
geometricShape |
Dictionary | Mandatory | This dictionary contains the parameters used to define the type and the position of the geometric shape. In particular we have:
|
assignedCollisionGeometry:
- linkName: r_foot
geometricShape:
shape: cylinder
radius: 0.16
length: 0.06
origin: "0.0 0.03 0.0 1.57079632679 0.0 0.0"
- linkName: l_foot
geometricShape:
shape: box
size: 0.4 0.2 0.1
origin: "0.0 0.0 0.0 0.0 0.0 0.0"
Parameters related to the inertia parameters of a link
| Attribute name | Type | Default Value | Description |
|---|---|---|---|
assignedMasses |
Map | {} (Empty Map) | If a link is in this map, the mass found in the SimMechanics file is substituted with the one passed through this map. Furthermore, the inertia matrix present in the SimMechanics file is scaled accounting for the new mass (i.e. multiplied by new_mass/old_mass). The mass is expressed in Kg. |
assignedInertias |
Array | empty | Structure for redefining the inertia tensor (at the COM) for a given link. |
| Attribute name | Type | Default Value | Description |
|---|---|---|---|
linkName |
String | Mandatory | name of the link for which we want to set the frame |
xx |
String | empty | If defined, change the Ixx value of the inertia matrix of the link. Unit of measure: Kg*m^2 . |
yy |
String | empty | If defined, change the Iyy value of the inertia matrix of the link. Unit of measure: Kg*m^2 . |
zz |
String | empty | If defined, change the Izz value of the inertia matrix of the link. Unit of measure: Kg*m^2 . |
assignedMasses:
link1: 1
link2: 3
assignedInertias:
- linkName: link1
xx: 0.0001
- linkName: link1
xx: 0.0003
yy: 0.0003
zz: 0.0003
Sensor information can be expressed using arrays of sensor options. Note that given that the URDF still does not support an official format for expressing sensor information, this script will output two different elements for each sensor:
- a
<gazebo>element, necessary to simulate the sensor in Gazebo when loading the URDF, as documented in http://gazebosim.org/tutorials?tut=ros_gzplugins . - a more URDF-like
<sensor>element, in particular the variant supported by the iDynTree library, as documented in https://github.com/robotology/idyntree/blob/master/doc/model_loading.md .
| Attribute name | Type | Default Value | Description |
|---|---|---|---|
forceTorqueSensors |
Array | empty | Array of option for exporting 6-Axis ForceTorque sensors |
sensors |
Array | empty | Array of option for exporting generic sensors (e.g. camera, depth, imu, ray..) |
| Attribute name | Type | Default Value | Description |
|---|---|---|---|
jointName |
String | empty | Name of the Joint for which this sensor measure the ForceTorque. |
directionChildToParent |
Bool | True | True if the sensor measures the force excerted by the child on the parent, false otherwise |
sensorName |
String | jointName | Name of the sensor, to be used in the output URDF file |
exportFrameInURDF |
Bool | False | If true, export a fake URDF link whose frame is coincident with the sensor frame (as if the sensor frame was added to the exportedFrames array). |
exportedFrameName |
String | sensorName if defined jointName otherwise |
Name of the URDF link exported by the exportFrameInURDF option |
frameName |
String | empty | Name of the frame in which the sensor measure is expressed. Mandatory if exportFrameInURDF is set to yes. |
linkName |
String | empty | Name of the parent link at which the sensor is rigidly attached. Mandatory if exportFrameInURDF is set to yes. |
frameReferenceLink |
String | linkName |
link at which the sensor frame is attached (to make sense, this link should be rigidly attached to the linkName. By default referenceLink is assumed to be linkName. |
frame |
String | empty | The value of this element may be one of: child, parent, or sensor. It is the frame in which the forces and torques should be expressed. The values parent and child refer to the parent or child links of the joint. The value sensor means the measurement is rotated by the rotation component of the <pose> of this sensor. The translation component of the pose has no effect on the measurement. |
sensorBlobs |
String | empty | Array of strings (possibly on multiple lines) represeting complex XML blobs that will be included as child of the <sensor> element of type "force_torque" |
Note that for now the FT sensors sensor frame is required to be coincident with child link frame, due to URDF limitations.
| Attribute name | Type | Default Value | Description |
|---|---|---|---|
linkName |
String | Mandatory | Name of the Link at which the sensor is rigidly attached. |
frameName |
String | empty | displayName of the frame in which the sensor measure is expressed. The selected frame must be attached to the referenceLink link. If empty the frame used for the sensor is coincident with the link frame. |
frameReferenceLink |
String | linkName | link at which the sensor frame is attached (to make sense, this link should be rigidly attached to the linkName. By default referenceLink is assumed to be linkName. |
sensorName |
String | LinkName_FrameName | Name of the sensor, to be used in the output URDF file |
exportFrameInURDF |
Bool | False | If true, export a fake URDF link whose frame is coincident with the sensor frame (as if the sensor frame was added to the exportedFrames array) |
exportedFrameName |
String | sensorName | Name of the URDF link exported by the exportFrameInURDF option |
sensorType |
String | Mandatory | Type of sensor. Supported: "accelerometer", "gyroscope", "camera", "depth", "gpu_lidar", "rgbd_camera" |
updateRate |
String | Mandatory | Number representing the update rate of the sensor. Expressed in [Hz]. |
sensorBlobs |
String | empty | Array of strings (possibly on multiple lines) represeting complex XML blobs that will be included as child of the <sensor> element |
If you use extensions of URDF, we frequently want to add non-standard tags as child of the <robot> root element.
Using the XMLBlobs option, you can pass an array of strings (event on multiple lines) represeting complex XML blobs that you
want to include in the converted URDF file. This will be included without modifications in the converted URDF file.
Note that every blob must have only one root element.
| Attribute name | Type | Default Value | Description |
|---|---|---|---|
XMLBlobs |
Array of String | [] (empty array) | List of XML Blobs to include in the URDF file as children of <robot> |
By using the a .csv file it is possible to load some joint-related information from a csv file. The rationale for using CSV over YAML for some information related to the model (for example joint limits) is to use a format that it is easier to modify using common spreadsheet tools like Excel/LibreOffice Calc, that can be easily used also by people without a background in computer science.
The CSV file is loaded and parsed using the d99kris/rapidcsv library. Please refer to its documentation for supported dialects of the format.
The CSV file is formed by a header line followed by several content lines, as in this example:
joint_name,lower_limit,upper_limit
torso_yaw,-20.0,20.0
torso_roll,-20.0,20.0
The order of the elements in header line is arbitrary, but the supported attributes are listed in the following:
| Attribute name | Required | Unit of Measure | Description |
|---|---|---|---|
| joint_name | Yes | - | Name of the joint to which the content line is referring |
| lower_limit | No | Degrees | lower attribute of the limit child element of the URDF joint. Please note that we specify this limit here in Degrees, but in the urdf it is expressed in Radians, the plugin will take care of internally converting this parameter. |
| upper_limit | No | Degrees | upper attribute of the limit child element of the URDF joint. Please note that we specify this limit here in Degrees, but in the urdf it is expressed in Radians, the plugin will take care of internally converting this parameter. |
| velocity_limit | No | Degrees/second (revolute), meters/second (prismatic) | velocity attribute of the limit child element of the URDF joint. Angular velocity is converted internally from degrees/second to radians/second. |
| effort_limit | No | Newton meters | effort attribute of the limit child element of the URDF joint. |
| damping | No | Newton meter seconds / radians | damping of the dynamics child element of the URDF joint. |
| friction | No | Newton meters | friction of the dynamics child element of the URDF joint. |
For velocity_limit and effort_limit, either omit the column or leave a joint's cell empty (or whitespace-only) to leave that limit disabled for that joint. Numeric values, including zero, enable the corresponding limit. Nonempty invalid values cause an export error.
This repository is maintained by:
| @Nicogene | |
| @mfussi66 |