Library, command-line tool, and import plugin for converting glTF models to [USD] (https://graphics.pixar.com/usd/docs/index.html) formatted assets for display in AR Quick Look.

Please note that this is not an officially supported Google product.

This is a C++ native library that serves as an alternative to existing scripted solutions. Its main benefits are improved compatibility with iOS and conversion speed (see Compatibility and Performance). It is treating USDZ as a transmission format rather than an interchange format. For more information about transmission and interchange file formats see here.

TLDR: Install it, then convert with: usd_from_gltf <source.gltf> <destination.usdz>

glTF is a transmission format for 3D assets that is well suited to the web and mobile devices by removing data that is not important for efficient display of assets. USD is an interchange format that can be used for file editing in Digital Content Creation tools (ie. Maya).

However, iOS Quick Look supports displaying USDZ files with a subset of the USD file specification. This tool converts glTF files to USDZ for display in Quick Look, attempting to emulate as much of glTF’s functionality as possible in iOS Quick Look runtime.

The emulation process is lossy. For example, to support double sided glTF materials, the geometry is doubled. This allows the converted glTF to display correctly on iOS, but importing back into a DCC application will not be the same data as the original source file.

This tool specifically addresses the use case of converting a file from glTF->USDZ->QuickLook. Going DCC->glTF optimizes the asset for runtime viewing, and may lose information if the converted USDZ is imported back in the DCC tool, like subdivision surfaces.

When converting glTF->USD->DCC, Apple's USDPython tools will better preserve the data in the glTF file at the cost of not having the same compatibility with existing versions of iOS Quick Look.

• Download and build USD. See the associated README for prerequisites and build steps. Refer to USD installation directory as {USD}.

• Install NASM.

  • (Linux) sudo apt-get install nasm
  • (OSX) brew install nasm (requires Homebrew)
  • (Windows) Use the installer for the latest stable release.

• Install PIL.

  • pip install Pillow

• Download usd_from_gltf source to {UFG_SRC}.

• Install to {UFG_BUILD} (with optional test data):

  python {UFG_SRC}/tools/ufginstall/ufginstall.py {UFG_BUILD} {USD} --testdata
  

• (Linux/OSX) Set LD_LIBRARY_PATH to the USD and usd_from_gltf lib directories. See ufginstall script output for the paths.

• (Optional) Add executable to PATH. See ufginstall script output for the exe path.

• (Optional) Build test data. See ufginstall script output for the ufgtest.py command.

• (Optional) Set PXR_PLUGINPATH_NAME so the glTF import plugin is available in Usdview. See ufginstall script output for the path.

The command-line tool is called usd_from_gltf and is in the {UFG_BUILD}/bin directory. Run it with (use --help for full documentation):

usd_from_gltf <source.gltf> <destination.usdz>

The library contains {UFG_SRC}/tools/ufgbatch/ufgbatch.py to facilitate batch conversion. Run it with (use --help for full documentation):

python {UFG_SRC}/tools/ufgbatch/ufgbatch.py my_tests.csv --exe "{UFG_BUILD}/bin/usd_from_gltf"

Each input CSV contains a list of conversion tasks of the form:

name,path/to/input.gltf,dir/to/output/usd[, optional usd_from_gltf flags]

The library also contains {UFG_SRC}/tools/ufgbatch/ufgtest.py to facilitate testing, and preview deployment. Run it with (use --help for full documentation):

python {UFG_SRC}/tools/ufgbatch/ufgtest.py my_tests.csv --exe "{UFG_BUILD}/bin/usd_from_gltf"

For development and testing, the ufgtest.py has a couple additional features:

• Golden file diffs. After a build completes, the tool compares built files against files in a known-good 'golden' directory. This is useful for determining if changes to the library affect generated data. This can be disabled with --nodiff.
• Preview web site deployment. This copies changed USDZ files (different from golden) to a directory and generates an index.html to view the listing in a browser, compatible with QuickLook on iOS. This can be disabled with --nodeploy.

The converter can be linked with other applications using the libraries in {UFG_BUILD}/lib/ufg. Call ufg::ConvertGltfToUsd to convert a glTF file to USD.

The plugin isn't necessary for conversion, but it's useful for previewing glTF files in UsdView.

To use it, set the PXR_PLUGINPATH_NAME environment variable to the directory containing plugInfo.json. See ufginstall script output for the path.