Tutorial: Setting up and Building Pixar's USD on Windows
Installing Required Software
You’re going to need a way to pull the USD Git repository. If you’re new to Git, one of the easiest ways to do this is to use the GitHub Desktop GUI. If you’re experienced with Git, of course, use whatever UI you prefer.
Download and install GitHub Desktop or your preferred Git interface.
While a separate Git install isn’t required to use GitHub Desktop, you’ll probably find it useful to have it set up on your system. Get Git here.
Download the 7Zip file archiver.
Add its install location (usually C:\Program Files\7-Zip) to the System Path .
Download Python 2.7. (Python 3 is not yet supported.)
Run the installer
Select the option to add Python 2.7 to the System Path
Important: you may need to add your Python Scripts directory to your System path by hand. (Usually C:\Python27\Scripts)
Verify that your System Path now includes C:\Python27 and C:\Python27\Scripts, and fix your paths if for some reason they’re not present.
Install it and select the option to add CMake to the System Path for all users.
Run the installer as an Administrator
When the warning appears, select More Info > Run Anyway
Install for anyone using this computer
Accept the default options
Add C:\Program Files\NASM to the System Path
Microsoft Visual Studio
Download Visual Studio Community.
Important: As of this writing, the build_usd.py script we’ll be running to build USD does not support VS 2019. You’ll need VS 2017 for this.
You can find older versions here: https://visualstudio.microsoft.com/vs/older-downloads/
Install it with the option to develop for desktop C++ selected.
Microsoft Visual Studio Code
Download and install Visual Studio Code.
Install the Python plugin for VSCode and reload it
Create a simple Python file (any file with extension .py)
Contents can be simple, for example:
msg = “Foo” Print msg
Saving the file with a .py extension should prompt VSCode to install PyLint - let it.
For further information on setting up VSCode to work with Python, check here. Be aware though that these directions discuss setting up Python 3, but USD requires Python 2. You can set up both Python versions on the same machine, but life gets more complicated if you do.
Getting the USD source
Navigate to Pixar’s USD Github repository.
Select Clone or Download > Open in Desktop (or again, if you’re already comfortable with Git, clone it by whatever means you prefer.)
Allow GitHub Desktop to clone the depot to the directory of your choice.
Preparing to Build
Run Start Menu > Visual Studio 2017 > x64 Native Tools Command Prompt for VS 2017
You must use the Native Tools Command Prompt - a standard command prompt won’t allow you to build using MSVC from the command line.
Verify your tools:
Type ‘cl’ - you should see the optimizing compiler’s usage notes appear
Type ‘7z’ - you should see the 7-Zip usage notes appear
Type ‘python’ - Python 2.7 should start. Type exit() to exit it.
If you have both Python 2 and Python 3 on your machine, type ‘py -2’ instead.
Type ‘cmake’ - CMake usage notes should appear
Type ‘nasm’ - NASM should complain that no input file was specified.
Type ‘pip install PySide’
For this and the following commands, it may be necessary to specify which pip executable to run if you have multiple versions of Python installed. In this case, you can specify the path directly:
C:\Python27\Scripts\pip install PySide
Let the install finish.
Type ‘pip install pyd’
Possibly not required
Type ‘pip install pyopengl’
Required for the USD viewer
In the Native Tools Command Prompt, navigate to the location where you cloned your USD source.
Type python build_scripts\build_usd.py "C:\USD"
Use py -2 rather than python if you need to specify explicitly that you want to run the build script using python 2. The script will not run under python 3.
The argument at the end is the location where you’d like to install the USD binaries. You can specify another location here if desired.
If your build fails:
Verify that you’re running from the Native Tools Command Prompt, not an ordinary command line.
Verify that you have VS 2017 installed and that you’re running the Native Tools Command Prompt associated with it.
An error like the following indicates that you’re missing the required VS install:
cmake -DCMAKE_INSTALL_PREFIX="C:\USD" -DCMAKE_PREFIX_PATH="C:\USD" -DCMAKE_BUILD_TYPE=Release -G "Visual Studio 15 2017 Win64" "C:\USD\src\zlib-1.2.11"
CMake Error at CMakeLists.txt:4 (project):
Visual Studio 15 2017 Win64
could not find any instance of Visual Studio.
Allow the build to complete
Add a PYTHONPATH variable to your system variables as instructed at the end of the install output and populate it as instructed.
If you installed USD to C:\USD, this path will be C:\USD\lib\python
Add C:\USD\bin and C:\USD\lib to your System Path as instructed.
If you installed elsewhere, of course, these paths will be different.
Testing the USD Build
Open a new command window (it no longer needs to be a Native Tools Command Prompt - Powershell or even the default command line is fine here now.)
Navigate to the location where you cloned your USD GitHub depot
Type: usdview .\extras\usd\tutorials\convertingLayerFormats\Sphere.usd
If you correctly set up your PYTHONPATH and Path variables in the last step, the USD viewer should now open and display a sphere.
If you’ve completed these steps and USDView successfully launched, you should be ready to work through the USD tutorials.
(You may also find it useful to set C:\USD\bin\usdview.cmd as the default application for .usd and .usda files in your Windows settings.)
Performing a simple Export/Import test using Unreal 4.22
Next, let’s set up Unreal Engine 4 to import and export USD. This functionality is experimental as of 4.22 and requires a bit of manual handling, but it’s enough to begin experimenting and see how the system works.
First, create a new project in Unreal 4.22.
Once the project has been created, open Settings | Plugins, and enable the USD Importer plugin and the Python Editor Script Plugin.
Allow the editor to restart.
Now for a simple test:
Create a new empty level.
Place a basic primitive, like a Sphere, into the level.
Select the sphere and hit File | Export Selected.
Set its Save As Type to .usda (USD supports binary .usd files and ASCII .usda files. When debugging, you’ll find it handy to work with .usda files so you can view their contents.)
Save it in a reasonable location.
If you now try opening the exported file in USDView, you’ll see that the geometry does not appear in the viewport, but its data appears valid.
This is because the geometry has been saved as a reference to an unrealActorClass, but we haven’t made any information about this class available to USD.
If we view the file in a text editor (If you’re using Visual Studio Code, I recommend enabling Animal Logic’s USD Language extension), we can see this as well - the actor’s unrealActorClass and unrealAssetPath have been specified along with its transform, but no other information is contained within the file.
For this simple test, this is fine.
Now let’s create another empty map in Unreal, select File | Import Into Level, and select the .usda file we just exported. You should see it appear in your level at the specified transform.
There’s also an interesting additional object in our level: a USDLevelInfo actor has been created.
If we select this actor, we’ll see that it gives us the option to specify a save file path, and that our imported sphere has automatically been added as a USD sub-layer. Let’s specify a destination path and hit Save USD.
The resulting USD file is even simpler than the previous - it simply references the Sphere sublayer we’d previously exported.
If we now create an empty Unreal level again and import the level .usda we just imported, we’ll see our geometry appear and if we look at our USDLevelInfo object, we’ll see that the imported level .usda is now identified as a sub-layer.
This is a major aspect of USD’s power - it can describe extremely large projects by referencing assets and entire scenes as sub-layers. We’ll talk about this more in another post.
What we’ve done here though should begin to give you a framework from which to explore USD, learn how it describes information, and learn how Unreal can generate and read the format.
Importing a USD Scene to Unreal
Now let’s try importing a full scene. Head over to http://graphics.pixar.com/usd/downloads.html and download the Kitchen Set scene. Extract it and verify it in USDView.
Now, in UE4, create a new empty level and select File | Import Into Level. Point the importer at the Kitchen_set.usd you just checked. The default import options are fine.
After a few moments, the scene should be properly constructed in your Unreal level.