URDF Importer

Background Resources:

Basic use

Running the importer

URDF files can be imported into a Vortex assembly file using the URDF import tool. The tool takes the form of a python script, compatible with python 3.8, and can be used from the command line, or as part of your own python scripts. For a step-by-step guide, see the ROS2 Tutorial 4: Importing URDF files. 

From the command line:

 The script is located at: <Vortex_install_dir>\bin\vxurdf\urdf_to_vxassembly.py. The script can then be run via:

> <python38> <script location>\urdf_to_vxassembly.py --input_urdf <path_to_urdf_input> --output_vxassembly <path_to_vxassembly_output> --package_directory <path_to_package>

where <python38> is either your python 3.8 command (e.g., just python), or the location of the python 3.8 executable, <script location> is the location and name of the python script to be run, in this case, the URDF to VxAssembly import script, and after installing Vortex, is: <Vortex_install_dir>\bin\vxurdf. 

The flags --input_urdf, --output_vxassembly and --package_directory can be shortened to -i, -o and -p respectively.

The location and name of the URDF file to be imported is denoted by: <path_to_urdf_input>, and the name and location of the output VxAssembly file is represented by <path_to_vxassembly_output>. 

In the case of there being extra graphical assets, such as meshes, the importer will create a .vxgraphicgallery file, linked to the assembly. This file contains the graphical assets imported from the URDF package, and will be saved in the same place as, and titled the same as, the output_vxassembly, but has the vxgraphicgallery file extension.

The location of the complete URDF package, including graphical assets, is provided by <path_to_package>. If <path_to_package> is not provided, and the URDF requires external graphical assets, it will search the directory containing the URDF file itself.

Note that:

• The input path can be an absolute path, or a relative path which is given relative to the current command line directory. 
• The directory for the output VxAssembly file must already exist, a new directory will not be created during import.
• The help command --h or --help can be used after the script to obtain detailed descriptions of the arguments and their requirements

From a python script

Upon installation of Vortex, the location of the Vortex.py script was added to the PYTHONPATH, to allow the use of 'import Vortex' in your python scripts. The URDF import script is contained in a folder in the same place, and the URDF to VxAssembly import function can be accessed via:

# Import the urdf_to_vxassembly function from urdf_to_vxassembly.py
from vxurdf.urdf_to_vxassembly import urdf_to_vxassembly

# Call the function
urdf_to_vxassembly(urdf_filename='inputfile.urdf', vxassembly_filename='outputfile.vxassembly', package_directory=None, application=None)

The same validation of file names and locations as is done using the command line, will also be performed after calling the function in a script, and, as before, both absolute and relative paths can be used. The package_directory variable is optional, and the application variable allows an instance of the Vortex application, (Vortex.VxApplication()) to be supplied to the import script. This is not required, but, as the importer does create an instance of the application, and only one application may exist, it is possible to send in an instance if one wishes to use the importer as part of a larger script. 

Limitations

The URDF standard has a number of limitations and these are reflected in the importer. Once a URDF file is imported however, it is an assembly available to be manipulated in the same ways any Vortex assembly can be. The URDF standard is described in this URDF standard link and the limitations of what it can describe are explained in detail.

The current version of the URDF import script has a number of further limitations, listed here:

• Currently, only the <robot>, <link> and <joint> tags are supported. Other tags which are part of the specification will notify the user that they are not supported during import, and will not affect the final VxAssembly created from the supplied URDF file. In particular, the importer does not utilize the information from <sensor>, <transmission> or <gazebo> tags. 
• The following subtags of <joint> are not supported, and their corresponding information is not utilized, as they have no simple analogue within Vortex:
  • <calibration>
  • <mimic>
  • <safety_controller>
  • The <velocity> subtag of <limit> is also not supported.
• The following subtags of <link> are not supported, and their corresponding information is not utilized:
  
  • The <mesh> subtag of <geometry> - currently, the importer only supports collections of primitive (sphere, cylinder and box) collision geometries.
• Vortex also requires a mass for each link. If no mass is provided, Vortex will initialize the object with the default mass of a part in Vortex (1kg mass, and a diagonal inertia matrix with entries of 0.4kgm² )

Model Mapping

The following table contains a summary of the data from the URDF file which the importer uses, and how this data is used in Vortex. The URDF variables are arranged in their xml hierarchy to make tags and subtags easily visible. The Vortex equivalent variables can be found in the Vortex Editor inspector when the relevant constraint or part is selected. The exceptions to this are the constraint type and collision geometry type, which are selected before the object is added to the assembly. These mappings are documented in further detail in source code comments if more information is required.

Troubleshooting

There are a number of warning and error messages designed to help you discover problems with your URDF import process if the process fails for some reason. Warning messages are simply warnings, the import will proceed regardless, but the warnings inform you if data may be lost, or remain unused for some reason. Exceptions stop the import process, these will usually only appear if the URDF input file has an error in it. 

Example warning messages

'Tag: --, unsupported in Vortex Assembly import

'Attribute: --, unsupported in Vortex Assembly import

Example exceptions

"Invalid -- tag: --"

"Invalid -- type: --"

"Required -- not set in XML: --"

"The version attribute should be in the form 'x.y'"
"Empty major or minor number is not allowed"
"Version number must be positive"

"Multiple roots detected, invalid URDF."
"No roots detected, invalid URDF."