A comprehensive suite of USD (Universal Scene Description) tools for converting, validating, and manipulating 3D assets for use with AR/VR applications, particularly for Apple platforms.
The easiest way to use all USD operations is through the new centralized usd_tool.py:
# Convert any 3D file to USDZ (automatic texture detection!)
./usd_tool.py convert model.obj model.usdz
# Run a full pipeline (convert → condition → validate)
./usd_tool.py pipeline model.gltf final.usdz --condition --validate
# Batch convert an entire directory
./usd_tool.py batch input_dir/ output_dir/ --recursive
# See all available commands
./usd_tool.py --helpNo more manual texture assignment! The tool now automatically:
- Reads MTL files for OBJ models (when available)
- Auto-detects textures by filename patterns when no MTL exists
- Supports AVIF textures for superior compression and smaller files
- Mixed format support - AVIF, PNG, JPEG in the same USDZ
- Packages all textures into USDZ files automatically
- Ensures ARKit compliance with Apple-confirmed AVIF support
- Zero Configuration: OBJ files work out-of-the-box with textures
- Smart Fallback: MTL files take priority, auto-detection as backup
- Modern Formats: AVIF support for 40-80% smaller texture files
- Complete Materials: Full PBR support including displacement mapping
- ARKit Ready: Native AVIF validation with modern iOS compatibility
- Pattern Matching: Recognizes 8+ texture types by common naming conventions
- Batch Processing: Auto-detection works in batch and pipeline modes
This package contains:
usd_tool.py- NEW: Unified command-line interface for all USD operationsusdzconvert- Python-based tool to convert from various file formats to usdzusdARKitChecker- Python-based tool for usdz validationUSD-Support-Scripts/- Apple's official USD conditioning and variant tools- Precompiled macOS Python modules for Pixar's USD library
- Sample scripts that demonstrate how to write USD files
fixOpacity- Tool to fix transparency issuesusdzcreateassetlib- Generate asset libraries from multiple assetsusdzaudioimport- Attach audio files to usdz files- Docker support - Run all tools in containers without local setup
After installation you can relocate the files.
The tools now require Python 3.9+ with the usd-core package:
# Install dependencies
python3 -m pip install -r requirements.txtNote: The legacy precompiled USD library was built for Python 3.7.9, but the modern usd-core package from PyPI works with Python 3.9+.
The easiest way to start is to double-click USD.command in the Finder, which opens a Terminal with environment variables set.
# Build the Docker image
docker build -t usd-tool:latest .
# Run commands without local setup
docker run -v $(pwd)/data:/data usd-tool:latest convert model.obj model.usdzFor more details, including demos, see the WWDC 2019 session "Working with USD": https://developer.apple.com/videos/play/wwdc2019/602/
The new usd_tool.py provides these commands:
| Command | Description | Example |
|---|---|---|
convert |
Convert 3D files to USDZ | ./usd_tool.py convert model.obj model.usdz |
validate |
Check USDZ for AR compatibility | ./usd_tool.py validate model.usdz |
condition |
Fix compatibility issues | ./usd_tool.py condition input.usdz -o output.usdz |
variants |
Combine files as variants | ./usd_tool.py variants -m red.usdz blue.usdz -o combined.usdz |
batch |
Process entire directories | ./usd_tool.py batch input/ output/ --recursive |
pipeline |
Chain operations | ./usd_tool.py pipeline model.fbx final.usdz --condition --validate |
opacity |
Fix transparency issues | ./usd_tool.py opacity model.usdz |
assetlib |
Create asset libraries | ./usd_tool.py assetlib asset1.usdz asset2.usdz -o library.usdz |
audio |
Import audio | ./usd_tool.py audio model.usdz sound.mp3 -o output.usdz |
| Old Command | New Unified Command |
|---|---|
usdzconvert model.obj out.usdz |
./usd_tool.py convert model.obj out.usdz |
usdARKitChecker file.usdz |
./usd_tool.py validate file.usdz |
python3 usd_conditioner.py in.usdz |
./usd_tool.py condition in.usdz -o out.usdz |
fixOpacity model.usdz |
./usd_tool.py opacity model.usdz |
For Docker usage, see DOCKER_USAGE.md.
For OBJ files, the tool now provides zero-configuration texture handling:
# Automatically reads textures from model.mtl
./usd_tool.py convert model.obj model.usdzPlace textures in the same folder as your OBJ with these naming patterns:
- Diffuse:
*diffuse*,*albedo*,*color*,*_d.* - Normal:
*normal*,*bump*,*_n.* - Roughness:
*roughness*,*rough*,*_r.* - Metallic:
*metallic*,*metal*,*_m.* - Occlusion:
*occlusion*,*ao*,*_o.* - Opacity:
*opacity*,*alpha*,*_a.* - Emissive:
*emissive*,*glow*,*_e.* - Displacement:
*displacement*,*height*,*disp*,*_disp.*
Examples: chair_diffuse.jpg, MyMaterial_normal.png, wood_roughness.tga
The tools now support AVIF format - the next-generation image format providing:
- 40-80% smaller files than JPEG/PNG with better quality
- Native ARKit support on modern iOS devices
- Mixed format workflows - use AVIF alongside PNG/JPEG
# Convert with AVIF textures
./usd_tool.py convert model.obj output.usdz \
-diffuseColor albedo.avif \
-normal normal.avif \
-roughness roughness.avif
# Mixed formats for optimal results
./usd_tool.py convert model.obj output.usdz \
-diffuseColor color.avif \ # AVIF for color (smaller)
-displacement height.png \ # PNG for displacement (compatibility)
-opacity alpha.png # PNG for alpha (precision)All USD material inputs are now supported, including displacement:
| Input | Description | Recommended Format |
|---|---|---|
-diffuseColor |
Base color/albedo | AVIF, JPEG |
-normal |
Normal/bump maps | AVIF, PNG |
-roughness |
Surface roughness | AVIF, PNG |
-metallic |
Metallic values | AVIF, PNG |
-occlusion |
Ambient occlusion | AVIF, PNG |
-displacement |
Height/displacement | PNG (best compatibility) |
-opacity |
Transparency/alpha | PNG (precision) |
-emissiveColor |
Glow/emission | AVIF, PNG |
-clearcoat |
Clear coat layer | AVIF, PNG |
-clearcoatRoughness |
Clear coat roughness | AVIF, PNG |
Supported image formats: AVIF, PNG, JPEG, TGA, BMP, TIFF, EXR, HDR
usdzconvert is a Python script that converts obj, gltf, fbx, abc, and usda/usdc/usd assets to usdz.
It also performs asset validation on the generated usdz.
For more information, run
usdzconvert -h
To export .usdz files that play back correctly on iOS 12, use usdzconvert's -iOS12 compatibility switch. When run with -iOS12, usdzconvert will use the Python Imaging Library (PIL) module to do texture conversion.
If your Python environment is missing necessary dependencies like PIL (Pillow) or numpy, you can install them using the provided requirements file:
python3 -m pip install -r requirements.txt
Note that FBX support in usdzconvert requires both Autodesk's FBX SDK and FBX Python bindings to be installed on your system.
To make FBX bindings available to Python, uncomment the line
export PYTHONPATH=$PYTHONPATH:"/Applications/Autodesk/FBX Python SDK/2020.2.1/lib/Python37_x64"
in USD.command, and adjust the path to point to the location of fbx.so (e.g., for Python 3.7, 3.9, etc., matching your environment).
usdARKitChecker is a Python script that validates existing usdz files. It is automatically run by usdzconvert, but can also be used as a stand-alone tool to validate files from other sources.
For more information, run
usdARKitChecker -h
Currently usdARKitChecker consists of three parts:
- validation through Pixar's
usdchecker - mesh attribute validation
- UsdPreviewSurface material validation
- NEW: Native AVIF format support with Apple-confirmed compatibility
This library was compiled using version 3.7.9 of Python.
This library was compiled using version 22.03 of the public USD GitHub repository with the following build script arguments (see USDPython/README.md for further details):
python3.7 USD/build_scripts/build_usd.py --build-args TBB,extra_inc=big_iron.inc --python --no-imaging --docs --no-usdview --build-monolithic USDPython
If you prefer to set your environment variables directly ,
To start using USD in Python, set your PATH and PYTHONPATH variables as follows (replace <PATH_TO_USDPYTHON> with the path to this USDPython folder):
export PATH=$PATH:<PATH_TO_USDPYTHON>/USD
export PYTHONPATH=$PYTHONPATH:<PATH_TO_USDPYTHON>/USD/lib/python
You should then be able to start using the USD library in Python 3 (if using a compatible USD build):
> python3
Python 3.9.x ...
Type "help", "copyright", "credits" or "license" for more information.
>>> import pxr
>>>
The samples folder contains a set of simple scripts that focus on different aspects of writing USD data, such as geometry, materials, skinning and animation.
Each script generates a .usd and a .usdz file in the assets sub folder, and also prints the generated .usd file's content.
| Script | Purpose |
|---|---|
101_scenegraph.py |
creates a scene graph |
102_mesh.py |
creates a cube mesh |
103_simpleMaterial.py |
creates a simple PBR material |
104_texturedMaterial.py |
creates a cube mesh and assigns it a PBR material with a diffuse texture |
105_pbrMaterial.py |
creates a cube mesh and assigns it a more complex PBR material with textures for normal, roughness and diffuse channels |
106_meshGroups.py |
creates a cube mesh with two mesh groups and assigns each a separate material |
107_transformAnimation.py |
builds a scene graph of several objects and sets (animated) translate, rotate, and scale transforms |
109_skinnedAnimation.py |
creates an animated skinned cube |
201_subdivision.py |
creates a subdivided cube with creases |
202_references.py |
creates an asset file then a reference file that reference and overwrite the asset file |
If you converted your usdz asset with Xcode's usdz_converter, and it has translucent materials that render opaque in iOS 13, use this script to correct the asset's translucent materials:
fixOpacity model.usdz
usdzcreateassetlib is a script that generates a single-file asset library from multiple usdz assets. The result is a nested usdz file that contains the source usdz assets and references them in a variant set. This script does not depend on the USD library, which should make it easy to deploy on servers.
usdzaudioimport is a script to attach sound/audio files into existing a usdz file. With this tool users can create SpatialAudio nodes in usdz file and specify parameters for it. For more information, run:
usdzaudioimport -h