How to Create Nested USDZ Files

JULY 20, 2019   github   contact

Some of the most exciting announcements of this year's WWDC, as it relates to AR, were made by the Quick Look and web team. Which makes sense, if AR is going to catch on in a major way a big part of that will have to come from having adoption all across the web. Furthermore, Quick Look is a great way to quickly add an AR experience in your app with the system doing a lot of the heavy lifting. From gestures to lighting, shadows to sharing, Quick Look makes it easy to go from 3D model to AR app. This year's session, Advances in AR Quick Look, had a number of intriguing announcements, but one that I found particularly useful is the ability to have nested USDZ files, in which you can have multiple USDZ objects that can be arranged and placed independently. That only left one question: how do you make one?

Screenshot of AR sceen with multiple virtual objects arranged.

Placing multiple virtual objects independently using Quick Look.

After searching the internet for awhile, I stumbled across a tweet by @lDavixl that showed just how easy it is.

You can now create nested usdz files! Visit the AR Quick Look gallery page ( and download the usdz tools package. You’ll find the ‘usdzcreateassetlib’ tool which will help you create multi-models AR Quick Look experiences.

Happy viewing!

— David Lui (@lDavixl) June 20, 2019

If you've created USDZ files in the past, you likely know about $ xcrun usdz_converter. This year there's a whole new suite of USDZ tools which can be downloaded from Apple's AR Quick Look gallery. While it's still possible to use the old converter, it's recommended that you begin to use the new USD.command suite. In fact, if you have old USDZ models with transparency or semi-transparency you'll likely need to update them using the new tools using the fixOpacity command.

Once you've downloaded the new USDZ tools, you'll want to open the folder titled "usdzconvert." From there, you can double click on "usdzcreateassetlib," which will launch and execute the $ usdzcreateassetlib command, which will give you the hint:

    $ usdzcreateassetlib outputFile.usdz asset1.usdz [asset2.usdz [...]]

Which is saying that the usdzcreateassetlib command should be followed by the desired output path followed by all of the models that should be nested in the output file separated by spaces.

With that in mind, we're ready to create our USDZ asset library. You'll likely want to create a new folder that will hold all of the models you intend to include in your new library. Create a new folder in Finder and option + drag all of your models. Also option + drag the usdzcreateassetlib command you downloaded from the Quick Look gallery. Next $ cd into the directory you just created. From there, drag and drop the usdzcreateassetlib command into terminal. Next, type in the name of the output file you want, then drag and drop all of the models you'd like to include. After pressing enter, a new file will be created containing all of the models you've added.

I'm going to create a USDZ that will hold a number of models that represent items you'd find in a typical office setting. I created a folder named "OfficeLib" and copied five USDZ models into it. Then in Terminal, I changed directories to "OfficeLib." Finally the terminal command would be something like this:

    $ ./usdzcreateassetlib OfficeLib.usdz chair.usdz desk.usdz mug.usdz pen.usdz curtainWall.usdz curtainWall.usdz curtainWall.usdz curtainWall.usdz 

This command wraps the chair, desk, mug, pen, and four instances of curtain wall into one file called OffliceLib.usdz. If you have iOS 13 or higher installed and are using Safari, you can try the nested USDZ below.

Link to collection of office related virtual objects

Unfortunately, it seems that with large objects like the office ones I included, the device has a hard time keeping up, and with iOS 13.0 beta 4, it seems including the same object more multiple times results in it appearing only once. With the upcoming updates I'll see how things develop.

Marked up screenshot of AR sceen with multiple virtual office objects arranged.

Screenshot of the office library objects

You'll definitely want to test your model thoroughly. One easy way to do this is to simply send the USDZ to yourself through iMessage. Also, you'll likely want to check the system version of the device using #available as nested USDZ files won't load at all on devices running an operating system below 13.0. I've included another collection with smaller everyday objects that seems to work better.

Link to collection of Michel Foucault related virtual objects

One final collection.

Screenshot of AR sceen with multiple virtual toy farm objects arranged.

Screenshot of the farm collection objects. Model made by EdwinRC

Link to collection of cartoonish toy farm virtual objects

Model made by EdwinRC

In conclusion, nested USDZ files are a great way to add a more immersive AR experience to your app and support for USDZ by Apple is expanding. While fairly easy to use, it's clear that iOS 13 and new USDZ support is still in beta. Some of the things I've experienced, just creating this blog post: objects being at a very different scale from what they are in their individual USDZ file, Xcode crashing when opening a USDZ file, visible artifacts when moving objects within the Quick Look scene, and broken opacity. Much of these are likely to be corrected before iOS 13 actually ships, though you may have to make adjustments to your models.

Overall AR support in Quick Look is a huge technological achievement and a boon for app developers. As always, feel free to send me feedback.