These USD file-format-plugins allow the interchange between Pixar's USD (.usd
, .usda
, .usdz
) and the following file formats, with cross platform support (windows
, macos
, and linux
):
Plugin | File Format | Extension |
---|---|---|
usdfbx | Autodesk's FBX | .fbx |
usdgltf | Khronos' glTF | .gtlf .glb |
usdobj | Wavefront's obj | .obj |
usdply | Polygon File Format | .ply |
usdstl | STL file format | .stl |
Supported features legend:
✅ Supported
⚠️ Supported with known issues
❌ Not supported
⦸ Not applicable/no support planned
The following tools are needed:
- C/C++ compiler (MSVC 19, GCC, Clang, Xcode)
- clang-format 16.0.0
- Python 3.10
- CMake 3.24
- Doxygen 1.9.8
The following dependencies are needed:
Dependency | Version | Affects | Optional |
---|---|---|---|
Pixar USD | 23.08 | all | no |
GTest | 1.11.0 | all tests | yes |
FBX SDK | 2020.2.1 | usdfbx | no |
LibXml2 | 2.10.0 | usdfbx | no |
Zlib | 1.2.11 | usdfbx | no |
TinyGltf | 2.8.2 | usdgltf | no |
Draco | 1.56 | usdgltf | yes |
Fmt | 10.1.1 | usdobj | no |
FastFloat | 1.1.2 | usdobj | no |
Happly | cfa2611 | usdply | no |
-
Install a C/C++ compiler.
-
Install clang-format.
-
Install cmake.
-
Install python and the following pip components:
pyside6
,pyopengl
. -
Build and install USD entering in a terminal (in windows a x64 Native Tools Command prompt):
python <USD_SOURCE_PATH>/build_scripts/build_usd.py <USD_INSTALL_PATH> --draco --openimageio --build-variant release
Add
--build-target universal
for universal binaries in macos.If adding
--openimageio
you may need these fixes:Setup USD environment variables:
<USD_INSTALL_PATH>/bin
toPATH
<USD_INSTALL_PATH>/lib
toPATH
in windows, or toLD_LIBRARY_PATH
in linux, mac<USD_INSTALL_PATH>/lib/python
toPYTHONPATH
In linux you may need these other dependencies:
sudo apt update sudo apt install libgl1-mesa-dev mesa-common-dev
-
Install FBX SDK.
-
You can install GTest, ZLIB, TinyGltf, Draco, fmt, FastFloat, Happly and OpenImageIO, or let cmake fetch them in the next steps (except for OpenImageIO). Also, you can leverage the installation of ZLIB, Draco and OpenImageIO included in USD.
git clone https://github.com/adobe/USD-Fileformat-plugins
To configure, build and install go to the project root folder and, using a multi-configuration backend (MSVC, ...) enter:
cmake -S . -B build -DCMAKE_INSTALL_PREFIX=bin <OPTIONS>
cmake --build build --config release
cmake --install build --config release
or using a single-configuration backend (Make, ...) enter:
cmake -S . -B build -DCMAKE_INSTALL_PREFIX=bin -DCMAKE_BUILD_TYPE=Release <OPTIONS>
cmake --build build
cmake --install build
where:
<OPTIONS>
is a list of extra options, as follows:
Option | Description | Default | Affects |
---|---|---|---|
-Dpxr_ROOT | Points to the USD installation | empty | all |
-DGTest_ROOT | Points to the GTest installation | empty | all tests |
-DFBXSDK_ROOT | Points to the Fbx installation | empty | usdfbx |
-DZLIB_ROOT | Points to the ZLIB installation | empty | usdfbx |
-DLibXml2_ROOT | Points to the LibXml2 installation | empty | usdfbx |
-DTinyGLTF_ROOT | Points to the TinyGLTF installation | empty | usdgltf |
-Ddraco_ROOT | Points to the draco installation | empty | usdgltf |
-Dfmt_ROOT | Points to the fmt installation | empty | usdobj |
-DFastFloat_ROOT | Points to the FastFloat installation | empty | usdobj |
-DHapply_ROOT | Points to the Happly installation | empty | usdply |
-DUSD_FILEFORMATS_BUILD_TESTS | Enables tests | ON | all tests |
-DUSD_FILEFORMATS_ENABLE_FBX | Enables fbx plugin | ON | usdfbx |
-DUSD_FILEFORMATS_ENABLE_GLTF | Enables gltf plugin | ON | usdgltf |
-DUSD_FILEFORMATS_ENABLE_OBJ | Enables obj plugin | ON | usdobj |
-DUSD_FILEFORMATS_ENABLE_PLY | Enables ply plugin | ON | usdply |
-DUSD_FILEFORMATS_ENABLE_STL | Enables stl plugin | ON | usdstl |
-DUSD_FILEFORMATS_ENABLE_DRACO | Enables draco in usdgltf | OFF | usdgltf |
-DUSD_FILEFORMATS_FORCE_FETCHCONTENT | Forces FetchContent for various packages | OFF | all |
-DUSD_FILEFORMATS_FETCH_GTEST | Forces FetchContent for GTest | ON | all tests |
-DUSD_FILEFORMATS_FETCH_TINYGLTF | Forces FetchContent for TinyGLTF | ON | usdgltf |
-DUSD_FILEFORMATS_FETCH_ZLIB | Forces FetchContent for Zlib | OFF | usdfbx |
-DUSD_FILEFORMATS_FETCH_LIBXML2 | Forces FetchContent for LibXml2 | OFF | usdfbx |
-DUSD_FILEFORMATS_FETCH_HAPPLY | Forces FetchContent for Happly | ON | usdply |
-DUSD_FILEFORMATS_FETCH_FMT | Forces FetchContent for Fmt | ON | usdobj |
-DUSD_FILEFORMATS_FETCH_FASTFLOAT | Forces FetchContent for FastFLoat | ON | usdobj |
-DUSD_FILEFORMATS_ENABLE_ASM | Generate a ASM based material network on layerwrite | OFF |
ZLIB, Draco and OpenImageIO packages are hinted to search into the USD installation by default. Override this by setting their ROOT or their FETCH variables (no fetch for OIIO).
The previous commands will place intermediate files into the folder build
and install binaries into the folder bin
.
Also, make the plugins discoverable by USD to complete installation, by adding the path <INSTALL_PATH>/plugin/usd
to the PXR_PLUGINPATH_NAME
environment variable (in this example: USD-Fileformat-plugins/bin/plugin/usd
).
- Note when building on Linux:
-DUSD_FILEFORMATS_ENABLE_CXX11_ABI=ON
- Requires USD built with "--openimageio"
python ./USD/build_scripts/build_usd.py ./usd-install --build-shared --usd-imaging --tools --generator <GENERATOR> --openimageio --build-variant release
python ./USD/build_scripts/build_usd.py ./usd-install --use-cxx11-abi=1 --build-shared --usd-imaging --tools --generator <GENERATOR> --openimageio --build-variant release
- Open your terminal and run the following commands to install the required Python packages:
pip install -r scripts/requirements.txt
Environment Variables
set PATH=%PATH%;.\USD-Fileformat-plugins\bin\bin;.\USD-Fileformat-plugins\bin\plugin\usd
set PXR_PLUGINPATH_NAME=%PXR_PLUGINPATH_NAME%;.\USD-Fileformat-plugins\bin\plugin\usd
export PATH=$PATH:./USD-Fileformat-plugins/bin/bin:./USD-Fileformat-plugins/bin/plugin/usd
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:./USD-Fileformat-plugins/bin/lib:./USD-Fileformat-plugins/bin/lib64
export PXR_PLUGINPATH_NAME=$PXR_PLUGINPATH_NAME:./USD-Fileformat-plugins/bin/plugin/usd
Or Copy plugins:
- Copy the installed plugins and dependent shared libraries to the specified folder:
mkdir -p ./LOCAL_USD_INSTALL/plugin/usd cp -r ./USD-Fileformat-plugins/bin/plugin/usd/* ./LOCAL_USD_INSTALL/plugin/usd/ cp ./USD-Fileformat-plugins/bin/bin/* ./LOCAL_USD_INSTALL/plugin/usd/
- Dependencies
pip install -r ../USD-Fileformat-plugins/scripts/requirements.txt
- Use pytest to run the tests:
pytest ./USD-Fileformat-plugins/test/test.py
- To generate new baseline data for tests, run the following command:
python ./USD-Fileformat-plugins/test/test.py --generate_baseline
USD will now be able to work with the supported files, for example:
- Use the USD tools on fbx:
usdview <fbx> # Converts FBX to USD
usdcat <fbx> # Converts FBX to USD
usdcat <usd> -o <fbx> # Converts USD to FBX
- Use the C++ USD API:
#include <pxr/usd/usd/stage.h>
UsdStageRefPtr stage = UsdStage::Open("cube.fbx")
stage->Export("cube.usd")
- Use the Python USD API:
from pxr import Usd
stage = Usd.Stage.Open("cube.fbx")
stage.Export("cube.usd")
Refer to each plugin's README for more details.
To generate the documentation go to the project root folder and enter:
doxygen
The resulting documentation will be placed at the docs
folder.