USD Fundamentals#
Stages, Files and Layers#
In USD, the virtual world is called a “stage”. The stage is composed of “layers” - the USD term for “documents” (such as files that have been converted from CAD sources). Note that documents need not be file-backed– e.g., databases can also be ingested as USD layer content.
There are various places where the layers of the stage can be found in USD Explorer - primarily in the Layer Window, but also in various sections of the Property Panel.
Layers can not only define the data, but also can contain sparse overrides that can encompass work-stream outputs on top of base datasets, such as animated transforms on top of a static robot, or material assignments on top of unshaded geometry.
Prims#
In OpenUSD, a virtual world is a composed “stage” (scenegraph) of “prims” (short for “primitives”, i.e., data containers) defined in “layers” (underlying document model).
Prims are organized hierarchically.
Prims are identified by their “path”, for example: /Factory/robots/Robot_1/Geometry/Arm/bolt_1
Schemas give meaning of the properties of a prim, for example the UsdGeomMesh schema encompasses points, topology, and other information for mesh geometry.
Layers can define new prims, reference prims from other layers, and provide non-destructive, sparse overrides that preserve the integrity of referenced data.
Prim hierarchies should be structured to make them navigable for users working with significant subhierarchies of the dataset.
Prim hierarchies define spatial encapsulation (if an ancestral prim is moved, its descendants move with it in 3D space). The hierarchy is displayed in the Stage Window in USD Explorer.
Prim Types#
Some prim types like Xform are expected to have children. The descendants of Xforms accumulate the translation, rotation, and scale operations of their ancestors. Other types are more restricted. Gprim (geometry types like Mesh and Sphere) are leaves in the hierarchy. Material prims are the root of a network composed of their child Shader prims. Scope is a generic container prim used for organizating sub-hierarchies– they cannot contain transform attributes like Xform, but do pass ancestral transforms to their descendants.
Here’s a quick list of some common prim types:
Xform
Scope
Mesh
Material
Light
Camera
You can learn about these and other prim types by searching for them here.
Prims can be created by right-clicking in the Stage Window.
Prim Hierarchy#
The stage is organized into a hierarchy of prims identified by their path. Prims are containers for other “properties” and “metadata” used to populate the scene.
The hierarchy gives prims the semantics of having “parents” and “children”. For the path /Factory/robots/Robot_1/Geometry/Arm/bolt_1, robots is the “parent” of Robot_1 and Geometry is one Robot_1’s “children”. Factory would be considered an “ancestor” of Robot_1 and Arm would be a “descendant” of Robot_1.
Prim hierarchies are also utilized to compute “inherited” values for some properties, such as hierarchical visibility (marking an ancestral prim invisible will also effectively make its descendants invisible) or material assignments (binding a material to an ancestral prim can also assign that material to all its geometry descendants).
Model Hierarchy#
The “Model Hierarchy” can be thought of as a “table of contents” for the stage’s full prim hierarchy. USD uses the “kind” metadata to “highlight” important prims, such the “roots” of the individual “components” that make up the scene - robots, signage, doors, furniture, etc.
The Model Hierarchy allows for quick navigation of “important” prims in the hierarchy
There are two key kinds – “assembly models” (aggregates, e.g., a workcell) and “component models” (e.g., a robot).
USD Explorer provides kind-based selection filtering to make it easier to navigate the stage
- See this document for more on Model Hierarchy:
References#
References are used for aggregating prim hierarchies - any prim can reference one or more prims from its own layer (internal referencing) or from another layer (external referencing). Note that an ancestral prim cannot internally reference one of its own descendants. To create a reference, select a xform, scope or material prim, select “add” in the property panel and then “reference”.
Note
To reference an external layer, it is recommended that the external layer contains metadata called “defaultPrim” for one of that layer’s root prims. If that doesn’t exist, the reference can not be created unless you also specify the path of a prim within that layer. While “defaultPrim” can only point to one of the layer’s root prims, references that contain prim paths can address any prim in the layer’s hierarchy.
Payloads#
Payloads are similar to references, but in addition to referencing semantics, prims with payloads can be loaded and unloaded from memory as needed to manage the user’s working set. Unloading a payload does not persistently remove its contents from the scene embodied by its USD layer stack; it merely releases the payload from the in-memory working set for the stage.
Sublayers#
In addition to creating references, you may wish to insert a layer (“sublayer”) for workflow-specific content, for example to override positions, add lights, cameras or animation samples. This method of composing layers is called “sublayering” and it is accessed via the Layer window inside of Explorer. The order of the layers matter and layers which are higher in the stack override the contributions from layers further down.
Overs and Deltas#
All prim data such as properties and metadata can be “defined” - which means that a given layer contains a full definition of a prim, including the type, name, attributes etc. However, as elluded to in “Sublayers” above, USD layers can also store overrides, called “overs”. In Omniverse, overs are labelled as “Deltas” and they can be found in the Layer Window. Scene edits are written as deltas whenever the “Authoring Layer” of the stage is set to a different layer than the one that holds the definition of a given prim.