urdf-usd-converter 0.1.0a2

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")

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.