End to End Example
VERIFIED ON USD VERSION 21.08
This tutorials aims to show USD in an extremely simplified pipeline. The files for this tutorial live in USD/extras/usd/tutorials/endToEnd.
Overview of files:
- assets: This folder contains some files that are used in the tutorial. It also contains some of the geometry in case you do not want to author them yourself.
- scripts: Some generic scripts we use in the tutorial. We've tried to document them. Feel free to poke around, or run them with
-h
. - tutorial_scripts: Scripts specifically geared toward this tutorial. They may have hard-coded paths that are intended to be run from the tutorial root. We've also documented those, but they are intended to be used primarily for this tutorial.
Goals:
- How to generate USD files from Maya
- How to introspect USD files
- How to manipulate USD files with code
Create Assets
Bootstrap
We'll first run a script that bootstraps an asset for us. The following will create an empty asset named "Ball" inside the directory "models/Ball".
python scripts/create_asset.py Ball --shadingVariantLayer -o models/Ball
Go ahead and look at the files it created:
ls models/Ball usdcat models/Ball/*.usd usdview models/Ball/Ball.usd
There is no geometry but if usdview
opens without errors, we're off to a great start. We'll be adding geometry in the next section.
Putting models in their own directories is convenient for managing versions, etc. but how you layout files at your site will likely differ. This particular structure is an example and is not required to get USD to work.
We're going to also need a Table for this example so go ahead and run:
python scripts/create_asset.py Table -o models/Table
Maya
The Maya plugin previously distributed with USD has been incorporated into the Autodesk maya-usd repository. This portion of the tutorial remains here for historical reference.
You can continue through this tutorial by using the geometry provided in the repository and skipping to the "Shading Variants" section.
cp assets/Ball/Ball.maya.usd models/Ball/Ball.maya.usd cp assets/Table/Table.maya.usd models/Table/Table.maya.usd usdview models/Ball/Ball.usd usdview models/Table/Table.usd
You should see a sphere-like mesh for the Ball asset.
Load the Maya plugin
Inside Maya, load the pxrUsd
Maya plugin. This can be done via the Plug-in Manager (Windows -> Settings/Preferences -> Plug-in Manager
) or by entering the following command in the MEL script window
loadPlugin pxrUsd
Exporting the ball asset
Open the Ball.ma file in Maya. This file contains geometry and shading for a simple sphere:
maya assets/Ball/Ball.ma
To export this scene, select the sphere, select File -> Export Selection, and choose pxrUsdExport under Files of type
.
Be sure to choose RfM under shading mode. In the file browser, find "models/Ball/Ball.maya.usd"
and save over it.
Save Settings:
You can now try viewing this:
usdview models/Ball/Ball.usd # in usdview, you can view the different levels of subdivision via ctrl+- and ctrl+=
Exporting the table asset
Open the Table.ma file in Maya.
maya assets/Table/Table.ma
Select the table in the scene, then select File -> Export Selection. Choose pxrUsdExport under Files of type
.
As with the Ball, be sure to choose RfM under shading mode. In the file browser, find "models/Table/Table.maya.usd"
and save over it.
At this point, you should have geometry and shading information authored for both the Ball
and Table
. If you were not able to complete this section, see the note above for instructions on copying over pre-exported assets.
Shading Variants
We will add shading variants to the Ball entirely through code. Please see tutorial_scripts/add_shadingVariants.py
.
Start by copying the Ball textures into your Ball directory:
cp -r assets/Ball/tex models/Ball/
Add shading variants to the Ball with a python script:
python tutorial_scripts/add_shadingVariants.py usdcat models/Ball/Ball.shadingVariants.usda
This script assumes you've been following along the tutorial and is expecting a Ball
model to exist with shading from the Maya file. If you've tweaked things, you may have to go in and modify that script.
We are keeping the networks very simple for this tutorial. If you look at the Ball
model in usdview
, and then with /Ball
selected, select the Meta Data tab and use the shadingVariant drop-down menu to change to variants with different colors.
usdview models/Ball/Ball.usd
Set dressing
We'll create a set model that brings together the Table
and a standard set of 15 Ball
models together.
python tutorial_scripts/create_Room_set.py usdview models/Room_set/Room_set.usd
This script assumes you've been following along the tutorial and is expecting an Ball
and Table
model to exist. It also makes some assumptions about the size of these models. If you've tweaked things, you may have to go in and modify that script.
Also, note that we're hard-coding absolute paths to the other assets. The path resolver plugin provides a better mechanism that allows you to locate assets by other means.
You may need to move the camera around to see the table and balls as pictured below.
Shot Work
Here, we'll mock up an example of how a sequence and shot might be structured. This will illustrate some of the benefits of USD composition. Since your structure likely varies, we'll first define some terms and explain the structure we're about to create.
A sequence is a collection of related shots. A shot will include (by sublayering) all the scene description that is associated with its sequence. This structure allows you to put opinions that affect multiple shots in one location. We will also make each sequence inherit opinions from a global/shared shot.usd
file. This makes it so we can define the overall structure in one place. That's a good place to put things you will need everywhere (for example, the camera).
Another axis by which we organize our work is by department. A shot can have a layer for layout, a layer for animation, and a layer for sim, as an example. The same goes for a sequence. We will build a shot that has the following layers (strongest to weakest)
# shot layers s00_01.usd s00_01_sim.usd s00_01_anim.usd s00_01_layout.usd s00_01_sets.usd # sequence layers s00.usd s00_sim.usd s00_anim.usd s00_layout.usd s00_sets.usd # global shot.usd
USD has no notion of what a "shot" or "sequence" is. Again, this is just an example and this structure is not required for USD.
Sequence/Shot setup
The scripts/create_shot.py
script will help setup a sequence and a shot. For starters, take a look at the structure that's defined in assets/shot.usd
:
usdcat assets/shot.usd
Let's setup the sequence. We'll use the create_shot.py
script even though we're making a sequence:
python scripts/create_shot.py s00 -o shots/s00 -b assets/shot.usd
This creates a sequence in the directory shots/s00
that references assets/shot.usd
(note the -b
argument to create_shot.py
authors that reference verbatim).
And now the shot:
python scripts/create_shot.py s00_01 -o shots/s00_01 -b shots/s00/s00.usd
Now, you should have the layer structure defined in the previous sections. Opinions from the shot will override the weaker opinions that are in the sequence or the "global" layer.
In an actual production, you'll probably structure your files to make the dependency between s00_01
and s00
more evident.
Since this is a newly created shot and sequence, there shouldn't really be anything in it except for what was in assets/shot.usd, which should just be the camera.
usdview shots/s00_01/s00_01.usd
Simple shot work
Now we'll start running some scripts. First, at the sequence level, we'll bring in the Room_set
asset.
python tutorial_scripts/add_set_to_s00.py usdview shots/s00/s00.usd
And now, let's say a layout TD adds in a cue ball, removes some un-needed props, and positions the camera
# notice that s00_01 brings in opinions from s00 usdview shots/s00_01/s00_01.usd # feel free to introspect the resulting files in between each of the following. python tutorial_scripts/layout_shot_s00_01.py python tutorial_scripts/anim_shot_s00_01.py
Render
The Katana USD plugin was removed from the USD distribution in version 20.05 in favor of the Foundry-supported plugin located at https://github.com/TheFoundryVisionmongers/KatanaUsdPlugins. This portion of the tutorial remains here for historical reference.
We'll now render our shot in katana
. In the root of your endToEnd tutorial directory, run:
katana assets/simple.katana
The USD file is read in with the provided PxrusdIn node. An optional camera is merged into the scene (to work around a known issue when rendering from the camera in the USD file). A simple light is created in the gaffer node.
To render the scene, right-click on the RenderSettings node and select "Preview Render".
That's it!
Feel free to experiment with this tutorial by modifying scripts or adding your own geometry and shading.