2.3. Working with USD

2.3.1. Learning Objectives

In this tutorial, we will cover how to

  • save USD stages

  • load and reference existing USD stages

  • Organize stage tree hierarchy

2.3.2. Saving Options

  • Save: To save the current USD stage, go to the Menu Bar and click Files > Save or Files > Save As .. to save as a new file.

  • Save Flattened As: Saves the current USD file while merging all components to one mesh.

  • as .usda files: You have the option to save as .usda file instead of .usd file. .usda file is a human-readable text file format for the given USD stage.

  • Collect Assets: If your current stage used many reference USD stages, materials and textures from other folders and servers, you should Collect Assets to make sure all the external references that are used in your stage gets collected in one folder. To do so, save the current USD locally, then find it in the Content tab, right-click on it and select Collect Asset.

2.3.3. Loading Options

  • Open: To load a USD stage, go to Menu Bar and click Files > Open. This opens the USD stage, and you can directly edit it.

  • Add Reference: Files > Add Reference adds a USD file as a reference. You will not be able to edit the referenced USD. This can also be done by finding the file in the Content Tab and dragging it into the viewport.

2.3.3.1. Set Stage for Reference

To demonstrate adding a file as reference, let’s save the current stage with the simple cube and cylinders as a mock robot. First we’ll rearrange the rigid bodies on stage into a hierarchial structure with meaningful names. We will put all the rigid body parts to the robot under a single Prim.

  1. Right click inside the Stage tab, select Create > Xform. Rename the newly added Xform to mock_robot. The Prim should appear under the World prim.

  2. Move the Cube, both Cylinders, Physics Material, and Looks folder under mock_robot by drag and drop.

  3. Rename the Cube and Cylinders to the body, wheel_left, and wheel_right.

  4. Save the stage as an USD file.

Now open a new stage. To load the USD file as a reference, either Files > Add Reference or drag the file from Content on to the stage. It will load the referenced USD under a Prim named the same as the USD filename. Notice that it loaded everything under the original World(defaultPrim), including PhysicsScene, defaultLight, and GroundPlane. This may not be great if you are loading multiple USD references, and they all have their own version of PhysicsScenes and defaultLights. You cannot delete them on the new stage because they are loaded by reference, but to delete them in the original USD would make it difficult to work within those USD stages.

To both have the necessary environment set up in the USD stages but not export them when they are being referenced, you need to move non-referenced items out of the default Prim.

  • Select the robot’s parent prim on stage, in this case /mock_robot if you followed the instructions above.

  • Open the menu Edit while the prim is selected, and click on unparent. Now instead of being under World, mock_robot is parallel to World.

  • Right-click on the robot prim again on stage, and Set as a Default Prim. Save.

Now, if you open a new stage and load the same file again as a reference, only the robot will be imported.

2.3.4. Summary

In this tutorial, we learned how to save and open USD files.

2.3.4.1. Further Readings