Universal Scene Descriptor (USD) Tutorial Guide

1. Introduction to USD

USD, or Universal Scene Descriptor, is a scene description system developed by Pixar Animation Studios for the interchange of complex 3D data between different software applications. It is designed for large-scale production pipelines, allowing artists, technical directors, and developers to work with highly detailed scenes that evolve over time.

Key Objectives

• Efficient representation of complex 3D scenes.
• Support for hierarchical composition and variant selection.
• Extensible data model for arbitrary attributes.
• Fast stage loading and manipulation.

USD achieves these objectives through a combination of binary storage, layer-based composition, and a schema that maps to native 3D constructs such as prims, attributes, and relationships.

2. The USD File Structure

A USD file is a collection of layers arranged in a composition arc. Each layer can be thought of as a text or binary file that contributes to the final scene description.

Layers and Layersets

• Base Layer: The foundational description of the scene.
• Layer Edit: Local changes that override or extend the base layer.
• Layer Override: External references that modify the base layer.

Composition Arc

The composition arc resolves how layers are combined to produce the final stage. It is defined by the layerStack and the editTarget.

3. Prims and Hierarchy

In USD, everything in a scene is a prim. Prims can be primitives, like meshes and cameras, or containers, like Scope objects.

Primitives

• Mesh
• Camera
• Lights
• Material

Container Prims

• Scope
• VariantSet
• LayerOffset

Prims form a tree hierarchy. The root prim is typically /, and all other prims are nested beneath it.

4. Attributes and Relationships

Attributes store data values on prims, while relationships reference other prims.

Attributes

• Type system: double, float3, matrix4d, etc.
• Array support.
• Metadata (e.g., displayGroup).

Relationships

• References other prims by path.
• Used for connecting meshes to materials.

5. Variant Sets

Variants allow multiple configurations of a prim or subtree to coexist, facilitating work on multiple versions of an object.

Defining Variants

def Mesh "character" (
    variantSets = [
        "shading" : [
            "diffuse" : (
                "materials" = [ @material1@ ]
            ),
            "metallic" : (
                "materials" = [ @material2@ ]
            )
        ]
    ]
)

The active variant can be set via the variantSet selector in the stage.

6. References, Inherits, and Overrides

USD provides three mechanisms for reusing data:

• References: Include the full description of another prim.
• Inherits: Copy attributes from a parent prim.
• Overrides: Replace a prim with a new definition.

These mechanisms are crucial for modular pipeline design.

7. Layers and Edit Target

When a user edits a prim, the changes are written to the active layer, known as the editTarget. The edit target is typically the topmost layer in the composition arc.

Layer Stack

The layerStack is a list of layers that contribute to the stage. The order of layers determines precedence.

Layer Editing

Editing operations are recorded in the edit layer, leaving the base layers untouched.

8. The USD API

USD provides a C++ API and Python bindings for programmatic manipulation.

Core Concepts

• UsdStage: Represents the entire scene.
• UsdPrim: A node in the prim hierarchy.
• UsdAttribute: A key-value pair on a prim.

Typical Workflow

1. Open a stage: stage = Usd.Stage.Open("scene.usd")
2. Query prims: prim = stage.GetPrimAtPath("/character")
3. Read attributes: prim.GetAttribute("visibility").Get()
4. Modify attributes and save.

9. Common Pitfalls and Best Practices

• Use variantSet selectors carefully to avoid accidental overrides.
• Keep base layers immutable; perform edits in a separate layer.
• Leverage usdcat for quick inspection of large files.
• Always test the stage after composition changes.

10. Interactive USD Parser Demo

Below is a simple USD parser that visualizes the hierarchy of a USD file. Edit the sample text and press “Render” to update the tree.