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.
- MacOS 13.4
- Xcode 14.3.1 & the command line tools
- Homebrew 4.0.26 with brew upgrade run 2023-06-30
- optional: VSCode, plugins for C++, CMake and Python from Microsoft and USD plugin from Animal Logic for inspection.
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.
- https://developer.apple.com/documentation/realitykit/creating-3d-content-with-reality-composer
- Building AR Experiences with Reality Composer https://developer.apple.com/videos/play/wwdc2019/609
- The artist’s AR toolkit https://developer.apple.com/videos/play/wwdc2020/10601/
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.
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.
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!
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)
- WindowServer CGLayerKit called back with no connection
- kernel 1 duplicate report for System Policy: mds(133) deny(1) file-read-data /private/var/db/searchparty/sharedVault/agents/BADE6C8F-36E9-4FD3-B815-5E34351823AC/savedConfiguration.plist
- kernel Sandbox: HydraResourceCoordinator(44546) deny(1) file-read-metadata /Users/$USER/Developer/GitHub/USDHelloWorld/Part_03/ThreeBodyExample
- HydraQLPreviewExtension WARNING: Quick Look extensions should not have any views or subviews claim first responder
- SceneKitQLPreviewExtension CGSWindowShmemCreateWithPort failed on port 0
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.