On this page | |
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 Composition ▸ 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 subsequentInherit
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 |
|
Reference a prim from the output of a LOP node |
|
Reference another prim in the scene graph tree in the first input |
|
Block all existing references |
|
Block one existing reference |
|
Reference several prims from an external file |
|
USD References Explained ¶
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 ¶
Multi-input
Perform the reference operations from the multi-input.
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 New Primitives 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.)
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.
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-evaluated, with the ability to access the current Primitive Path to generate a value specific to that primitive.
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 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.
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
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.
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
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.)
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 wildcard pattern expansions.
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.
Setting this parameter to Auto
will not author a Kind on the leaf primitive where the reference is added. Instead, it will examine the Kind of the prim after setting the reference, and automatically set the Kind of ancestor prims to ensure the leaf primitive is part of a valid model hierarchy. Note that this may result in adding a Kind to ancestor prims that were not created by this node. If the referenced prim has no kind, or is not a model kind, Auto
mode will not author Kind on any prim.
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.
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-Operation, 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 undoing 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.