urdf-usd-converter 0.1.0rc1

A URDF to OpenUSD Data Converter

urdf-usd-converter

Overview

A URDF to OpenUSD Data Converter

Important: This is currently an Alpha product. See the CHANGELOG for features and known limitations.

Key Features:

• Converts an input URDF file into an OpenUSD Layer
• Supports data conversion of visual geometry & materials, as well as the links, collision geometry, and joints necessary for kinematic simulation.
• Available as a python module or command line interface (CLI).
• Creates a standalone, self-contained artifact with no connection to the source URDF, OBJ, DAE, or STL data.
  • Structured as an Atomic Component
  • Suitable for visualization & rendering in any OpenUSD Ecosystem application.
  • Suitable for import & simulation in Newton.

This project is part of Newton, a Linux Foundation project which is community-built and maintained.

Implementation Details & Dependencies

Specific implementation details are based on our URDF to USD Conceptual Data Mapping.

The output asset structure is based on NVIDIA's Principles of Scalable Asset Structure in OpenUSD.

The implementation also leverages the following dependencies:

• NVIDIA's OpenUSD Exchange SDK to author consistent & correct USD data.
• Pixar's OpenUSD python modules & native libraries (vendored via the usd-exchange wheel).
• tinyobjloader, pycollada, and numpy-stl for parsing any mesh data referenced by the input URDF datasets.

Get Started

To start using the converter, install the python wheel into a virtual environment using your favorite package manager:

python -m venv .venv
source .venv/bin/activate
pip install urdf-usd-converter
urdf_usd_converter /path/to/robot.urdf /path/to/usd_robot

See urdf_usd_converter --help for CLI arguments.

Alternatively, the same converter functionality can be accessed from the python module directly, which is useful when further transforming the USD data after conversion.

import urdf_usd_converter
import usdex.core
from pxr import Sdf, Usd

converter = urdf_usd_converter.Converter()
asset: Sdf.AssetPath = converter.convert("/path/to/robot.urdf", "/path/to/usd_robot")
stage: Usd.Stage = Usd.Stage.Open(asset.path)
# modify further using Usd or usdex.core functionality
usdex.core.saveStage(stage, comment="modified after conversion")

Specifying ROS packages

If a filename within a mesh or texture in the URDF file is specified as package://<package_name>/<path>, we must separately provide the actual path where the package is located.
<package_name> is the ROS package name and has a corresponding path. <path> is a relative path within that package path.
The package path specified for <package_name> can be either a relative path or an absolute path.
If the package path is a relative path, the path specification will be relative to this URDF file.

When the converter traces back to the parent directory with the URDF file as the current directory, if a file matching the specified path is found, the combination of the package name and path at that time is automatically used.

If the ROS package path still cannot be found, we must manually specify the path combination for the package name.

CLI

Specify the path to the package name by using the --package argument in the CLI.
We can also specify multiple packages.

When a filename is specified in an URDF file as shown below, the "robot_package" following package:// is the package name.
ROS packages are assigned either a relative path or an absolute path from the URDF relative to the package name.

  <material name="body_mat">
    <color rgba="1.0 1.0 1.0 1.0"/>
    <texture filename="package://robot_package/textures/body_image.png"/>
  </material>

When specifying the --package argument in the CLI as shown below, the actual path will be "/path/to/assets/textures/body_image.png".

urdf_usd_converter /path/to/robot.urdf /path/to/usd_robot --package robot_package=/path/to/assets

If multiple packages and paths exist, specify them as follows.

urdf_usd_converter /path/to/robot.urdf /path/to/usd_robot --package robot_package=/path/to/assets --package robot_foo=/path/to/foo

If the path contains spaces, please enclose it in double quotation marks.

Python

When specifying a list of ROS package names and paths in Python, assign the package name to the "name" key and the path to the "path" key in a dictionary.
Specify the list of packages for this package in the ros_packages argument of urdf_usd_converter.Converter.

import urdf_usd_converter
import usdex.core
from pxr import Sdf, Usd

packages = [
    {"name": "robot_package", "path": "/path/to/assets"},
    {"name": "robot_foo", "path": "/path/to/foo"},
]
converter = urdf_usd_converter.Converter(ros_packages=packages)
asset: Sdf.AssetPath = converter.convert("/path/to/robot.urdf", "/path/to/usd_robot")

Loading the USD Asset

Once your asset is saved to storage, it can be loaded into an OpenUSD Ecosystem application.

We recommend starting with usdview, a simple graphics application to confirm the visual geometry & materials are working as expected. You can inspect any of the USD properties in this application, including the UsdPhysics properties.

Tip: OpenUSD Exchange Samples provides ./usdview.sh and .\usdview.bat commandline tools which bootstrap usdview with the necessary third party dependencies.

However, you cannot start simulating in usdview, as there is no native simulation engine in this application.

To simulate this asset in Newton, call newton.ModelBuilder.add_usd() to parse the asset and add it to your Newton model.

Simulating in other UsdPhysics enabled products (e.g. NVIDIA Omniverse, Unreal Engine, etc) may provided mixed results. The rigid bodies are structured hierarchically, which maximal coordinate solvers often do not support. In order to see faithful simulation in these applications, the USD asset will need to be modified to suit the expectations of each target runtime.

Contribution Guidelines

Contributions from the community are welcome. See CONTRIBUTING.md to learn about contributing via GitHub issues, as well as building the project from source and our development workflow.

General contribution guidelines for Newton repositories are available here.

Community

For questions about this urdf-usd-converter, feel free to join or start a GitHub Discussions.

For questions about OpenUSD Exchange SDK, use the USD Exchange GitHub Discussions.

For general questions about OpenUSD itself, use the Alliance for OpenUSD Forum.

By participating in this community, you agree to abide by the Linux Foundation Code of Conduct.

References

• URDF XML Docs
• NVIDIA OpenUSD Exchange SDK Docs
• OpenUSD API Docs
• OpenUSD User Docs
• NVIDIA OpenUSD Resources and Learning

License

The urdf-usd-converter is provided under the Apache License, Version 2.0, as is the OpenUSD Exchange SDK.