Exercise: Working With Payloads#

Let’s first look at how payloads work using simple geometry.

  1. In the Visual Studio Code terminal, run the following code to open the file in usdview.

Windows:

.\scripts\usdview.bat .\composition_arcs\payloads\simple_example\red_cube.usd

Linux:

./scripts/usdview.sh ./composition_arcs/payloads/simple_example/red_cube.usd

Notice that this is the same cube we used in the Working With References exercise.

  1. Close out of usdview and head back to Visual Studio Code.

  2. Open the following file to view the USDA format: composition_arcs/payloads/simple_example/payloads_simple.usd

It’ll look like this:

 1#usda 1.0
 2(
 3    defaultPrim = "World"
 4    endTimeCode = 100
 5    metersPerUnit = 0.01
 6    startTimeCode = 0
 7    timeCodesPerSecond = 24
 8    upAxis = "Y"
 9)
10
11def Xform "World"
12{
13    def "red_cube_01" (
14        prepend payload = @./red_cube.usd@
15    )
16    {
17        float3 xformOp:rotateXYZ = (0, 0, 0)
18        float3 xformOp:scale = (1, 1, 1)
19        double3 xformOp:translate = (-75, 0, 0)
20        uniform token[] xformOpOrder = ["xformOp:translate", "xformOp:rotateXYZ", "xformOp:scale"]
21    }
22
23    def "red_cube_02" (
24        prepend payload = @./red_cube.usd@
25    )
26    {
27        float3 xformOp:rotateXYZ = (0, 0, 0)
28        float3 xformOp:scale = (1, 1, 1)
29        double3 xformOp:translate = (75, 0, 0)
30        uniform token[] xformOpOrder = ["xformOp:translate", "xformOp:rotateXYZ", "xformOp:scale"]
31    }
32
33    def "red_cube_03" (
34        prepend payload = @./red_cube.usd@
35    )
36    {
37        float3 xformOp:rotateXYZ = (0, 0, 0)
38        float3 xformOp:scale = (1, 1, 1)
39        double3 xformOp:translate = (0, 100, 0)
40        uniform token[] xformOpOrder = ["xformOp:translate", "xformOp:rotateXYZ", "xformOp:scale"]
41    }
42}

What are some of the things you notice that are similar to references? Any differences? You should notice the payload keyword instead of the references keyword. We can also see that a payload is added similar to how a reference is added in USDA, where the only difference is the keyword.

  1. Next, run the following code in Visual Studio Code to open the file in usdview:

Windows:

.\scripts\usdview.bat .\composition_arcs\payloads\simple_example\payloads_simple.usd

Linux:

./scripts/usdview.sh ./composition_arcs/payloads/simple_example/payloads_simple.usd

You might be asking yourself, how is this any different from using references? What’s the benefit?

Let’s start by showing one of the differences between payloads and references.

  1. In usdview, right-click on red_cube_01 in the tree view. We have the option to unload the prim.

  1. Click on Unload.

We can see that the red cube has vanished from the scene. Take note that when selecting Unload, all the descendants from the payload are also not in the tree view. This is because payloads have the ability to load (compose) all of the scene description targeted by the payload or unload all their scene description, recomposing all prims beneath the payloaded prim, unloading them from the layer.

On the other hand, references are always composed and present on the stage. They cannot be unloaded.

  1. We can also unload all payloads in the stage at once. In usdview, right-click on red_cube_01 and select Load to load it back onto our stage.

  2. Then, right-click on Root and click Unload. This will unload all payloads that are composed on the stage. To load it back, right-click on Root and select Load.

Now, imagine that our scene has become too large and it’s hard to see everything when it’s fully loaded into the viewport. You can open the stage with all payloads unloaded and then load just what you need to work on the scene. This is where payloads come in handy.

  1. Open composition_arcs/payloads/exercise/payloads_exercise.py in Visual Studio Code.

Similarly to how we added references to prims, we will use GetPayloads() and AddPayload() to add payloads to a prim.

  1. Add the following code into the script:

 1xform = UsdGeom.Xform.Define(stage, "/World/sm_bldgF_01")
 2xform.GetPrim().GetPayloads().AddPayload("./sm_bldgF.usd")
 3xform = UsdGeom.Xform.Define(stage, "/World/sm_bldgF_02")
 4xform.GetPrim().GetPayloads().AddPayload("./sm_bldgF.usd")
 5xform_api = UsdGeom.XformCommonAPI(xform)
 6xform_api.SetTranslate(Gf.Vec3d(180, 0, 0))
 7xform = UsdGeom.Xform.Define(stage, "/World/sm_bldgF_03")
 8xform.GetPrim().GetPayloads().AddPayload("./sm_bldgF.usd")
 9xform_api = UsdGeom.XformCommonAPI(xform)
10xform_api.SetTranslate(Gf.Vec3d(340, 0, 0))

  1. Save the file.

  2. In the terminal, run the following code:

Windows:

python .\composition_arcs\payloads\exercise\payloads_exercise.py

Linux:

python ./composition_arcs/payloads/exercise/payloads_exercise.py

  1. Now let’s open city.usda. In the terminal, run the following code:

Windows:

.\scripts\usdview.bat .\composition_arcs\payloads\exercise\city.usda

Linux:

./scripts/usdview.sh ./composition_arcs/payloads/exercise/city.usda

As we can see, each building here is actually a payload. We can unload these via a script as well.

  1. We can open a Python interpreter window inside of usdview. Go to Window > Interpreter to open a Python interpreter.

  1. Add the following code into the interpreter then press enter. This will unload all the payloads composed under the root. You can also find this code in composition_arcs/payloads/exercise/usdview_exercise.py

1stage = usdviewApi.stage
2root = stage.GetPseudoRoot()
3root.Unload()

  1. Let’s say you want to only load one of the buildings back. Add the following code into the interpreter then press enter to run the code.

1bldg = stage.GetPrimAtPath("/World/sm_bldgF_01")
2bldg.Load()

This means that we can unload all payloads in a stage before opening the layer. This can save on load time especially for large scenes.