Add a Reference

A Reference is a composition arc that enables users to aggregate layers or assets onto a Stage. A Reference targets a prim from a layer and loads it and all of its descendants into a new namespace within the referencing layer. This snippet shows how to create and add a Reference to a prim. A single prim can have multiple References.

USD Python

With the USD API, you can use Usd.Prim.GetReferences() to receive the references and add a new one with Usd.References.AddReference().

from pxr import Usd, Sdf

def add_int_reference(prim: Usd.Prim, ref_target_path: Sdf.Path) -> None:
    references: Usd.References = prim.GetReferences()
    references.AddInternalReference(ref_target_path)

def add_ext_reference(prim: Usd.Prim, ref_asset_path: str, ref_target_path: Sdf.Path) -> None:
    references: Usd.References = prim.GetReferences()
    references.AddReference(
        assetPath=ref_asset_path,
        primPath=ref_target_path # OPTIONAL: Reference a specific target prim. Otherwise, uses the referenced layer's defaultPrim.
    )


#############
# Full Usage
#############
from pxr import UsdGeom

# Create new USD stage for this sample
stage: Usd.Stage = Usd.Stage.CreateInMemory()

# Create and define default prim, so this file can be easily referenced again
default_prim = UsdGeom.Xform.Define(stage, Sdf.Path("/World"))
stage.SetDefaultPrim(default_prim.GetPrim())

# Create an xform which should hold all references in this sample
ref_prim: Usd.Prim = UsdGeom.Xform.Define(stage, Sdf.Path("/World/ref_prim")).GetPrim()

# Add an internal reference
intern_target_path: Sdf.Path = Sdf.Path("/World/intern_target")
target_prim: Usd.Prim = UsdGeom.Xform.Define(stage, intern_target_path).GetPrim()
add_int_reference(ref_prim, intern_target_path)

# Add an external reference to specific prim
add_ext_reference(ref_prim, "C:/path/to/file.usd", Sdf.Path("/World/some/target"))

# Add other external reference to default prim
add_ext_reference(ref_prim, "C:/path/to/other/file.usd", Sdf.Path.emptyPath)

usda = stage.GetRootLayer().ExportToString()
print(usda)

# Get a list of all prepended references
references = []
for prim_spec in ref_prim.GetPrimStack():
    references.extend(prim_spec.referenceList.prependedItems)

# Check that the reference prim was created and that the references are correct
assert ref_prim.IsValid()
assert references[0] == Sdf.Reference(primPath=intern_target_path)
assert references[1] == Sdf.Reference(assetPath="C:/path/to/file.usd", primPath=Sdf.Path("/World/some/target"))
assert references[2] == Sdf.Reference(assetPath="C:/path/to/other/file.usd")

Python Kit Commands

The AddReference command in Kit can add internal and external references to a prim.

import omni.kit.commands
from pxr import Usd, Sdf

def add_int_reference(prim: Usd.Prim, ref_target_path: Sdf.Path) -> None:
    omni.kit.commands.execute("AddReference",
        stage=prim.GetStage(),
        prim_path = prim.GetPath(), # an existing prim to add the reference to.
        reference=Sdf.Reference(
            primPath = ref_target_path
        )
    )

def add_ext_reference(prim: Usd.Prim, ref_asset_path: str, ref_target_path: Sdf.Path) -> None:
    omni.kit.commands.execute("AddReference",
        stage=prim.GetStage(),
        prim_path = prim.GetPath(), # an existing prim to add the reference to.
        reference=Sdf.Reference(
            assetPath = ref_asset_path,
            primPath = ref_target_path
        )
    )


#############
# Full Usage
#############
import omni.usd
from pxr import UsdGeom

# Create new USD stage for this sample in OV
context: omni.usd.UsdContext = omni.usd.get_context()
success: bool = context.new_stage()
stage: Usd.Stage = context.get_stage()

# Create and define default prim, so this file can be easily referenced again
default_prim = UsdGeom.Xform.Define(stage, Sdf.Path("/World"))
stage.SetDefaultPrim(default_prim.GetPrim())

# Create a xform which should hold all references in this sample
ref_prim: Usd.Prim = UsdGeom.Xform.Define(stage, Sdf.Path("/World/ref_prim")).GetPrim()

# Add an internal reference
intern_target_path: Sdf.Path = Sdf.Path("/World/intern_target")
target_prim: Usd.Prim = UsdGeom.Xform.Define(stage, intern_target_path).GetPrim()
add_int_reference(ref_prim, intern_target_path)

# Add an external reference to specific prim
add_ext_reference(ref_prim, "C:/path/to/file.usd", Sdf.Path("/World/some/target"))

# Add other external reference to default prim
add_ext_reference(ref_prim, "C:/path/to/other/file.usd", Sdf.Path.emptyPath)

usda = stage.GetRootLayer().ExportToString()
print(usda)

# Get a list of all prepended references
references = []
for prim_spec in ref_prim.GetPrimStack():
    references.extend(prim_spec.referenceList.prependedItems)

# Check that the reference prim was created and that the references are correct
assert ref_prim.IsValid()
assert references[0] == Sdf.Reference(primPath=intern_target_path)
assert references[1] == Sdf.Reference(assetPath="C:/path/to/file.usd", primPath=Sdf.Path("/World/some/target"))
assert references[2] == Sdf.Reference(assetPath="C:/path/to/other/file.usd")

USDA

This is an example USDA result from creating an Xform and adding three References to it. The first referenced target prim is inside the current file with the prim path /World/intern_target. The second referenced target prim is in the file C:/path/to/file.usd with the prim path /World/some/target and the third is the default prim in the file C:/path/to/other/file.usd.

#usda 1.0
(
    defaultPrim = "World"
)

def Xform "World"
{
    def Xform "ref_prim" (
        prepend references = [
            </World/intern_target>,
            @C:/path/to/file.usd@</World/some/target>,
            @C:/path/to/other/file.usd@
        ]
    )
    {
    }

    def Xform "intern_target"
    {
    }
}