Reference 2.0

References the contents of a external USD files and/or layers created by other LOP nodes into a branch of the existing scene graph tree. Can also remove or replace existing references.

On this page	Overview Tips How to USD References Explained Local Variables Parameters
Since	19.5

Overview ¶

This node lets you reference a tree of primitives from a different location, into your current scene graph. These other locations can be external files, other LOP nodes, or even different primitives within the same tree. Multiple references can be made to the same source, allowing you to re-use existing primitives.

See the section References Explained for details about this USD concept.

Tips ¶

When an Action parameter is set to Create New Primitives, the Primitive path must specify a single primitive path. This parameter is re-evaluated for each reference being created, and if necessary will be made unique by appending a numeric suffix.
When an Action parameter is set to Edit Existing Primitives, the Primitive path is interpreted as a primitive pattern. The reference is added to every primitive that matches the pattern.
If the prim you specify to reference onto already has existing references, the new reference will be composed with any existing references. See the Pre-operation parameter for how to clear existing references before adding a new one.
The reference operations specified on this node are performed in order, so multiple references can be added to a single primitive. For example, a Create action for the multi-input might create a some new primitives, then a subsequent Inherit operation can add an inherit arc to each of these newly created reference primitives.

How to ¶

The “target” that gets referenced onto a primitive in the scene graph tree is often in an external file, however this node can also reference a prim in the output of another LOP node.

To...	Do this
Reference a prim in an external file	Set the Primitive path to the scene graph path at which the referenced prim should be attached. Set the Reference type to “Reference files” or “Payload files” (see payloads for more information). Set the File pattern to the file path of the USD file to reference in. This file path can include wild cards to match multiple files on disk, in which case a new primitive will be created for each matching file. In addition to standard wildcard matching, the File pattern parameter can contain the special token `<LASTMATCH>`. When appearing after a path component with a wildcard, this token will be set to the value used to fill in that wildcard component. So if the file `/tmp/assets/Book/Book.usd` exists on disk, a Reference path of `/tmp/assets//<LASTMATCH>.usd` will find the `Book.usd` layer. This token is very useful when your asset naming conventions involve a USD file that matches the parent directory name. Use the Reference primitive* pop-up menu if you want to choose the prim in the external file to load in. Usually you can leave Reference primitive set to “Reference automatically chosen primitive”. If you want to import a specific prim, change Reference primitive to “Reference specific primitive” and enter the prim path in Reference primitive path.
Reference a prim from the output of a LOP node	Connect the LOP node containing the stage you want to reference to this node’s multi-input. The Primitive path will be re-evaluated for each connected input, and can include local variables which will generate a separate primitive for each input connection. For a single addition, you can set the Reference primitive path to the prim to import. If you have multiple inputs connected to this node’s multi-input: You can explicitly specify the destination primitive which will hold the reference using the table at the bottom of the parameter interface. This table can also be used to specify a different times to reference each input, and a specific primitive to reference from each input. You can set Reference primitive path to a scene graph path to import from the same prim in all inputs, or write an expression which is evaluated from each input connected to this node’s multi-input. In the expression, you can use the `@input` local variable (`$IIDX` is deprecated) for the current input index (starting at `1`). (Remember that in string parameters, you must enclose expressions in backticks.)
Reference another prim in the scene graph tree in the first input	Set the Primitive path to the scene graph path at which the referenced prim should be attached. Set the Reference type to “Reference from first input”, “Inherits from first input”, or “Specialize from first input”, depending on the type of composition you want. See inherits and specializes for more information about how these choices differ from a simple reference. Set Reference primitive to “Reference specific primitive”. Set Reference primitive path to the scene graph path of the prim you want to reference in.
Block all existing references	Set the Primitive path to the scene graph path of the prim that currently has a reference you want to block. Set the Pre-operaiton menu to “Clear all references”.
Block one existing reference	Set the Primitive path to the scene graph path of the prim with the reference you want to remove. Set the parameters to specify the reference you want to remove. For example, if you want to remove a reference to the file `lamp.usd`, set Reference type to “Reference files” and File pattern to `lamp.usd`. Set Reference operation to “Remove references”.
Reference several prims from an external file	Set the Reference type to “Reference files” or “Payload files” (see payloads for more information). Set the File pattern to the file path of the USD file to reference in. This file path can include wild cards to reference primitives from several files with one node. Set the Reference primitive to `Reference Specific Primitive`. Set the Reference primitive path to `/` to reference every root primitive from every file. Set the Primitive path* to /`strcat(@sourcename, @primpath)`.

USD References Explained ¶

Referencing takes the tree in the referenced file and “injects” it onto a branch in the current tree.

For example, if you start with this tree:

Scene tree before reference


/Lights/
    light1
    light2
/Models/
    tableside_lamp

If /Models/tableside_lamp references lamp.usd and that file contains:

Contents of lamp.usd


/lamp/
    base
    bulb
    shade
    socket
    switch

Then after referencing the file, the tree will look like this

Scene tree after reference


/Lights/
    light1
    light2
/Models/
    tableside_lamp/
        base
        bulb
        shade
        socket
        switch

The prim containing the reference (/Models/tableside_lamp) and the referenced prim (/lamp from lamp.usd) are composed together (with overlapping property values decided by opinion strength), but the prim keeps the name of the original referencing prim.
When you reference in content, you must specify a prim in the referenced file (/lamp in the example above), and that prim cannot be the root (/). So when you're creating a file that is meant to be referenced in by other layers, you should organize the contents under a single root primitive.

(It’s possible to specify the default primitive of a file. If you reference a file and don’t specify a specific prim in the file, you get the file’s “default primitive”.)

Referencing is useful to re-use smaller individual assets into a larger scene. In particular, referencing is the only way to load the same layer file more than once at different scene graph locations. (Because sublayering works on the entire tree, sublayering the same file more than once would have no effect.)

Simple trash can asset

#usda 1.0
(
   defaultPrim = "TrashCan"
)

def Xform "TrashCan" (
   kind = "component"
)
{
   def Cylinder "Can"
   {
       token axis = "Y"
       bool doubleSided = 0
       double height = 2
       double radius = 1
   }
}

File which references the trash can asset 3 times, for 3 different rooms in a set

#usda 1.0
()

def Xform "Scene"
{
   def Xform "Set"
   {
       def "BathroomTrashCan" (
           append references = @./trashcan.usda@
       )
       {
           double3 xformOp:translate = (2, 0, 1.4)
           uniform token[] xformOpOrder = ["xformOp:translate"]
       }

       def "KitchenTrashCan" (
           append references = @./trashcan.usda@
       )
       {
           double3 xformOp:translate = (16.01, 5, -43.072)
           uniform token[] xformOpOrder = ["xformOp:translate"]
       }

       def "OfficeTrashCan" (
           append references = @./trashcan.usda@
       )
       {
           double3 xformOp:translate = (-7.12, 0, 11.9)
           uniform token[] xformOpOrder = ["xformOp:translate"]
       }
   }
}

The Reference LOP and Stage Manager LOP create references. The Graft Stages LOP is similar, but instead of referencing from a file, it inserts a branch into the scene graph tree from elsewhere in the LOP network.

Local Variables ¶

@sourcename

The name of the file on disk (with the extension removed) or connected input to be referenced. Only set when the Parameter order is File Pattern Evaluated Before Primitive Path.

@sourcepath

The full path of the file on disk or connected input to be referenced. Only set when the Parameter order is File Pattern Evaluated Before Primitive Path.

@sourceindex

An incrementing number for each connected input or file being referenced by this node. Only set when the Parameter order is File Pattern Evaluated Before Primitive Path.

@sourceprim

An incrementing number for the current multi-input connection or file if it is being referenced multiple times. Only set when the Parameter order is File Pattern Evaluated Before Primitive Path.

@sourcenumprim

The total number of times the current multi-input connection or file will be referenced. Only set when the Parameter order is File Pattern Evaluated Before Primitive Path.

@prim

An incrementing number for each reference created by this node, or for each prim to which a reference is being added. Available with any Parameter order setting.

@primpath

The full path of the prim to which a reference is being added. Only set when the Parameter order is Primitive Path Evaluated Before File Pattern.

Parameters ¶

References From Multi-input

Enable

Perform the reference operations from the multi-input.

Parameter Order

Set this parameter to File Pattern Evaluated Before Primitive Path to allow the use of wild cards in the File pattern parameter. For each matching file the Primitive path will be evaluated to generate the path of the primitive that should reference the file.

Set this parameter to Primitive Path Evaluated Before File Pattern to author a single reference on each of a set of prims, where the referenced file or prim can be a function of the prim path that will be holding the reference. For each prim matching the Primitive path, the File pattern and Reference primitive path parameter is re-evalauted, with the ability to access the current Primitive path to generate a value specific to that primitive.

Primitive Path

In create mode, this parameter specifies a single primitive path. This is the scene graph path where the referenced branch will be attached. If this prim doesn’t exist, the node will create it. In edit mode, this parameter is a primitive pattern that will be matched against the existing primitives on the stage connected to this node’s first input. You can use local variables to control the reference primitive path.

Action

Whether this node should create new prims for the multi-input connections, or edit existing prims. Create mode will also edit a prim if it already exists, but a unique primitive name will be created automatically for each reference created for each multi-input connection. Edit mode allows for adding references to any number of existing prims.

Primitive Count

In create mode, the number of referencing primitives to create for each multi-input connection.

Reference Type

The type of composition arc to create to the referenced prim.

Reference Inputs

Reference in a prim from the multi-input connections.

Payload Inputs

Reference in a prim from the multi-input connections as a payload.

Make Instanceable

Mark the new or modified prims as instanceable (as in “native instancing”). This saves memory if you reference the same branch into multiple places, but makes the descendants of the referenced prim not editable. If this option is off, the prims are not explicitly marked as not instanceable. Instead, the current instanceable value on each prim is left unchanged.

Reference Primitive

Controls which prim to import from the multi-input connections.

Reference Automatically Chosen Primitive

If the referenced input connection has a default primitive set, use that. If there is no default prim, use the first Xform prim at the root. If there is no Xform prim at the root, use the first root prim of any type.

Reference Default Primitive

If the referenced input connection has a default primitive set, use that. If not, display a warning on this node.

Reference Specific Primitive

Reference in the scene graph path in the Reference primitive path parameter. In this mode the reference primitive specified in each row of the input table takes precedence over the value in the Reference primitive path parameter.

Reference Primitive Path

The scene graph path of the prim in the referenced layer that that is composed onto the stage. Contents of the referenced layer outside of this referenced primitive path will not appear on the composed stage. This parameter is only used if the Reference primitive parameter is set to “Reference specific primitive”.

(If you set this field automaticPrim or defaultPrim, it mimics the behavior of setting Reference primitive to “Reference automatically chosen primitive” or “Reference default primitive”.)

File and Internal References

Number of References

This node can add multiple references to external files and primitives already in the scene, each of which can be controlled separately.

Enable

Perform the reference in this instance of the multi-parm.

Primitive Path

Action

Whether this node should create new prims for the multi-input connections, or edit existing prims. Create mode will also edit a prim if it already exists, but a unique primitive name will be created automatically for each reference created for this multiparm instance. Edit mode allows for adding references to any number of existing prims.

Primitive Count

In create mode, the number of referencing primitives to create for this multiparm instance.

Reference Type

The type of composition arc to create to the referenced prim.

Reference File

Reference in a prim from an external USD file.

Payload File

Reference in a prim from an external USD file as a payload.

Reference From First Input

Reference in another prim from the scene graph tree in the first input.

Inherit From First Input

Create an “inherits” composition arc to another prim from the scene graph tree (in the first input). The inherit target need not exist yet.

Specialize From First Input

Creates a “specializes” composition arc to another prim from the scene graph tree (in the first input). The specialize target need not exist yet.

Make Instanceable

File Pattern

When Reference type is “Reference file” or “Payload file”, the file path to the file to reference. This parameter can contain wildcards, in which case every matching file found on disk will be added as a separate reference. In create mode, this will create a new primitive for each matching file. In edit mode, all matching files will be referenced onto every primitive matching the Primitive path pattern.

When specifying file paths with spaces (whether that path contains wildcard characters or not), each such file must be enclosed in quotes. This parameter value is first split into tokens (separated by whitespace, accounting for quotation marks), and then each token is expanded if it has wildcard characters, or treated as a simple file path if it does not contain any wildcards. Simple file paths will be added as references even if there is no matching file found on disk.

Wildcard pattern expansions are cached so the disk is only scanned for files the first time a given pattern is expanded on this node. This wildcard expansion cache can be cleared by hitting the Reload files button.

Reference Primitive

When Reference type is “Reference file” or “Payload file”, this controls which prim to import from the external file.

Reference Automatically Chosen Primitive

If the referenced file has a default primitive set, use that. If there is no default prim, use the first Xform prim at the root. If there is no Xform prim at the root, use the first root prim of any type.

Reference Default Primitive

If the referenced file has a default primitive set, use that. If not, display a warning on this node and ignore this instance of the multi-parm.

Reference Specific Primitive

Reference in the scene graph path in the Reference primitive path parameter.

Reference Primitive Path

When Reference type is “from first input”, or Reference primitive is “Reference specific primitive”, this is the scene graph path to the prim to reference in.

Time Offset (in Frames)

Offsets all time samples from the file or target primitive on the first input. You can use this to re-time animations in the references file.

Time Scale

Scales all time samples from the file or target primitive on the first input. You can use this to re-time animations in the references file.

Reload Files

Click to reload the contents of all files imported by this node. This also clears the cache of file wilrdcard pattern expansions.

Composition

Handle Missing Files

If the reference is to an external file, this controls what the node does if the referenced file does not exist.

Error for Missing Files

The node errors, preventing cooking the rest of the network.

Warn for Missing Files

The node shows a warning, then passes through the first input unchanged.

Ignore Missing Files

The node silently ignores the missing file, and passes through the first input unchanged.

Allow Missing Files on the Stage

Author the reference to the sublayer even if it currently doesn’t exist. This node and the following nodes will probably print warnings from the USD libraries about missing files.

Pre-Operation

If you set this to a value other than “No pre-opertation”, the node clears existing references on the node.

No Pre-Operation

Do not clear existing references on the prim at Primitive path.

Clear Reference Edits in Active Layer

Clear any additions or removals to the list of references on this prim made in the currently active layer.

This is not a non-destructive USD edit. It’s more like undo-ing any changes from previous nodes that are currently “pending” in the active layer.

Clear All References

Authors an override of the specified reference type which masks all existing references on this primitive, regardless of the layer in which they were authored. This provides a blank slate so that only the references specified by this node will remain.

Reference Operation

How new references added by this node interact with existing references on the prim at Primitive path.

When editing references on a primitive, you are really making edits to a list. These edits are expressed as adding to the beginning or the end of the list created by composing all weaker layers, or by explicitly removing certain items from the list.

Add as Strongest References in Prepend List

Make new references stronger than any references from lower layers, and stronger than any previous “prepend” edits in the currently active layer.

Add as Weakest References in Prepend List

Make new references stronger than any references from lower layers, but weaker than any previous “prepend” edits in the currently active layer.

Add as Strongest References in Append List

Make new references weaker than any references from lower layers, but stronger than any previous “append” edits in the currently active layer.

Add as Weakest References in Append List

Make new references weaker than any references from lower layers, and weaker than any previous edits in the currently active layer.

Remove References

The layers or primitives referenced by this node are removed from the list of references on the destination primitive rather that being added.

Because this removal is expressed as a list edit, you can selectively remove specific layers from the list of references, no matter what layer authored the original reference.

Created Primitives

Primitive Kind

If the prim at Primitive path doesn’t exist, this node will create it. If it has to create the prim, it will set it to have this kind.

Parent Primitive Type

If the prim at Primitive path doesn’t exist, this node will create it. If it has to create the prim, it will give any intermediate prims it has to create this type.

Primitives

In edit mode, the node has this parameter to specify any number of existing primitives. This lets you specify the prim(s) the node should operate on. You can click the select button beside the text box to select the primitives from the scene graph tree. You can also use primitive patterns for advanced matching, including matching all prims in a collection.

Primitive Path

In create mode, the node has this parameter to specify a single primitive path. This is the scene graph path where the referenced branch will be attached. The referenced prim will be overlayed onto this prim, and the referenced prim’s descendants will become this prim’s descendants. If this prim doesn’t exist, the node will create it.

Action

Whether this node should create a new prim, or edit existing prims. Create mode will also edit a prim if it already exists, but only a single prim can be specified in that mode. Edit mode allows for adding references to any number of prims with one node.

Make Instanceable