• Stars
    star
    283
  • Rank 146,066 (Top 3 %)
  • Language
    C++
  • License
    MIT License
  • Created over 4 years ago
  • Updated over 1 year ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Tiny, dependency-free USDZ/USDA/USDC library written in C++14

Tiny USDZ library in C++14

TinyUSDZ is secure, portable and dependency-free(depends only on C++ STL. Other 3rd-party libraries included. Yes, you don't need pxrUSD library!) USDZ/USDC/USDA library written in C++14.

Mid-term todo

  • Experimental composition support #25
    • subLayers
    • references
    • payload(no delayed load)
    • inherits
    • variantSet
    • Validate composition is correctly operated.
  • Tydra: Handy data structure converter for rendering #31
  • MaterialX #86
  • Improve support for Blender USD export/import
  • tusdview(TinyUSDZ version of usdview)

Build status

Linux Windows macOS iOS Android
dev Linux Build Windows CI build
Windows ARM CI build
macOS Build iOS Build Android arm64v8a Build

Supported platforms

Linux Windows macOS iOS Android WASM(WASI) WASM(Emscripten)
dev βœ… 64bit
βœ… 32bit
βœ… aarch64
βœ… 64bit
βœ… 32bit
βœ… ARM64/ARM32
βœ… βœ… βœ… βœ… sandbox/wasi βœ… sandbox/emscripten

Python binding(testing. currently not working)

https://pypi.org/project/tinyusdz/

Python binding is very early alpha testing stage. Not working at the moment.

You can install Python prebuilt wheel using

$ python -m pip install tinyusdz
Linux Windows macOS 11(Big Sur) or later macos 10
3.7 βœ… 64bit
βœ… 32bit
βœ… aarch64
βœ… 64bit
βœ… 32bit
βœ… ARM64
βœ… arm64 🚫 universal2
βœ… Intel
3.8 βœ… 64bit
βœ… 32bit
βœ… aarch64
βœ… 64bit
βœ… 32bit
βœ… ARM64
βœ… arm64 βœ… universal2
βœ… Intel
3.9 βœ… 64bit
βœ… 32bit
βœ… aarch64
βœ… 64bit
βœ… 32bit
βœ… ARM64
βœ… arm64 βœ… universal2
βœ… Intel
3.10 βœ… 64bit
βœ… 32bit
βœ… aarch64
βœ… 64bit
βœ… 32bit
βœ… ARM64
βœ… arm64 βœ… universal2
βœ… Intel
3.11 βœ… 64bit
βœ… 32bit
βœ… aarch64
βœ… 64bit
βœ… 32bit
βœ… ARM64
βœ… arm64 βœ… universal2
βœ… Intel

NOTE: Windows ARM64 binary is provided using cross-compiling. Its not well tested.

Status

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).

v0.8.0 is 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(Q4/2023 expected) planned)

Remaining tasks for v0.8.0 release are writing examples, demos and utility functions(Tydra. Especially access to Material/Shader attributes).

  • USDZ/USDC(Crate) parser
    • USDC Crate version v0.8.0(most commonly used version as of 2022 Nov) or higher is supported.
  • USDZ/USDC(Crate) writer (Work-in-progress)
  • USDA parser(Hand-written from a scratch. No Bison/Flex dependency!)
  • USDA writer
  • Support basic Primitives(Xform, Mesh, BasisCurves, etc.), basic Lights and Shaders(UsdPreviewSurface, UsdUVTexture, UsdPrimvarReader)
  • Experimental support of some Composition features #25
    • subLayers
    • references
    • payload
    • inherits
    • variants
    • specializes

Please see doc/status.md for more details

  • Basic C API(c-tinyusd) for language bindings
  • Write simple SDL viewer example(2023 Summer expected)
  • Write iOS and Android example(2023 Summer expected)
  • Vulkan or OptiX/HIP RT raytracing viewer example
  • USD <-> glTF converter example
  • Web demo with Three.js?

Discussions

We've opened Github Discussions page! https://github.com/syoyo/tinyusdz/discussions

Security and memory budget

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.

Fuzzer

See tests/fuzzer . For building fuzzer tests, you'll need Meson and Ninja.

Web platform(WASM) and sandboxed environment(WASI)

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.

Tydra

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.

  • Image color space
  • More details are T.B.W.

Notice

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).

Commercial support

TinyUSDZ focuses on loading/writing USDA/USDC/USDZ functionalities. Example viewer is just for demo purpose. syoyo does not provide commercial support as an individual.

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 have a plan to manage TinyUSDZ project under Light Transport Entertainment Inc. (By relicensing to Apatch 2.0)

Projects using TinyUSDZ

Other related projects

Supported platforms

  • Linux 64bit or later
    • ARM AARCH64
    • x86-64
    • RISC-V(Should work)
    • SPARC, POWER(Big endian machine). May work(theoretically)
  • Android arm64v8a
  • iOS
  • macOS(Arm, x86-64)
  • Windows 10 64bit or later
    • Windows ARM
    • clang-cl + MSVC SDK cross compile
  • WebAssembly
  • WASI(through WASI toolchain)

Requirements

  • C++14 compiler
    • gcc 4.9 or later
    • Visual Studio 2019 or later(2017 may compiles)
      • VS2019 16.10 or later you can use CMakePresets.json for easier building.
      • Can be compiled with standalone MSVC compilers(Build Tools for Visual Studio 2019)
    • clang 3.4 or later https://clang.llvm.org/cxx_status.html
    • llvm-mingw(clang) supported
    • MinGW gcc supported, but not recommended(You may got compilation failure depending on your build configuration: #33 , and linking takes too much time if you use default bfd linker.). If you want to compile TinyUSDZ in MinGW environment, llvm-mingw(clang) is recommended to use.

Compilation with C++17 is also supported.

Build

Integrate to your app

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.

Compiler defines

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

Cmake build is provided.

Linux and macOS

$ mkdir build
$ cd build
$ cmake ..
$ make

Please take a look at scripts/bootstrap-cmake-*.sh for some build configuraions.

Visual Studio

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)

LLVM-MinGW build

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)

CMake build options

  • TINYUSDZ_PRODUCTION_BUILD : Production build. Do not output debugging logs.
  • TINYUSDZ_BUILD_TESTS : Build tests
  • TINYUSDZ_BUILD_EXAMPLES : Build examples(note that not all examples in examples folder are built)
  • TINYUSDZ_WITH_OPENSUBDIV : Use OpenSubviv to tessellate subdivision surface.
    • OpenSubdiv code is included in TinyUSDZ repo. If you want to use external OpenSubdiv repo, specity the path to OpenSubdiv using 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.

clang-cl on Windows

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

Tools and Examples

  • tusdcat Parse USDZ/USDA/USDC and print it as Ascii(similar to usdcat in pxrUSD).
  • usda_parser Parse USDA and print it as Ascii.
  • usdc_parser Parse USDC and print it as Ascii.
  • Simple SDL viewer
    • Separated CMake build provided: See Readme
  • api_tutorial Tutorial of TinyUSDZ Core API to construct a USD scene data.
  • tydra_api Tutorial of TinyUSDZ Tydra API to access/query/convert a USD scene data.

See examples directory for more examples, but may not actively maintained except for the above examples.

USDZ Data format

See prim_format.md and preview_surface.md

Example

Minimum example to load USDA/USDC/USDZ file.

// 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;
}

With Core TinyUSDZ API

Please see api_tutorial

With Tydra API

Please see tydra_api

TODO

Higher priority

  • Built-in usdObj(wavefront .obj mesh) support.
    • via tinyobjloader.
  • Support Crate(binary) version 0.8.0(USD v20.11 default)
  • usdSkel utilities
    • Joint hierachy reconstruction and compute skinning matrix(usdSkel)
    • Blend shapes
      • Basic Blendshapes support
      • In-between blend shapes
  • Read USD data with bounded memory size. This feature is especially useful for mobile platform(e.g. in terms of security, memory consumption, etc)
  • USDC writer
  • Support Nested USDZ
  • UDIM texture support
  • MaterialX support
    • Parse XML file using tinyxml2

Middle priority

  • Composition arcs
  • Code refactoring, code optimization

Lower priority

  • iOS example?
  • Support AR related schema(Game-like feature added by Reality Composer?)
  • Audio play support
    • Play audio using SoLoud or miniaudio(or Oboe for Android)
    • wav(dr_wav)
    • mp3(dr_mp3)
    • m4a(ALAC?)
  • Viewer with Vulkan API.
  • Replace OpenSubdiv with our own subdiv library.
  • Write parser based on the schema definition.
  • Support big endian architecture.

Python binding and prebuit packages

Python binding and prebuilt packages(uploadded on PyPI) are provided.

See python/README.md and doc/python_binding.md for details.

CI build

CI build script is a build script trying to build TinyUSDZ in self-contained manner as much as possible(including custom Python build)

Linux/macOS

T.B.W.

Windows

Build custom Python,

> ci-build-python-lib.bat

then build TinyUSDZ by linking with this local Python build.

> ci-build-vs2022.bat

Cross compile with clang-cl + MSVC SDK on linux and run it on WINE(No Windows required at all solution!)

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.

License

TinyUSDZ is licensed under MIT license and Apache 2.0 license. (Doing relicensing from MIT to Apache 2.0. Will be fully relicensed to Apache 2.0 at some point)

Third party licenses

More Repositories

1

tinygltf

Header only C++11 tiny glTF 2.0 library
C++
1,582
star
2

tinyexr

Tiny OpenEXR image loader/saver library
C++
620
star
3

tinyobjloader-c

Header only tiny wavefront .obj loader in pure C99
C
346
star
4

tinygltfloader

Header only C++ Tiny glTF loader.
C
247
star
5

tinydng

Header-only Tiny DNG/TIFF loader and writer in C++
C
126
star
6

MMDLoader

Simple MMD(PMD/VMD) loader in C++
C++
105
star
7

lucille

lucille global illumination renderer
C
89
star
8

tacotron-tts-cpp

Tacotron text to speech in C++(synthesize only)
C++
71
star
9

nanovg-nanort

NanoRT(SW ray tracer) backend for NanoVG
C
49
star
10

nanocanvas

NanoCanvas, portable JavaScript vector graphics engine.
C
43
star
11

tinymeshutils

Tiny Mesh utilities(e.g. compute half-edge data structure) in C++11
C++
35
star
12

docker-utils

Docker utilities
Shell
33
star
13

tinyvdbio

TinyVDBIO header-only C++ OpenVDB IO library
C++
32
star
14

eson

ESON, Exa-scale Storage Object Notation
Python
31
star
15

window-bootstrap

Cross-platform C++ Window/UI bootstrap
C
29
star
16

python-rdma-examples

Python RDMA sample scripts
Python
18
star
17

tinyshrot

TinySHRot, header-only C89 spherical harmonics rotation codes.
C
17
star
18

aobench

Automatically exported from code.google.com/p/aobench
HTML
16
star
19

aobench_cs

aobench in OpenGL compute shader!
C++
12
star
20

standalone-pocketfft

pocketfft in standalone C
C
12
star
21

tinyxpd

Dependency-free and header-only C++11 XGen XPD cache I/O library.
C++
11
star
22

USD-build-aarch64

USD build script for aarch64 target
C++
10
star
23

dynamic_bitset

Simple dynamic bitset template class
C++
10
star
24

oi-build

OpenIndiana Unified Build System
C
9
star
25

minioptix

Mini OptiX sample
C
8
star
26

libphm

PHM: Simple Portable Half float(fp16) Map fileformat in C/C++
C
7
star
27

tinylinalg

Tiny linear algebra and matrix math library
7
star
28

xgen-spline-to-cyhair

XGen Interactive Grooming spline to CyHair exporter
C++
7
star
29

node.rdma

RDMA transport layer for node.js
C++
6
star
30

tinylosslessjpeg

Tiny LosslessJPEG decoder in C++11
6
star
31

flutter_native_vulkan_experiment

Experiment to call Vulkan function from Flutter(dart ffi)
Dart
6
star
32

espnet-tts-streamlit

ESPNet TTS with Streamlit GUI
Python
6
star
33

tinycolorio

Header-only C++11 color IO library
Jupyter Notebook
6
star
34

OpenVDB-Android

Android port of OpenVDB
C++
5
star
35

staticstruct

Simple statically typed struct serialization/deserialization library in C++11
C++
5
star
36

raw-images

RAW photo images
5
star
37

espnet-tts

ESPNet TTS standalone execution
Python
4
star
38

mudalang

MUDA(MUltiple Data Accelerator) language
Haskell
4
star
39

solaris-infiniband-tools

Tcl
4
star
40

minijit

Minimal clang/LLVM JIT experiment
CMake
4
star
41

usda-to-usdc-experiment

USDA to USDC conversion experiment in C++
C++
4
star
42

cycles

cycles experimental
C++
3
star
43

tinyarchive

Tiny binary archive library.
C++
3
star
44

parallella-playground

Parallella Epiphany playground
C
3
star
45

aobench_oculus

aobench for Oculus Rift
C++
3
star
46

libtorch_mobile_build

libtorch mobile build script
CMake
2
star
47

libjsonnet-cpp

Embed jsonnet to your C++11 application
C++
2
star
48

francine

Render backend
2
star
49

MUDA

MUDA is a MUltiple Data Accleleration language
Haskell
2
star
50

cmake-rpath-experiment

CMake + RPATH experiment
CMake
2
star
51

alembic-converters

Alembic file formart converters in C++11
C++
2
star
52

jsmuda

optimized code generator written in node.js
JavaScript
2
star
53

llvm-project-mingw-build

llvm-project MinGW build script using llvm-mingw
Shell
2
star
54

LLL

Lucille Light transport Language
Haskell
2
star
55

cyhair-combiner

Simple CyHair combiner tool
C++
2
star
56

jch-vis

Visualize Jump Consistent Hash
1
star
57

visemenet-docker

Run VisnemeNet inference in nvidia-docker container
Dockerfile
1
star
58

klee-avx

avx support branch for klee
1
star
59

OSOgraph

Simple script visualizing OSO instructions using graphviz
Python
1
star
60

orelatex

δΏΊεΎ— latex η’°ε’ƒγƒ†γƒ³γƒ—γƒ¬γƒΌγƒˆ
1
star
61

oremake

oremake
JavaScript
1
star
62

aobench-fortran

Fortran 90 port of aobench
Fortran
1
star
63

aobench-osv

OSv port of aobench
C++
1
star
64

nanostl

NanoSTL, small subset of C++ STL
1
star
65

llvm-win-build

llvm-win-build
1
star
66

aobench-ios

aobench-ios
C
1
star
67

orevfx

ore vfx tool build
1
star
68

clapack-cmake-android-arm64

clapack cmake build for Android ARM64(NDK r20 or later)
C
1
star
69

orebuildenv

俺得ビルド環咃
Shell
1
star
70

naiad-tools

Naiad emp processing tools
C
1
star
71

lesh

continuos building tool
JavaScript
1
star