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:
- create a solo cube
- find sphere in the tab menu, shift-enter to auto append
- append a cone
- append a cylinder
- append a usd rop
- save it to $HIP/geo/manyshapes.usd
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 either by doing a best guess (like it did here, but warning you its unhapy), or
You can workaround this in a couple of hacky ways:
- Let the reference node guess which prim to load, as we've just seen
- 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
- 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)
- On the newly enabled 'Reference Primitive Path' parameter, click the chooser on the right
- 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.
- On the USD ROP, scroll down to the 'layer metadata section'
- Use the dropdown next to the default prim to choose what you want, say the sphere
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 that parent the default prim:
- Insert a stage manager before the rop
- Use the tricks mentioned before to create a top level 'shapes' folder, put all the shapes under that folder
- On the rop, set the default prim to /shapes
Reload the reference again, see all the shapes. Hooray!
Set the reference location in the scene graph
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 picked the rubber toy.
Annoyingly, I can't find a way to have Lops show me what the default prim is! The best I can do for now is prove it breaks when you don't set it. Try this:
- Go back to your node chain of shapes that ends in the manyshapes.usd rop
- Insert a 'configure layer' node before the rop
- Enable 'default primitive', leave it blank. We've now removed the default prim, so we should get an error
- Select the rop, click save and... oh. Damnit, no error.
- Scroll down in the Rop parameters, expand 'layer metadata', and enable 'error saving layer with no default primitive'
- 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; use a folder in the scene graph tree. Create a top level folder prim, call it 'mycoolprims', parent all our shapes underneath it, set 'mycoolshapes' as the default prim:
- Go back to the chain of shapes and rop
- Insert a stage manager node before the final rop
- Click the green plus at the top to make a top level folder, double click it to rename it to 'mycoolshapes'
- Drag all the other prims underneath it, so they're all children of mycoolshapes
- Insert a configure layer node before the rop
- Enable 'default prim', set the path to /mycoolshapes
- 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.
- Look at the reference node again, below where you specify the usd path is a 'Reference Primitive' parameter.
- Change it from 'Reference automatically chosen primitive' (which will get the default prim), to 'reference specific primitive'
- 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.