Urban Exile

Google has a utility to convert glTF files (a 3D transmission format for the web) into the USDZ format (a 3D format released by Apple that is based on the USD format from Pixar). Unfortunately, if you want to use this utility you need to build it from the source code. This one is going to get really technical, but putting together all of these pieces took me quite a bit of time so I figured these directions would be useful to others! If you want to build the usd_from_gltf project on Windows WSL using Debian, read on!

Why?

I recently learned that Apple platforms (Mac, iPhone, etc.) can send and receive 3D objects and use them directly in Augmented Reality (AR) mode. If you have an Apple device, you can see what I mean by visiting the Apple Augmented Reality Quick-Look page; try clicking on one of the 3D models and allowing your browser to access your camera. The 3D model (and any associated animations) can be placed in-camera into the environment that you are viewing!

But of course, there is a catch – the file needs to be in a USDZ format. What is USDZ? It’s a format Apple designed that is based on another format, USD, which Pixar has made available to the 3D community. USD is gaining popularity and adoption as an interchange format for 3D pipelines, because it supports non-destructive editing, different views, opinions, and even allows different parts of the pipeline (modeling, lighting, animation) to be worked on independently.

But USDZ isn’t really compatible with USD, it just uses a subset of USD features and then packs the files into a completely different file format (ZIP files with custom byte alignment, so it’s not even really compatible with normal ZIP files, either – of course).

And I primarily use Blender for 3D objects, which only supports USDA and USDC (the formats defined by Pixar). So if I want to export an object to USDZ from Blender, I am out of luck – at least, if I want to directly export the files.

Fortunately, Blender also supports exporting to glTF, which is a format designed for 3D models on the web, especially mobile devices. The goal of glTF is to be the “JPG of 3D”, designing the format to be easily consumed by browsers with minimal processing.

And Google released an unofficial utility to convert from glTF to USDZ. So I decided to build it, figuring that it couldn’t be too hard to compile a simple conversion utility. After hours of trying different compile steps, I finally got lucky and hit the magic combination — here are the steps!

Setting Up WSL

If you are going to build this on Windows, I recommend using the Windows Subsystem for Linux, aka WSL. It allows you to run Linux directly on Windows. I already use Ubuntu in WSL, so I figured I would use a different image for this utility, so I didn’t accidentally break anything in my working Ubuntu WSL image.

If you aren’t using Windows but just want the instructions for a Debian-based system, you can skip to the next section.

First, install WSL on your computer. WSL is a feature of Windows that you can enable, assuming your computer supports virtualization and it is enabled in your BIOS. That discussion is outside the scope of this article. But if you can get WSL installed, I recommend using WSL version 2.

To install WSL and set it to version 2, open a PowerShell or command prompt:

wsl --install
wsl --set-default-version 2

Once WSL is installed, you will need to install the actual Linux distribution. In this case, we are installing Debian:

wsl --install -d Debian

A new window will pop up asking to create a username and password (inside Debian, it won’t affect your Windows logins). Don’t forget your password, you’ll be using it later on.

Once you have Debian running, all the rest of these instructions should be run in the WSL/Debian console.

Update Debian

The installation of Debian installed by WSL is very, very old. Let’s update it.

First, get all updates for the current release (you’ll need that password here):

sudo apt update
sudo apt upgrade
sudo apt autoremove

That applies all updates for the running release of Debian, which is “Stretch”. But that release is years old, so we need to update the release to the current version, which is “Bullseye”.

Edit the /etc/apt/sources.list file with your text editor of choice, running as root/sudo, and replace the contents of that file with the Bullseye sources:

deb http://deb.debian.org/debian bullseye main
deb http://deb.debian.org/debian-security/ bullseye-security main
deb http://deb.debian.org/debian bullseye-updates main

Now let’s run another update:

sudo apt update
sudo apt dist-upgrade
sudo apt autoremove

Install Dependencies

We need a lot of tools and libraries to build this utility! To install all of those packages, run this command:

sudo apt install git python3 python3-pip python3-venv build-essential cmake gcc libgl1-mesa-dev libglew-dev libtbb-dev libtbb2 libboost-all-dev libglib2.0-0

This will install about 1GB of files, so take a break while that runs.

Build the Pixar USD Tools

The conversion utility requires the Pixar USD toolkit, which we have to compile first. Here are the steps to build it into a local (non-root) folder:

Let’s make a folder under our home directory where we will build everything:

cd
mkdir usd
cd usd

Next, let’s setup a Python virtual environment for some more dependencies that are specific to Python, and install those dependencies:

python3 -m venv usd-env
source usd-env/bin/activate
pip3 install pyside2
pip3 install PyOpenGL

Next, download the USD toolkit source code:

git clone https://github.com/PixarAnimationStudios/USD.git

The glTF converter tool doesn’t work with the latest version of the USD toolkit. So we need to roll back the source code to a previous version:

cd USD
git checkout v20.11
cd ..

Finally, run the build!

python3 USD/build_scripts/build_usd.py USD-build

This step will take a while. A long while. On a 12th-gen i7, it takes about 20 minutes. On a 4th-gen i7, it took over an hour.

Building the Converter

The final steps! Here is how to build the actual conversion utilities.

First, we need a few more dependencies:

sudo apt install nasm
pip3 install Pillow

Next, we need one custom step to fix a linker problem when the compiler tries to find a library that is using the wrong name:

cd USD-build/lib
ln -s libboost_python39.so libboost_python.so
cd ../..

Now, download the source code for the utility:

git clone https://github.com/google/usd_from_gltf.git

And then build the code:

python3 usd_from_gltf/tools/ufginstall/ufginstall.py ufg-build USD-build --testdata

Assuming you were successful, you can now use the utility!

ufg_build/bin/usd_from_gltf source.gltf destination.usdz

I hope this was useful! Let me know if you see any improvements or corrections that need to be made.