Tutorial: Setting up and Building Pixar's USD on Windows

553309696.jpg

Setting up Pixar’s Universal Scene Description (USD) framework can be a daunting task, and documentation tends to be spread around. Here’s a quick rundown of what you need to do. (With thanks to VFXPro99’s instructions here :)

Installing Required Software

Git Support

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.

7-Zip

  • Download the 7Zip file archiver.

  • Install it.

  • Add its install location (usually C:\Program Files\7-Zip) to the System Path .

Python 2.7

  • 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.

CMake

  • Download CMake.

  • Install it and select the option to add CMake to the System Path for all users.

NASM

  • Download NASM.

  • 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

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.

  • Install dependencies:

    • 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


Building USD

  • In the Native Tools Command Prompt, navigate to the location where you cloned your USD source.

2019-08-06 19_14_24-Developer Command Prompt for VS 2017.png
  • 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):
              Generator
                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.

2019-08-06 19_15_55-Select Developer Command Prompt for VS 2017.png

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.

USDView

USDView

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.)

2019-08-07 11_03_40-Window.png

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.

UE4_USDImporterPlugin.png
UE4_PythonEditorScriptPlugin.png

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.

UE4_USD_ExportSphere.png

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.

UE4_USDSphere_inUSDView.png

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.

UE4_USDSphere_text.png

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.

UE4_USDSphere_import.png

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.

UE4_USDSphere_levelSave.png

The resulting USD file is even simpler than the previous - it simply references the Sphere sublayer we’d previously exported.

UE4_USDSphere_as_sublayer.png

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.

2019-08-09 12_32_40-E__Projects_USD_Examples_Kitchen_set_Kitchen_set_Kitchen_set.usd.png

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.

2019-08-09 12_35_22-USD Import Options.png

After a few moments, the scene should be properly constructed in your Unreal level.

usd_kitchen_example_in_ue4.png

Additional Resources