From cgwiki

More on referencing

The referencing we've done so far has been pretty simple; load a pig, done.

USD references are a little more complex than this, and are so core to working with USD it's worth exploring more in depth.

First, lets make a more complex USD file on disk to play with by chaining together some shapes:

Make manyshapes.usd

  1. create a solo cube
  2. find sphere in the tab menu, shift-enter to auto append
  3. append a cone
  4. append a cylinder
  5. append a usd rop
  6. save it to $HIP/geo/manyshapes.usd

Default primitive

Create a reference node, load that usd. While you'd expect to see all the shapes, in fact you get just the cube and a warning on the node that it 'reference one of several root primitives'. What's that about?

USD expects a default primitive to be tagged in a usd file. That will be the prim loaded and displayed.

If you don't specify a default prim, you're being bad. Lops lets you get around this in a couple of ways:

  1. Let the reference node guess which prim to load, as we've just seen
  2. Explicitly tell it which prim to load.

Lets see how to do that hacky second method, before doing the right thing and assigning a default prim.

Explicitly tell a reference node which prim to load

  1. On the reference node, set 'reference primitive' to Reference Specific Primitive (note the other modes talk about automatically finding a prim, or the default prim as we just discussed)
  2. On the newly enabled 'Reference Primitive Path' parameter, click the chooser on the right
  3. This now shows you the prims in the usd file. Pick what you want, now it displays.

Set the default primitive

Bah, lets do this right.

  1. On the USD ROP, scroll down to the 'layer metadata section'
  2. Use the dropdown next to the default prim to choose what you want, say the sphere
  3. Save

Now if you go back to the reference node and choose either automatic or default, reload, it should display the sphere.

Reference many prims

So you might've noticed we specify a default prim, not prims. What if we want to reference in all the shapes?

Simple, put all the shapes under a parent folder, and make the folder be the default prim:

  1. Insert a stage manager before the rop
  2. Use the tricks mentioned before to create a top level 'shapes' folder, put all the shapes under that folder
  3. On the rop, set the default prim to /shapes
  4. Save

Reload the reference again, see all the shapes. Hooray!

Set the reference location in the scene graph

Note that in the scene graph tree the '/shapes' prim has been renamed to 'referenceN'. This comes from the 'primitive path' parameter which is set to '/$OS', ie, it'll create a top level folder named after the node.

This can be changed to whatever you want. Try changing that path to '/shot020/assets/shape_library'. As soon as you do that, the Scene Graph updates to reflect that folder structure.

Whats the point

You could summarise a reference as 'put this, there'. Or more explicitly:

From THAT USD file, load THIS prim, and place it THERE in the scene graph.

Seems arbitrary and fiddly, but there's a few cool features:

  • This lets you create very specific hierarchies in very specific ways. Eg you could have 5 references, each one representing the set, the characters, the props, the fx, the camera, and assemble them clearly and logically; eg set is always put into /shot/asset/set, chars into /shot/char, cameras into /cam, whatever makes sense for you for assembly
  • The ability to override the default prim with an explicit override is handy, and high performance. Eg you might have a huge city set in a usd file, but you just need to load one streetlamp to do fx on it. Fine, set the reference primitive path to only that streetlamp, it loads instantly, the rest of the usd file is ignored.
  • Layering.

Layering? What? Better read the next section!

prev: UsdGuide07 this: UsdGuide08 next: UsdGuide09
main menu: UsdGuide