Add a Payload

A Payload is a composition arc that functions similar to a Reference to enable users to aggregate layers or assets onto a Stage. The difference is that a users can choose to not load a Payload. This can help users see the full hierarchy of a Stage, but only load the heavy parts ( i.e. Payloads) that they need. A Payload 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 add a Payload to a prim. A single prim can have multiple Payloads.

USD Python

With the USD API, you can use Usd.Prim.GetPayloads() to receive the payloads and add a new one with Usd.Payloads.AddPayload().

from pxr import Usd, Sdf

def add_payload(prim: Usd.Prim, payload_asset_path: str, payload_target_path: Sdf.Path) -> None:
    payloads: Usd.Payloads = prim.GetPayloads()
    payloads.AddPayload(
        assetPath=payload_asset_path,
        primPath=payload_target_path # OPTIONAL: Payload a specific target prim. Otherwise, uses the payloadd 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
default_prim = UsdGeom.Xform.Define(stage, Sdf.Path("/World"))
stage.SetDefaultPrim(default_prim.GetPrim())

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

# Add an external payload
add_payload(payload_prim, "C:/path/to/file.usd", Sdf.Path("/World/some/target"))

# Add other external payload to default prim
add_payload(payload_prim, "C:/path/to/other/file.usd", Sdf.Path.emptyPath)

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

# Get a list of all prepended payloads
payloads = []
for prim_spec in payload_prim.GetPrimStack():
    payloads.extend(prim_spec.payloadList.prependedItems)

# Check that the payload prim was created and that the payloads are correct
assert payload_prim.IsValid()
assert payloads[0] == Sdf.Payload(assetPath="C:/path/to/file.usd", primPath=Sdf.Path("/World/some/target"))
assert payloads[1] == Sdf.Payload(assetPath="C:/path/to/other/file.usd")

Python Kit Commands

The AddPayload command in Kit can add payloads to a prim.

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

def add_payload(prim: Usd.Prim, payload_asset_path: str, payload_target_path: Sdf.Path) -> None:
    omni.kit.commands.execute("AddPayload",
        stage=prim.GetStage(),
        prim_path = prim.GetPath(), # an existing prim to add the payload to.
        payload=Sdf.Payload(
            assetPath = payload_asset_path,
            primPath = payload_target_path
        )
    )


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

# 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 payloaderenced again
default_prim = UsdGeom.Xform.Define(stage, Sdf.Path("/World"))
stage.SetDefaultPrim(default_prim.GetPrim())

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

# Add an payload specific prim
add_payload(payload_prim, "C:/path/to/file.usd", Sdf.Path("/World/some/target"))

# Add other payload to default prim
add_payload(payload_prim, "C:/path/to/other/file.usd", Sdf.Path.emptyPath)

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

# Get a list of all prepended payloads
payloads = []
for prim_spec in payload_prim.GetPrimStack():
    payloads.extend(prim_spec.payloadList.prependedItems)

# Check that the payload prim was created and that the payloads are correct
assert payload_prim.IsValid()
assert payloads[0] == Sdf.Payload(assetPath="C:/path/to/file.usd", primPath=Sdf.Path("/World/some/target"))
assert payloads[1] == Sdf.Payload(assetPath="C:/path/to/other/file.usd")

USDA

This is an example USDA result from creating an Xform and adding two Payloads to it. The first payload target prim in this case is in the file C:/path/to/file.usd with the prim path /World/some/target and the second 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 payload = [
            @C:/path/to/file.usd@</World/some/target>,
            @C:/path/to/other/file.usd@
        ]
    )
    {
    }
}