Usd.Stage

Introduction to UsdStage

The UsdStage is a fundamental component of the OpenUSD API, which provides a powerful framework for reading and writing USD files. USD, short for Universal Scene Description, is an open-source file format developed by Pixar Animation Studios. It allows for the efficient interchange of 3D graphics data between different applications and pipelines. The UsdStage is at the core of working with USD files, allowing users to manipulate and query the scene hierarchy, apply edits, and manage layers.

Creating a UsdStage

To begin working with a USD file, you first need to create a UsdStage. This can be done using the Usd.Stage.CreateNew() method, which creates a new, empty USD stage in memory. Alternatively, you can use the Usd.Stage.Open() method to open an existing USD file for editing. The UsdStage object represents the entire scene and provides various methods and functions to interact with it.

Scene Hierarchy and Layers

The UsdStage organizes the scene data in a hierarchical structure, similar to a file system. Each node in the hierarchy is called a Prim, which can represent various types of objects such as geometry, lights, or cameras. Prims can have child prims, forming a tree-like structure that represents the scene layout.

Layers are an essential concept in USD, as they allow for efficient collaboration and versioning of scene data. A layer represents a set of scene edits that can be applied on top of other layers. The UsdStage can have multiple layers, and each layer can contain its own set of prims and edits. This layering system enables non-destructive editing of the scene, making it easy to revert changes or apply modifications without altering the original data.

Querying and Manipulating Scene Data

With a UsdStage, you can query and manipulate various aspects of the scene. You can use the GetPrimAtPath() method to retrieve a specific prim from the stage by providing its path. Paths in USD follow a similar syntax to file system paths, using forward slashes to separate levels in the hierarchy. Once you have a reference to a prim, you can access and modify its attributes, relationships, and metadata.

The UsdStage also provides methods to traverse the scene hierarchy, allowing you to iterate over all prims or find specific prims based on criteria such as type or custom metadata. This makes it easy to perform operations on specific parts of the scene or extract relevant information.

Applying and Managing Edits

Edits in USD are represented as composition arcs between prims in different layers. These arcs define how the scene is constructed by combining information from various layers. Edits can be applied at different levels of the scene hierarchy, allowing for granular control over modifications.

The UsdStage provides methods to apply edits, such as creating new prims or modifying existing ones. You can also apply attribute value changes, add or remove relationships between prims, and edit metadata. Additionally, the UsdStage supports various edit targets, which specify the layer and path where an edit should be applied. This allows for complex editing workflows, including referencing and layering of scene data.

Collaboration and USD Variants

USD supports powerful collaboration workflows by using Variants. Variants enable multiple representations of a prim to coexist in the same scene, allowing artists and technical directors to work in parallel on different versions of a shot or asset. The UsdStage provides methods to create, edit, and switch between variants, making it easy to manage and collaborate on complex scenes.

Conclusion

The UsdStage is a key component of the OpenUSD API, providing a flexible and efficient way to read and write USD files. With its support for scene hierarchy, layers, and edits, the UsdStage allows users to query, manipulate, and manage scene data with ease. Whether you are working on a single-shot or collaborating on a complex production pipeline, the UsdStage is a powerful tool for working with USD files.