UsdReferenceSet

In Universal Scene Description (USD), references are fundamental composition operations used to construct scenes using a modular approach. They enable the reuse and assembly of content by incorporating the contents of one layer into another layer. This reuse goes beyond simple import and offers powerful overrides and variations when combined with other composition operations.

Artists can add external USD files, like assets or scene fragments, to a scene using references. This promotes reusability and flexibility, enabling the use of a single asset across multiple scenes without making destructive edits.

Example: When an artist makes a generic tree asset as a USD file, they can reference this tree in different environments or scenes. If they want to create a forest, they can reference the same tree multiple times with different overrides. This creates variation in size, color, or form, resulting in a diverse forest using just one base asset.

References facilitate layered composition and versioning by allowing localized changes without modifying the original asset file. In essence, they help efficiently manage and deploy assets in complex scenes, ensuring consistent updates and enabling targeted modifications.

To help understand how references are defined, consider referencing a simple sphere primitive from a scene file. Imagine the sphere is called blueSphere and has been defined in a file called aSphere.usda. Our simple scene file could reference the file as follows:

#usda 1.0
def "SceneRoot" {
references = @./aSphere.usda@blueSphere
}

Setting USD References

Use UsdReferenceSet to add references to your scene that refer to other prims..

Prims to contain the references are added to primPaths.

You can then browse to a USD asset file using the asset field. Once selected, the assetPrimPath is populated with the scene hierarchy for the asset, allowing you to select a prim to reference.

Once the reference has been selected, you can decide how to place the reference in relation to existing references on the prim using the listPosition dropdown. Choose to append to the end of the existing list of references, prepend to the start, or clear the existing references and replace with the ones you’re adding (reset to explicit). Alternatively, choose delete to remove the references that you’ve specified in the node parameters.

Controls

Control (UI)	Default Value	Function
primPaths	N/A	Specify locations where references are applied. References are generated at each path, following the order in which they are listed.
asset	N/A	Load a USD file to use for references. This gets converted to the "asset/path.usda" section of a full reference path: @asset/path.usda@</prim/path>
assetPrimPath	N/A	The path to the Prim to be used as a reference. All prims in the asset file are given in their scene hierarchy. If no reference file is added, you can use the prim path to a prim in the current stage. This becomes the "prim/path" part of a full reference path, in this format: @asset/path.usda@</prim/path>.
listPosition	prepend	Specifies how the references are added to the scene. Options are: append - adds the new reference(s) by positioning them at the end of the current list, ensuring they are evaluated after existing values, allowing them to potentially override preceding definitions. prepend - adds the reference(s) to the front of the list, causing them to be evaluated before, and potentially overridden by values added later or in subsequent layers. delete - removes one or more references from the list, preventing their properties from influencing the composed prim in the scene. reset to explicit - clears any existing references on the prim and sets the reference list to be only the new reference(s) you're adding. It essentially instructs the USD scene to ignore any previous references on the prim(s) and only use the new ones For more information, refer to the USD Glossary under List Editing.