TinyUSDZ
is secure, portable and dependency-free(depends only on C++ STL. Other 3rd-party libraries included. Yes, you don't need pxrUSD/OpenUSD library!) USDZ/USDC/USDA library written in C++14.
Wasm demo! (requires 10MB file download)
(from https://github.com/syoyo/Vulkan-glTF-USDZ-PBR)
(from ASF MaterialXViewer fork https://github.com/lighttransport/materialx)
Linux | Windows | macOS | iOS | Android | |
---|---|---|---|---|---|
dev |
Linux | Windows | macOS | iOS | Android | WASM(WASI) | WASM(Emscripten) | |
---|---|---|---|---|---|---|---|
dev | ✅ 64bit ✅ 32bit ✅ aarch64 | ✅ 64bit ✅ 32bit ✅ ARM64/ARM32 | ✅ | ✅ | ✅ | ✅ sandbox/wasi | ✅ sandbox/emscripten |
TinyUSDZ is in v0.8.0 release candidate. Core loading feature(both USDA and USDC) is now working and production-grade(And no seg fault for corrupted USDA/USDC/USDZ input). Somewhat working Tydra framwork for rendering USD model with OpenGL/Vulkan-like renderer. https://github.com/syoyo/tinyusdz/issues/148
v0.8.0 is basically Flattened scene only(i.e, USDA/USDC generated by using pxrUSD's usdcat --flatten
or USDZ scene).
Composition features are work-in-progress(experimental Composition feature support in v0.8.0. Better composition feature in next major release v0.9.0(Q3/2024 expected) planned)
Remaining tasks for v0.8.0 release are writing examples, demos and utility functions(Tydra. Especially access to Material/Shader attributes).
Please see doc/status.md for more details
c-tinyusd
) for language bindings
We've opened Github Discussions page! https://github.com/syoyo/tinyusdz/discussions
TinyUSDZ has first priority of considering security and stability.
USDZ(USDC) is a binary format. To avoid out-of-bounds access, out-of-memory, and other security issues when loading malcious USDZ(e.g. USDZ file from unknown origin), TinyUSDZ has a memory budget feature to avoid out-of-memory issue.
To limit a memory usage when loading USDZ file, Please set a value max_memory_limit_in_mb
in USDLoadOptions.
TinyUSDZ source codes(and some external third party codes) are also checked by Address Sanitizer, CodeQL and Fuzzer.
See tests/fuzzer . For building fuzzer tests, you'll need Meson and Ninja.
If you need to deal with arbitrary USD files from unknown origin(e.g. from internet, NFT storage. Whose may contain malcious data), it is recommended to use TinyUSDZ in sandboxed environment(RunC, FlatPak, WASI(WASM)). Run in WASI is recommended at the moment.
TinyUSDZ does not use C++ exceptions and can be built without threads. TinyUSDZ supports WASM and WASI build. So TinyUSDZ should runs well on various Web platform(WebAssembly. No SharedArrayBuffer, Atomics and WebAssembly SIMD(which is not yet available on iOS Safari) required) and sandboxed environment(WASI. Users who need to read various USD file which possibly could contain malcious data from Internet, IPFS or blockchain storage).
See sandbox/wasi/ for Building TinyUSDZ with WASI toolchain.
USD itself is a generic container of 3D scene data.
Tydra is an interface to Renderers/Viewers and other DCCs. Tydra may be something like Tiny version of pxrUSD Hydra, but its API is completely different. See src/tydra/README.md for the background.
TinyUSDZ does not support Reality Composer file format(.reality
) since it uses proprietary file format and we cannot understand it(so no conversion support from/to Reality also).
TinyUSDZ focuses on loading/writing USDA/USDC/USDZ functionalities. Example viewer is just for demo purpose.
If you need commercial support, eco-system development(e.g. plug-ins, DCC tools on top of TinyUSDZ) or production-grade USDZ model viewer(e.g. embed TinyUSDZ to your AR app, 3D NFT Android mobile viewer capable of displaying (encrypted) USDZ model), please contact Light Transport Entertainment, Inc. : https://goo.gl/forms/1p6uGcOKWGpXPHkA2
We are also looking for sponsors. If you are interested in sponsoring(or donating) to TinyUSDZ project, please also contact Light Transport Entertainment, Inc. for details: https://goo.gl/forms/1p6uGcOKWGpXPHkA2
CMakePresets.json
, but seems a bit troublesome in VS2022 https://github.com/lighttransport/tinyusdz/pull/182#issuecomment-2236676598 . If you encounter an issue, use vcsetup.bat
to setup .sln for a while.Compilation with C++17 is also supported. Compile on C++20 and C++23 could be possible, but not well tested, since C++20/C++23 compiler is not yet mature(as of 2024/01))
If you are using CMake, just include tinyusdz repo with add_subdirectory
and set include path to <tinyusdz>/src
We recommend to use CMake 3.24 or later.
(Mininum requirement is 3.16)
...
# TinyUSDZ examples, tests and tools builds are disabled by default when
# tinyusdz is being built as a library with `add_subdirectory`
add_subdirectory(/path/to/tinyusdz tinyusdz)
target_include_directories(YOUR_APP PRIVATE "/path/to/tinyusdz/src")
# Namespaced static library target `tinyusdz::tinyusdz_static` is provided.
# At the moment we recommend to use static build of TinyUSDZ.
# You can use alias target `tinyusdz_static` also for legacy cmake version.
target_link_libraries(YOUR_APP PRIVATE tinyusdz::tinyusdz_static)
# For TinyUSDZ DLL(shared) library target, you can use
# `tinyusdz` library target
Another way is simply copy src
folder to your app, and add *.cc
files to your app's build system.
All include paths are set relative from src
folder, so you can just add include directory to src
folder.
See <tinyusdz>/CMakeLists.txt
and examples/sdlviewer/CMakeLists.txt for details.
TinyUSDZ does not generate any header files and source files before the build and after the build(before the installation stage), so you don't need to take care of any pre-processing and post-processing of source tree. For example, USD Ascii parser uses hand-written C++ code so no Bison/flex/PEG processing involved.
It may not be recommend to use tinyusdz as a git submodule, since the repo contains lots of codes required to build TinyUSDZ examples but these are not required for your app.
Please see CMake build options
and CMakeLists.txt
. In most case same identifier is defined from cmake build options: For example if you specify -DTINYUSDZ_PRODUCTION_BUILD=1
for cmake argument, TINYUSDZ_PRODUCTION_BUILD
is defined.
Cmake build is provided.
$ mkdir build
$ cd build
$ cmake ..
$ make
Please take a look at scripts/bootstrap-cmake-*.sh
for some build configuraions.
Visual Studio 2019 and 2022 are supported.
CMakePresets.json
is provided for easier build on Visual Studio 2019 and Visual Studio 2022, but has lot of limitations(and seems parallel build is not working well so build is slow).
If you want flexibility, ordinary cmake .sln
generation approach by invoking vcsetup.bat
recommended.
(Edit VS version in vcsetup.bat
as you with before the run)
MinGW native and cross-compiling example using llvm-mingw(clang) is provided.
See scripts/bootstrap-cmake-mingw-win.sh
and scripts/bootstrap-cmake-llvm-mingw-cross.sh
for details.
One of benefit to use llvm-mingw is address sanitizer support on Windows app.
To run app(.exe
, you'll need libunwind.dll
and libc++.dll
on your working directory or search path)
For Windows native build, we assume ninja.exe
is installed on your system(You can use it from Meson package)
TINYUSDZ_PRODUCTION_BUILD
: Production build. Do not output debugging logs.TINYUSDZ_BUILD_TESTS
: Build testsTINYUSDZ_BUILD_EXAMPLES
: Build examples(note that not all examples in examples
folder are built)TINYUSDZ_WITH_OPENSUBDIV
: Use OpenSubviv to tessellate subdivision surface.
osd_DIR
cmake environment variable.TINYUSDZ_WITH_AUDIO
: Support loading audio(mp3 and wav).TINYUSDZ_WITH_EXR
: Support loading EXR format HDR texture through TinyEXR.TINYUSDZ_WITH_PXR_COMPAT_API
: Build with pxrUSD compatible API.Assume ninja.exe is installed and path to ninja.exe is added to your %PATH%
Edit path to MSVC SDK and Windows SDK in bootstrap-clang-cl-win64.bat
, then
> bootstrap-clang-cl-win64.bat
> ninja.exe
usdcat
in pxrUSD).
tusdcat
also do USD composition(flatten
) and contains TinyUSDZ Composition API usecase.tusdcat
usda_parser Parse USDA and print it as Ascii.tusdcat
usdc_parser Parse USDC and print it as Ascii.See examples directory for more examples, but may not actively maintained except for the above examples.
rendermesh-refactor
branchSee prim_format.md and preview_surface.md
// TinyUSDZ is not a header-only library, so no TINYUSDZ_IMPLEMENTATIONS
#include "tinyusdz.hh"
// Include pprinter.hh and value-pprint.hh if you want to print TinyUSDZ classes/structs/enums.
// `tinyusdz::to_string()` and `std::operator<<` for TinyUSDZ classes/enums are provided separately for faster compilation
#include <iostream>
#include "pprinter.hh"
#include "value-pprint.hh"
int main(int argc, char **argv) {
std::string filename = "input.usd";
if (argc > 1) {
filename = argv[1];
}
tinyusdz::Stage stage; // Stage in USD terminology is nearly meant for Scene in generic 3D graphics terminology.
std::string warn;
std::string err;
// Auto detect USDA/USDC/USDZ
bool ret = tinyusdz::LoadUSDFromFile(filename, &stage, &warn, &err);
if (warn.size()) {
std::cout << "WARN : " << warn << "\n";
}
if (!ret) {
if (!err.empty()) {
std::cerr << "ERR : " << warn << "\n";
}
return EXIT_FAILURE;
}
// Print Stage(Scene graph)
std::cout << tinyusdz::to_string(stage) << "\n";
// You can also use ExportToString() as done in pxrUSD
// std::cout << stage.ExportToString() << "\n";
// stage.metas() To get Scene metadatum,
for (const Prim &root_prim : stage.root_prims()) {
std::cout << root_prim.absolute_path() << "\n";
// You can traverse Prim(scene graph object) using Prim::children()
// See examples/api_tutorial and examples/tydra_api for details.
}
return EXIT_SUCCESS;
}
Please see api_tutorial
Please see tydra_api
Python binding and prebuilt packages(uploadded on PyPI) are provided.
See python/README.md and doc/python_binding.md for details.
CI build script is a build script trying to build TinyUSDZ in self-contained manner as much as possible(including custom Python build)
T.B.W.
Build custom Python,
> ci-build-python-lib.bat
then build TinyUSDZ by linking with this local Python build.
> ci-build-vs2022.bat
clang-cl(MSVC cl.exe) + MSVC SDK cross compile is also supported.
Please take a look at doc/wine_cl.md
You can build pure Windows build of TinyUSDZ on Linux CI machine.
TinyUSDZ is primarily licensed under Apache 2.0 license. Some helper code is licensed under MIT license.