Difference between revisions of "UsdGuide08"

From cgwiki
(6 intermediate revisions by the same user not shown)
Line 3: Line 3:
 
The referencing we've done so far has been pretty simple; load a pig, done.
 
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.  
+
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, 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'.
+
First, lets make a more complex USD file on disk to play with by chaining together some shapes:
  
In fact, lets do this:
+
=== Make manyshapes.usd ===
  
# Make yet another copy of the pig reference, disconnect it from everything else, display it.
+
# create a solo cube
# The location in the Scene Graph Tree will be /referenceN.
 
# Change the Primitive Path parameter to /shot/characters/background/pig
 
# Bingo, look in the Scene Graph Tree now, it's immediately made that 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:
 
 
 
# create a cube, put it down by itself
 
 
# find sphere in the tab menu, shift-enter to auto append
 
# find sphere in the tab menu, shift-enter to auto append
# same for pig
+
# append a cone
# same for rubber toy
+
# append a cylinder
 
# append a usd rop
 
# append a usd rop
 
# save it to $HIP/geo/manyshapes.usd
 
# save it to $HIP/geo/manyshapes.usd
  
Right, now lets load this back in with a reference:
+
=== Default primitive ===
  
# Create a reference node
+
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?
# Set the file path to save it to $HIP/geo/manyshapes.usd
 
# 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?
+
USD expects a '''default primitive''' to be tagged in a usd file. That will be the prim loaded and displayed.
  
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 this works is 'take a prim from this usd on disk, and put it at this location in the scene graph'.
+
If you don't specify a default prim, you're being bad. Lops lets you get around this in a couple of ways:
  
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.
+
# Let the reference node guess which prim to load, as we've just seen
 +
# Explicitly tell it which prim to load.
  
=== Default prim ===
+
Lets see how to do that hacky second method, before doing the right thing and assigning a default prim.
  
Ok fine, but we didn't specify that.. did we?
+
=== Explicitly tell a reference node which prim to load ===
  
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.
+
# 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.
  
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:
+
=== Set the default primitive ===
  
# Go back to your node chain of shapes that ends in the manyshapes.usd rop
+
Bah, lets do this right.
# 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).
+
# 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
 +
# Save
  
=== Ok great, but where are my shapes? ===
+
Now if you go back to the reference node and choose either automatic or default, reload, it should display the sphere.
  
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?
+
=== Reference many prims ===
  
Simple; define a top level folder prim, call it 'mycoolprims', parent all our shapes underneath it, and define 'mycoolshapes' as the default prim.
+
So you might've noticed we specify a default prim, not prims. What if we want to reference in all the shapes?
  
# Go back to the chain of shapes and rop
+
Simple, put all the shapes under a parent folder, and make that parent the default prim:
# 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'
+
# Insert a stage manager before the rop
# Drag all the other prims underneath it, so they're all children of mycoolshapes
+
# Use the tricks mentioned before to create a top level 'shapes' folder, put all the shapes under that folder
# Insert a configure layer node before the rop
+
# On the rop, set the default prim to /shapes
# Enable 'default prim', set the path to /mycoolshapes
 
 
# Save
 
# Save
# Go back to the new reference node thats loading manythings.usd, reload, it should now show all the shapes.
 
  
=== Override the default primitive ===
+
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.
  
Phew! But hey, imagine after all that you change your mind, and you only want the sphere? You can do that.
+
Seems arbitrary and fiddly, but there's a few cool features:
  
# Look at the reference node again, below where you specify the usd path is a 'Reference Primitive' parameter.
+
* 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
# Change it from 'Reference automatically chosen primitive' (which will get the default prim), to 'reference specific primitive'
+
* 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.
# 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.
+
* Layering.
  
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.
+
Layering? What? Better read the next section! [[UsdGuide09]]

Revision as of 05:59, 30 April 2021

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 that parent 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! UsdGuide09