From cgwiki

More on referencing

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

In a more complex scenario, with multiple departments getting into slapfights, huge sets made up of thousands of references, you'd likely want more control.

First, you can be more expliclit about where the reference will go in the Scene Graph Tree. Rather than just being vomited at the top level, you can say 'place this reference at /shot/characters/background/pig. In fact, lets do this:

  1. Make yet another copy of the pig reference, disconnect it from everything else, display it.
  2. The location in the Scene Graph Tree will be /referenceN.
  3. Change the Primitive Path parameter to /shot/characters/background/pig
  4. Bingo, look in the Scene Graph Tree now, it's immediately made that outliner folder structure for you, with the final 'pig' being the reference itself.

So that's being specific about the output location. You can also be specific about the input too. First, lets save a usd with a few things in it:

  1. create a cube put it down by itself
  2. find sphere in the tab menu, shift-enter to auto append
  3. same for pig
  4. same for rubber toy
  5. append a usd rop
  6. save it to $HIP/geo/manyshapes.usd

Right, now lets load this back in with a reference:

  1. Create a reference node
  2. Set the file path to save it to $HIP/geo/manyshapes.usd
  3. Look in the viewport and Scene Graph Tree, look confused

If you wired this in the same way I did, you'll only see the rubber toy, nothing else. What's that about?

A reference in USD is actually very explicit about what it will load, and where it will put it in the scene graph. My mental picture of how thsi works is 'take a prim from this usd on disk, and put it at this location in the scene graph'.

So why did this only load the rubber toy? Because if you don't specify which prim to load, it looks for a prim tagged as the default prim, and loads that.

Default prim

Ok fine, but we didn't specify that.. did we?

Well, we didn't, but something did. The rubber toy node did this secretly, so when the references is loaded back in, it knows what to do.

Annoyingly, this info is hard to preview in lops. The best I can do for now is prove it breaks when you don't set it. Try this:

  1. Go back to your node chain of shapes that ends in the manyshapes.usd rop
  2. Insert a 'configure layer' node before the rop
  3. Enable 'default primitive', leave it blank. We've now removed the default prim, so we should get an error
  4. Select the rop, click save and... oh. Damnit, no error.
  5. Scroll down in the Rop parameters, expand 'layer metadata', and enable 'error saving layer with no default primitive'
  6. Save again. Aha! Error!

That was contrived and stupid, but it makes the point that USD files are expected to have a default primitive. It's good to get in the habit of defining it yourself, either on the ROP options, or with a configure layer. (Don't worry about layers for now, we'll get to those in a bit).

Ok great, but where are my shapes?

Yes yes, we've got off track. So we have 2 conflicting things here; a reference expects to point to a single prim (the default prim if you don't specify otherwise), but we want to bring in many prims. How to solve this conundrum?

Simple; define a top level folder prim, call it 'mycoolprims', parent all our shapes underneath it, and define 'mycoolshapes' as the default prim.

  1. Go back to the chain of shapes and rop
  2. Insert a stage manager node before the final rop
  3. Click the green plus at the top to make a top level folder, double click it to rename it to 'mycoolshapes'
  4. Drag all the other prims underneath it, so they're all children of mycoolshapes
  5. Insert a configure layer node before the rop
  6. Enable 'default prim', set the path to /mycoolshapes
  7. Save
  8. Go back to the new reference node thats loading manythings.usd, reload, it should now show all the shapes.

Override the default primitive

Phew! But hey, imagine after all that you change your mind, and you only want the sphere? You can do that.

  1. Look at the reference node again, below where you specify the usd path is a 'Reference Primitive' parameter.
  2. Change it from 'Reference automatically chosen primitive' (which will get the default prim), to 'reference specific primitive'
  3. In the newly enabled 'Reference primitive path' parm, use the selector on the right, it'll pop up a outliner view of whats inside the file, choose your sphere.

As per usual this seems overly complicated, but its handy if you have a huge complicated city model on disk, and only want to work on a single streelight. Unlike most other systems that'll make you pay the cost of loading everything only to then load the one thing you need, Lops and USD will load that single streetlight very efficiently.