Hello USD - Part 3: Reality Composer is my USD WYSIWIG

What I’ve written in this series so far has been aided by looking at USDZ files generated by Reality Composer and Blender. I’ve been using the usdcat tool supplied in Pixar’s USD repo.

Knowledge Prereq

This post assumes the reader is familiar with what CMake is and its role in building C++ projects. That said, Pixar has done all the hard work. The only thing to do is a copy paste of a couple of lines into a shell.

Software & Hardware:

Following along does not require any beta software.

These steps have been tested on both Intel and Apple Silicon, no rosetta mode required.

Step 1: Get a USDC file from a Reality Composer project

Most programs that create USD files compress them into Crate files because the ASCII files get unwieldy. Thankfully, the folks at Pixar made a converter. Honestly this converter turns Reality Composer almost into a WYSIWIG. Super handy.

Find Reality Composer via the Xcode > Developer Tools > Reality Composer menu path in Xcode 14.

I chose New Document from the start up screen with a horizontal layout and threw some random objects into it. I did not turn on physics or accessibility at this time.

Screen shot of a Reality Composer window with 3 objects, a rock with an image texture, a purple cube and a blue capsule

What was less clear than putting some objects on the stage, was needing to go into Reality Composer > Settings to turn on the USDZ export.

Screenshot of a Reality Composer settings window. It is very small and only has about 5 things to edit, but the one that says Enable USDZ Export is checked.

Once that box is ticked in the settings the File > Export menu will give the USDZ option. I chose Current Scene rather than Project hoping to get a simpler file.

Screenshot of Reality Composer export window in context over a view of the file being exported. The radio button for exporting only the scene is selected. USDZ is selected as the export file type in the drop down menu. There are instructions to look up the developer documentation

I now have a file called ThreeBodyUSDZ.usdz

I renamed that file to ThreeBodyUSDZ.zip and extracted the contents (doubled click on it).

Depending on the complexity of the USDZ, the result will be a .usdc file with a long UUID()-looking name or a folder that has one in it. I’ll target that file with usdcat to convert. usdcat can work on .usdz files directly, but the time may come when targeting specific files in an archive will be helpful.

Step 2: Install the C++ conversion tool

Just doing conversions does not require installing python libraries or modules at all: not from Pixar, nor the ones in USDZ Tools bundle from Apple. usdcat, a utility that lives in the Pixar C++ library on github, will do everything we need.

That said, we’re going to make use of one python script, as Pixar supplies a Python 3.11 compatible build script. (CMake dependency)

Dependencies for USD itself include: zlib, boost, TBB, MaterialX, OpenSubdiv. Running the brew install scripts does not appear to appreciably speed things up, the build script appears to go fetch it’s own copies regardless.

# unnecessary, ignored by the compiler, but for the record done
brew install zlib
brew install boost
brew install tbb
brew install opensubdiv

Doing the USD --no-python install:

# if haven't already
# brew install cmake
cd $DOWNLOAD_DIR
git clone https://github.com/PixarAnimationStudios/USD.git
# there will now be a directory called USD in the pwd
# the below will show the build options
python3 USD/build_scripts/build_usd.py
# run with the --no-python option
python3 USD/build_scripts/build_usd.py --no-python $BUILD_DEST_DIR

Fair warning, this takes a long time to run.

I will not be adding this build to my PATH at this time. One reason, I am going to make a few different builds and I want it clear in this documentation which one I’m using. My $BUILD_DEST_DIR is ~/opb/USDCpp. opb “off path bin” and USDCpp to let me know I’m using the --no-python build

Step 3: Convert the files

# discover options
~$BUILD_DEST_DIR/usdcat --help
# The basic pattern:
~$BUILD_DEST_DIR/usdcat -o $DESTINATION $SOURCE
# so for example
cd $DIRECTORY_WITH_FILES_TO_CONVERT
~/opb/USDCpp/bin/usdcat -o threeBodyExample_fromArchive.usda ThreeBodyUSDZ.usdz
~/opb/USDCpp/bin/usdcat -o threeBodyExample_fromCrate.usda ThreeBodyUSDZ/8AE371F7-0528-4095-8AA4-ECDAA71F409E.usdc

Success!

Screenshot of same image (rock, cube capsule), but this time in a QuickView window.

All it took was using a destination file name with .usda as the extension to get a usda file from the conversion tool.

Step 4: Inspect and compare the files

Helpful hint: use a diffing tool to compare the files. (VSCode: open folder, select files and right click)

Exactly the same!

Copies of these files are available on GitHub.

Interestingly, changing the extension from .usda to .usd on these files makes them stop working in QuickView. Possible related error messages in Console (full list from time at https://github.com/carlynorama/USDHelloWorld/tree/main/explorations/Part_03/ThreeBodyExample/console_errors_on_usd.txt)

I found the errors interesting but not fully illuminating. I’m hoping the USDZ checking script in Apple’s USDZ Tools will help, but that’s tomorrows topic.

The stone uses a texture, for the .usda file to render the texture the image for the texture must have the same relative path to the .usda as to the original .usdc or .usdz, or the .usda will need to be edited.

Blender

Blender appears to export .usdc files directly, at least for simple projects. These files convert beautifully into .usda files using usdcat, and QuickLook can render them fine. Downside, Blender presents a much steeper learning curve than Reality Composer and isn’t integrated into the RealityKit workflow.

Wrap Up

It appears the most typical way to create USDZ files is through some GUI: Blender, Reality Composer, Maya, etc. Having a way to convert these software generated files into something human readable makes it easier to learn about the format and was fairly easy to do.