nvidia-srl-usd 2.0.0

SRL Python USD utils

NVIDIA SRL USD

A Python package for USD (Universal Scene Description) utilities, providing advanced prim manipulation, world structure management, and robotics scene integration capabilities. This package integrates with NVIDIA SRL's robotics ecosystem and provides high-level wrappers for USD operations that are commonly needed in robot control, simulation, and scene management applications.

Table of Contents

• Overview
• Quick Start
• Installation
• Usage
  • 1. USD Stage Management
  • 2. Prim Operations
  • 3. World Structure
  • 4. Geometry Export
  • 5. Physics Properties
  • 6. Transform Operations
• Examples
• Development
  • Setting up development environment
  • Running Tests
  • Code Quality
  • Building Package
  • Documentation
• Configuration
• Troubleshooting
  • Common Issues
  • Debug Mode
• Performance
• License
• Support

Overview

The NVIDIA SRL USD package currently provides solutions for:

• USD stage management with efficient file loading and validation
• Prim operations for querying, filtering, and manipulating USD prims
• World structure management for robotics scenes and environments
• Geometry export capabilities for converting USD geometry to common formats
• Physics properties handling for simulation and robotics applications
• Transform operations for pose calculations and coordinate transformations

Quick Start

1. Install the package:

   pip install nvidia-srl-usd
   

2. Basic USD stage usage:

   from nvidia.srl.usd import prim_helper
   from nvidia.srl.usd import world_structure
   
   # Open a USD stage
   stage = prim_helper.open_stage("path/to/scene.usd")
   
   # Get world structure
   world = world_structure.WorldStructure(stage)
   
   # List all entity prims in the world
   entities = world.get_entity_prims()
   print(f"Found {len(entities)} entities in the world")
   

3. Prim querying example:

   from nvidia.srl.usd import prim_helper
   
   # Get all camera prims in the stage
   cameras = prim_helper.get_prims(
       stage,
       prim_types=["Camera"],
       return_path=True
   )
   print(f"Available cameras: {cameras}")
   
   # Get all prims with physics properties
   physics_prims = prim_helper.get_prims(
       stage,
       has_apis=[prim_helper.UsdPhysicsRigidBodyAPI]
   )
   print(f"Physics objects: {len(physics_prims)}")
   

4. Geometry export example:

   from nvidia.srl.usd import prim_helper
   
   # Export a prim's geometry as OBJ file
   prim = stage.GetPrimAtPath("/world/table")
   if prim_helper.is_object(prim):
       prim_helper.export_geometry_as_obj_file(
           prim,
           "table.obj",
           frame_time=0.0
       )
       print("Geometry exported successfully")
   

Installation

Prerequisites

• Python 3.7 or higher
• Gitlab access token for NVIDIA's package repository
• USD Core library (automatically installed as dependency)

Install from PYPI.org

Use pip to install this Python distribution from the PYPI package registry (https://pypi.org/project/nvidia-srl-usd/).

pip install nvidia-srl-usd

Install for Development

# Clone the repository
git clone ssh://[e-mail]:12051/srl/py/usd.git
cd usd

# Set up development environment
make init

# Activate virtual environment
source .venv/3.10-py-usd/bin/activate

Usage

1. USD Stage Management

The package provides utilities for opening and managing USD stages:

from nvidia.srl.usd import prim_helper

# Open a USD stage from file path
stage = prim_helper.open_stage("scene.usd")

# Check if stage is valid
if stage:
    print(f"Stage opened successfully: {stage.GetRootLayer().realPath}")

    # Get default prim
    default_prim = prim_helper.get_world_prim(stage)
    print(f"Default prim: {default_prim.GetPath()}")

2. Prim Operations

Query and filter prims based on various criteria:

from nvidia.srl.usd import prim_helper

# Get all prims matching a path pattern
table_prims = prim_helper.get_prims(
    stage,
    path_pattern=".*table.*",
    return_path=True
)

# Get prims by type
mesh_prims = prim_helper.get_prims(
    stage,
    prim_types=["Mesh"]
)

# Get prims with specific APIs
rigid_body_prims = prim_helper.get_prims(
    stage,
    has_apis=[prim_helper.UsdPhysicsRigidBodyAPI]
)

# Check prim properties
for prim in mesh_prims:
    if prim_helper.is_object(prim):
        print(f"Object prim: {prim.GetPath()}")
    if prim_helper.is_robot(prim):
        print(f"Robot prim: {prim.GetPath()}")

3. World Structure

Manage world scenes and robotics environments:

from nvidia.srl.usd import world_structure

# Initialize world structure
world = world_structure.WorldStructure(stage)

# Get world information
print(f"World USD path: {world.get_world_usd_path()}")
print(f"URDF root directory: {world.get_urdf_root_dir_path()}")

# Get different types of prims
world_prim = world.get_world_prim()
entity_prims = world.get_entity_prims()
object_prims = world.get_object_prims()

print(f"World prim: {world_prim.GetPath()}")
print(f"Entities: {len(entity_prims)}")
print(f"Objects: {len(object_prims)}")

# Get URDF path for a specific prim
for prim in entity_prims:
    urdf_path = world.get_urdf_path(prim)
    print(f"Prim {prim.GetPath()} -> URDF: {urdf_path}")

4. Geometry Export

Export USD geometry to common formats:

from nvidia.srl.usd import prim_helper

# Export geometry as OBJ file
prim = stage.GetPrimAtPath("/world/robot/end_effector")
if prim_helper.has_geometry(prim):
    prim_helper.export_geometry_as_obj_file(
        prim,
        "end_effector.obj",
        frame_time=0.0,
        triangulate=True
    )

# Export with specific frame time
prim_helper.export_geometry_as_obj_file(
    prim,
    "end_effector_frame_10.obj",
    frame_time=10.0
)

5. Physics Properties

Work with USD physics properties for simulation:

from nvidia.srl.usd import prim_helper

# Check if prim has physics properties
if prim_helper.has_physics_properties(prim):
    # Get mass
    mass = prim_helper.get_mass(prim)
    print(f"Mass: {mass}")

    # Get center of mass
    com = prim_helper.get_center_of_mass(prim)
    print(f"Center of mass: {com}")

    # Get inertia tensor
    inertia = prim_helper.get_inertia_tensor(prim)
    print(f"Inertia tensor: {inertia}")

# Check physics API types
if prim_helper.has_api(prim, prim_helper.UsdPhysicsRigidBodyAPI):
    print("Prim has rigid body physics")
if prim_helper.has_api(prim, prim_helper.UsdPhysicsCollisionAPI):
    print("Prim has collision properties")

6. Transform Operations

Handle transforms and poses:

from nvidia.srl.usd import prim_helper
from nvidia.srl.math.transform import Transform

# Get prim transform
transform = prim_helper.get_transform(prim, frame_time=0.0)
print(f"Transform: {transform}")

# Get prim pose
pose = prim_helper.get_pose(prim, frame_time=0.0)
print(f"Pose: {pose}")

# Set prim transform
new_transform = Transform.from_rotation_and_translation(
    rotation=[0, 0, 0, 1],  # Quaternion
    translation=[1, 2, 3]
)
prim_helper.set_transform(prim, new_transform, frame_time=0.0)

# Get transform at specific time
transform_at_time = prim_helper.get_transform(prim, frame_time=10.0)

Examples

The package includes several example scripts and test cases:

Python Examples

• Basic USD operations: tests/usd/prim_helper_test.py
• World structure: tests/usd/world_structure_test.py
• Transform operations: Various test functions in test files

Running Examples

# Run all tests (includes examples)
make test

# Run specific test file
python -m pytest tests/usd/prim_helper_test.py

# Run with coverage
make coverage

Development

Setting up development environment

1. Clone the repository:

   git clone ssh://[e-mail]:12051/srl/py/usd.git
   cd usd
   

2. Set up the Python virtual environment:

   make init
   

3. Activate the virtual environment:

   source .venv/3.10-py-usd/bin/activate
   

Running Tests

# Run all tests
make test

# Run tests with coverage
make coverage

# Run specific test file
python -m pytest tests/usd/prim_helper_test.py -v

Code Quality

# Run all code quality checks
make check

# Format code
make format

# Generate documentation
make docs

Building Package

# Build package
make package

Documentation

# Build documentation
make docs

# View documentation
open _build/docs/sphinx/html/index.html

Configuration

The package works with standard USD files and doesn't require additional configuration files. However, it integrates with:

• URDF files: Automatically locates URDF files relative to USD files
• USD schemas: Supports standard USD schemas and NVIDIA extensions
• Physics properties: Works with UsdPhysics schema for simulation

Troubleshooting

Common Issues

1. USD import errors: Ensure USD Core is properly installed

   pip install usd-core
   

2. File path errors: Verify USD file paths and permissions

   ls -la your_scene.usd
   

3. Memory issues: Large USD files may require more memory

   # Monitor memory usage
   top -p $(pgrep python)
   

4. Physics API errors: Ensure UsdPhysics schema is available

   from pxr import UsdPhysics
   # If this fails, USD installation may be incomplete
   

Debug Mode

Enable debug logging by setting the environment variable:

export LOG_LEVEL=DEBUG
python your_script.py

USD Version Compatibility

The package supports multiple USD versions:

• Python 3.11+: USD Core 25.2+
• Python 3.9-3.10: USD Core 21.11-23.8
• Python 3.7-3.8: USD Core 21.11+

Check your USD version:

from pxr import Usd
print(f"USD version: {Usd.GetVersionInfo()}")

Performance

• Stage loading: Optimized for large USD files
• Prim queries: Efficient filtering and pattern matching
• Geometry export: Fast conversion to common formats
• Memory usage: Efficient memory management for large scenes
• Transform calculations: Optimized matrix operations

License

Copyright (c) 2022-2025, NVIDIA CORPORATION & AFFILIATES. All rights reserved.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0.

Support

For issues and questions:

• Project issues: https://gitlab-master.nvidia.com/srl/py/usd/-/issues
• Documentation: Built locally with make docs
• NVIDIA Robotics: https://developer.nvidia.com/robotics
• USD Documentation: https://openusd.org/