Implementing an Open-Source USD Renderer in Python

Integrate USD File Rendering into Your Python Package Without Omniverse

Key Takeaways

• Robust USD Handling: Utilize the Pixar USD Python API to effectively manage and manipulate USD files within your Python package.
• High-Performance Rendering: Leverage Hydra-compatible open-source renderers like HdStorm for efficient and scalable rendering solutions.
• Minimal Setup: Implement a straightforward minimal example to quickly integrate and test USD rendering capabilities in your project.

Introduction

Universal Scene Description (USD) is a powerful framework developed by Pixar for the interchange of 3D graphics data. It is widely used in various industries for complex scene representation and collaboration. Integrating USD rendering capabilities into a Python package opens up numerous possibilities for developers working with 3D graphics, simulations, and visualizations.

While NVIDIA's Omniverse provides a comprehensive suite for working with USD files, there are robust open-source alternatives available that do not rely on Omniverse. This guide will walk you through the process of incorporating an open-source USD renderer into your Python package, complete with a minimal example to get you started.

Setting Up the Environment

Installing the USD Python API

The Pixar USD Python API, accessible via the pxr module, is essential for handling USD files in Python. You can install it using pip:

pip install usd-core

If more advanced features are required, consider building USD from source. Detailed instructions are available in the USD GitHub Repository.

Installing Hydra-Compatible Renderers

Hydra is USD's high-performance rendering architecture that supports various backends. One of the most commonly used open-source Hydra renderers is HdStorm. To utilize Hydra renderers, ensure that your environment has the necessary dependencies:

• Ensure OpenGL is installed on your system.
• For Vulkan support, install the appropriate Vulkan libraries.
• Other dependencies may be required based on the chosen Hydra renderer.

Creating and Managing USD Stages

Creating a New USD Stage

A USD stage is the fundamental container for all scene data. You can create a new stage or load an existing one using the USD Python API:

from pxr import Usd, UsdGeom

# Create a new USD stage
stage = Usd.Stage.CreateNew('example.usda')
stage.SetDefaultPrim(UsdGeom.Xform.Define(stage, '/Root').GetPrim())

Adding Primitives to the Stage

Once the stage is created, you can add various primitives like spheres, cameras, and lights. Here's how to add a simple sphere to the stage:

from pxr import Gf

# Define a sphere primitive
sphere = UsdGeom.Sphere.Define(stage, '/Root/Sphere')
sphere.GetRadiusAttr().Set(2.0)

# Set the sphere's color
sphere.CreateDisplayColorAttr([(1, 0, 0)])  # Red color

# Save the stage to file
stage.Save()

Loading an Existing USD Stage

If you already have a USD file, you can load it as follows:

# Load an existing USD stage
stage = Usd.Stage.Open('example.usd')

Configuring the Renderer

Setting Up Hydra with HdStorm

HdStorm is an open-source GPU renderer integrated with Hydra. To set it up, you need to define render settings and specify HdStorm as the renderer plugin:

from pxr import UsdRender, Gf

# Define render settings
render_settings = UsdRender.Settings.Define(stage, '/Render/Settings')
render_settings.CreateResolutionAttr().Set(Gf.Vec2i(1024, 768))
render_settings.CreatePixelAspectRatioAttr().Set(1.0)
render_settings.CreateAspectRatioConformPolicyAttr().Set("expandAperture")

# Define render product
render_product = UsdRender.Product.Define(stage, '/Render/Product')
render_product.CreateProductTypeAttr().Set("raster")
render_product.CreateNameAttr().Set("output.png")
render_product.CreateResolutionAttr().Set(Gf.Vec2i(1024, 768))

# Set up camera
from pxr import UsdGeom

camera = UsdGeom.Camera.Define(stage, '/Render/Camera')
camera.CreateFocalLengthAttr().Set(50.0)
camera.CreateHorizontalApertureAttr().Set(36.0)
camera.CreateClippingRangeAttr().Set(Gf.Vec2f(0.1, 1000.0))

Initializing the Hydra Renderer

After defining the render settings and products, initialize the Hydra renderer plugin:

from pxr import UsdRender

# Initialize HdStorm renderer
renderer = UsdRender.RendererPlugin.Find("HdStormRendererPlugin")
if renderer:
    renderer.Render(stage, "/Render/Settings")
else:
    print("HdStormRendererPlugin not found.")

Ensure that the HdStorm renderer is installed and accessible in your environment. If not, you may need to install additional packages or dependencies.

Minimal Python Example

Below is a complete minimal Python example that demonstrates how to create a USD stage, add a sphere, configure render settings, and render the scene using HdStorm:

from pxr import Usd, UsdGeom, Gf, UsdRender

def create_usd_stage(file_path):
    """Creates a new USD stage with a simple sphere."""
    stage = Usd.Stage.CreateNew(file_path)
    stage.SetDefaultPrim(UsdGeom.Xform.Define(stage, '/Root').GetPrim())
    
    # Add a sphere
    sphere = UsdGeom.Sphere.Define(stage, '/Root/Sphere')
    sphere.GetRadiusAttr().Set(2.0)
    sphere.CreateDisplayColorAttr([(1, 0, 0)])  # Red color
    
    # Save the stage
    stage.Save()
    print(f"USD stage saved to {file_path}")
    return stage

def configure_renderer(stage):
    """Configures render settings for HdStorm renderer."""
    # Define render settings
    render_settings = UsdRender.Settings.Define(stage, '/Render/Settings')
    render_settings.CreateResolutionAttr().Set(Gf.Vec2i(1024, 768))
    render_settings.CreatePixelAspectRatioAttr().Set(1.0)
    render_settings.CreateAspectRatioConformPolicyAttr().Set("expandAperture")
    
    # Define render product
    render_product = UsdRender.Product.Define(stage, '/Render/Product')
    render_product.CreateProductTypeAttr().Set("raster")
    render_product.CreateNameAttr().Set("output.png")
    render_product.CreateResolutionAttr().Set(Gf.Vec2i(1024, 768))
    
    # Set up camera
    camera = UsdGeom.Camera.Define(stage, '/Render/Camera')
    camera.CreateFocalLengthAttr().Set(50.0)
    camera.CreateHorizontalApertureAttr().Set(36.0)
    camera.CreateClippingRangeAttr().Set(Gf.Vec2f(0.1, 1000.0))
    
    stage.Save()
    print("Render settings configured.")
    
def render_scene(stage):
    """Renders the USD stage using HdStorm renderer."""
    renderer = UsdRender.RendererPlugin.Find("HdStormRendererPlugin")
    if renderer:
        renderer.Render(stage, "/Render/Settings")
        print("Rendering completed.")
    else:
        print("HdStormRendererPlugin not found.")
        
if __name__ == "__main__":
    usd_file = "minimal_example.usda"
    stage = create_usd_stage(usd_file)
    configure_renderer(stage)
    render_scene(stage)

Explaining the Example

1. Creating the Stage: The create_usd_stage function initializes a new USD stage, adds a sphere primitive with a specified radius and color, and saves the stage to a file.

2. Configuring Render Settings: The configure_renderer function defines the rendering parameters such as resolution, aspect ratio, and camera settings. It sets up the render product which specifies the output file and format.

3. Rendering the Scene: The render_scene function initializes the HdStorm renderer and invokes the rendering process. It checks whether the HdStorm renderer plugin is available and proceeds to render the scene based on the defined settings.

Advanced Features

Adding Materials and Lighting

To create more realistic scenes, you can add materials and lighting to your USD stage:

from pxr import UsdShade

# Define a material
material = UsdShade.Material.Define(stage, '/Root/Materials/RedMaterial')
shader = UsdShade.Shader.Define(stage, '/Root/Materials/RedMaterial/Shader')
shader.CreateIdAttr("UsdPreviewSurface")
shader.CreateInput("diffuseColor", Sdf.ValueTypeNames.Color3f).Set((1, 0, 0))
material.CreateSurfaceOutput().ConnectToSource(shader, "surface")
sphere.GetPrim().GetRelationships().AddTarget(material.GetPath())

Custom Render Delegates

Hydra's modular architecture allows for custom render delegates. You can create or integrate your own render delegate to extend rendering capabilities or optimize performance for specific use cases.

# Example of integrating a custom render delegate
from pxr import UsdImaging

custom_delegate = UsdImaging.Engine()
custom_delegate.SetRenderParams({"customParam": value})
custom_delegate.Render(stage.GetPseudoRoot())

Handling Complex Scenes

For large and complex scenes, consider implementing scene partitioning, level of detail (LOD) management, and efficient data streaming to optimize rendering performance.

Displaying Rendered Output

Using usdview for Visualization

USD comes with a built-in tool called usdview which allows you to interactively visualize and explore USD stages:

usdview minimal_example.usda

This tool provides a graphical interface to navigate through the scene, inspect hierarchies, and view render outputs.

Integrating with Other Visualization Tools

For more advanced visualization needs, consider integrating with other tools like Blender or custom OpenGL applications. These integrations can offer enhanced rendering features, real-time interaction, and support for complex shaders.

# Example: Exporting USD to Blender
import bpy

# Import USD as a geometry node in Blender
bpy.ops.wm.usd_import(filepath='minimal_example.usda')

Conclusion

Integrating an open-source USD renderer into your Python package empowers you to handle complex 3D scenes efficiently without relying on proprietary solutions like Omniverse. By leveraging the Pixar USD Python API and Hydra-compatible renderers such as HdStorm, you can create robust rendering pipelines tailored to your project's needs.

This guide provided a comprehensive overview, from setting up the environment and managing USD stages to configuring render settings and implementing a minimal example. By following these steps, you can establish a solid foundation for further expansion and customization, enabling sophisticated rendering capabilities in your Python applications.

References

github.com

USD GitHub Repository

pypi.org

USD Core Python Package

openusd.org

USD Tutorials — Universal Scene Description Documentation

openusd.org

Rendering with USD - Universal Scene Description

github.com

Pixar USD Python API · kiryha/Houdini Wiki - GitHub

github.com

ColinKennedy/USD-Cookbook: USD Example Projects - GitHub