C++14实现的小型USDZ/USDA/USDC库

TinyUSDZ是一个安全、可移植且无依赖（仅依赖C++ STL，包含其他第三方库。是的，你不需要pxrUSD/OpenUSD库！）的USDZ/USDC/USDA库，使用C++14编写。

Wasm演示！（需要下载10MB文件）

<img src="https://github.com/syoyo/tinyusdz/assets/18676/2419ddf6-4410-4bcc-b9c1-466bf29d3b20" width="400px"> （来自 https://github.com/syoyo/Vulkan-glTF-USDZ-PBR） <img src="https://github.com/lighttransport/tinyusdz/assets/18676/5291f44f-b20a-4d4a-9b4a-16ffefccddc7" width="400px"> （来自ASF MaterialXViewer分支 https://github.com/lighttransport/materialx）

高优先级

准备v0.8版本发布
- 核心部分应该已准备好发布
- 编写演示和示例查看器（进行中）
  - examples/openglviewer OpenGL查看器
  - examples/sdlviewer 软件光线追踪查看器
- 关于Vulkan和Android Vulkan示例，请暂时参考 https://github.com/syoyo/Vulkan-glTF-USDZ-PBR
- 关于OpenGL + MaterialX示例，请参考ASF MaterialXViewer分支，通过TinyUSDZ加载USD模型 https://github.com/lighttransport/materialx

中期待办事项

构建状态

	Linux	Windows	macOS	iOS	Android
开发版		</br>

支持的平台

	Linux	Windows	macOS	iOS	Android	WASM(WASI)	WASM(Emscripten)
开发版	✅ 64位 </br> ✅ 32位 </br> ✅ aarch64	✅ 64位 </br> ✅ 32位 </br> ✅ ARM64/ARM32	✅	✅	✅	✅ [sandbox/wasi](https://github.com/lighttransport/tinyusdz/blob/dev/sandbox/wasi	✅ [sandbox/emscripten](https://github.com/lighttransport/tinyusdz/blob/dev/sandbox/emscripten

状态

TinyUSDZ 目前处于 v0.8.0 候选发布版本。核心加载功能（包括 USDA 和 USDC）现已可用，并且达到了生产级别（对于损坏的 USDA/USDC/USDZ 输入也不会发生段错误）。用于使用 OpenGL/Vulkan 类渲染器渲染 USD 模型的 Tydra 框架已经初步可用。https://github.com/syoyo/tinyusdz/issues/148 v0.8.0版本基本上只支持扁平化场景（即使用pxrUSD的usdcat --flatten生成的USDA/USDC或USDZ场景）。组合功能目前正在开发中（v0.8.0中的组合功能支持是实验性的。计划在下一个主要版本v0.9.0（预计2024年第三季度）中提供更好的组合功能支持）。

v0.8.0发布前的剩余任务包括编写示例、演示和实用函数（特别是Tydra，主要是访问材质/着色器属性）。

更多详情请参见 doc/status.md

讨论

我们已经开放了GitHub讨论页面！https://github.com/syoyo/tinyusdz/discussions

安全性和内存预算

TinyUSDZ将安全性和稳定性作为首要考虑。

USDZ（USDC）是一种二进制格式。为了避免在加载恶意USDZ（例如来自未知来源的USDZ文件）时出现越界访问、内存溢出和其他安全问题，TinyUSDZ具有内存预算功能以避免内存溢出问题。

要限制加载USDZ文件时的内存使用，请在USDLoadOptions中设置max_memory_limit_in_mb值。

TinyUSDZ源代码（以及一些外部第三方代码）也通过地址消毒器、CodeQL和模糊测试进行检查。

模糊测试

请参见tests/fuzzer。要构建模糊测试，您需要Meson和Ninja。

Web平台（WASM）和沙盒环境（WASI）

如果您需要处理来自未知来源的任意USD文件（例如来自互联网、NFT存储，可能包含恶意数据），建议在沙盒环境（RunC、FlatPak、WASI（WASM））中使用TinyUSDZ。目前推荐在WASI中运行。

TinyUSDZ不使用C++异常，可以在无线程的情况下构建。TinyUSDZ支持WASM和WASI构建。因此，TinyUSDZ应该能在各种Web平台（WebAssembly。无需SharedArrayBuffer、Atomics和WebAssembly SIMD（iOS Safari尚不支持））和沙盒环境（WASI。适用于需要从互联网、IPFS或区块链存储读取可能包含恶意数据的各种USD文件的用户）上运行良好。

有关使用WASI工具链构建TinyUSDZ的信息，请参见sandbox/wasi/。

Tydra

USD本身是一个通用的3D场景数据容器。

Tydra是渲染器/查看器和其他DCC的接口。 Tydra可能类似于pxrUSD Hydra的精简版本，但其API完全不同。有关背景信息，请参见src/tydra/README.md。

注意事项

TinyUSDZ不支持Reality Composer文件格式（.reality），因为它使用专有文件格式，我们无法理解（因此也不支持与Reality的相互转换）。

赞助和商业支持

TinyUSDZ专注于USDA/USDC/USDZ的加载/写入功能。示例查看器仅用于演示目的。

如果您需要商业支持、生态系统开发（例如基于TinyUSDZ的插件、DCC工具）或生产级USDZ模型查看器（例如将TinyUSDZ嵌入到您的AR应用程序中，能够显示（加密）USDZ模型的3D NFT Android移动查看器），请联系Light Transport Entertainment, Inc.：https://goo.gl/forms/1p6uGcOKWGpXPHkA2

我们也在寻找赞助商。如果您对赞助（或捐赠）TinyUSDZ项目感兴趣，也请联系Light Transport Entertainment, Inc.了解详情：https://goo.gl/forms/1p6uGcOKWGpXPHkA2

使用TinyUSDZ的项目

Vulkan-glTF-USDZ-PBR：使用Vulkan绘制USD模型的示例 https://github.com/syoyo/Vulkan-glTF-USDZ-PBR
usd2glb：USD转glTF 2.0 GLB转换器 https://github.com/fynv/usd2glb
webgpu-cpp-usdz：WebGPU C++/Wasm USDZ渲染器（注意：目前支持的功能还不多！）https://github.com/Twinklebear/webgpu-cpp-usdz
assimp开始集成TinyUSDZ：https://github.com/assimp/assimp/pull/5628
一个秘密项目 (/ω＼)
多个DCC工具和插件
您的项目可以在这里！（请发送PR）

其他相关项目

UsdzSharpie：C#实现的简单Usdz文件格式 ( https://github.com/UkooLabs/UsdzSharpie )
TinyGLTF：glTF 2.0加载器/保存器 ( https://github.com/syoyo/tinygltf )

支持的平台

要求

C++14编译器
- gcc 4.9或更高版本
- Visual Studio 2019或更高版本。推荐2022。
  - 您可以使用CMakePresets.json，但在VS2022中似乎有点麻烦 https://github.com/lighttransport/tinyusdz/pull/182#issuecomment-2236676598 。如果遇到问题，暂时使用vcsetup.bat来设置.sln。
  - 可以使用独立的MSVC编译器（Visual Studio 2019的Build Tools）编译
- clang 3.4或更高版本 https://clang.llvm.org/cxx_status.html
- 支持llvm-mingw（clang）
- 支持MinGW gcc，但不推荐（根据您的构建配置，可能会遇到编译失败：https://github.com/syoyo/tinyusdz/issues/33 ，如果使用默认的bfd链接器，链接时间会非常长）。如果您想在MinGW环境中编译TinyUSDZ，建议使用llvm-mingw（clang）。

也支持使用C++17进行编译。 C++20和C++23的编译可能也可以，但尚未经过充分测试，因为C++20/C++23编译器还不够成熟（截至2024/01）

构建

集成到您的应用程序

如果您使用CMake，只需使用add_subdirectory包含tinyusdz仓库，并将包含路径设置为<tinyusdz>/src 我们建议使用CMake 3.24或更高版本。（最低要求是3.16）


...

# 当tinyusdz作为库通过`add_subdirectory`构建时，TinyUSDZ示例、测试和工具的构建默认是禁用的
add_subdirectory(/path/to/tinyusdz tinyusdz)

target_include_directories(YOUR_APP PRIVATE "/path/to/tinyusdz/src")

# 提供了命名空间静态库目标`tinyusdz::tinyusdz_static`。
# 目前我们建议使用TinyUSDZ的静态构建。
# 对于旧版本的cmake，您也可以使用别名目标`tinyusdz_static`。
target_link_libraries(YOUR_APP PRIVATE tinyusdz::tinyusdz_static)

# 对于TinyUSDZ DLL（共享）库目标，您可以使用
# `tinyusdz`库目标

另一种方法是简单地将src文件夹复制到您的应用程序中，并将*.cc文件添加到您的应用程序的构建系统中。所有包含路径都是相对于src文件夹设置的，所以您只需要将包含目录添加到src文件夹。

有关详细信息，请参阅<tinyusdz>/CMakeLists.txt和examples/sdlviewer/CMakeLists.txt。

TinyUSDZ在构建之前和之后（安装阶段之前）不会生成任何头文件和源文件，所以您不需要关心源代码树的任何预处理和后处理。例如，USD Ascii解析器使用手写的C++代码，所以不涉及Bison/flex/PEG处理。

不建议将tinyusdz作为git子模块使用，因为该仓库包含许多构建TinyUSDZ示例所需的代码，但这些代码对您的应用程序并不需要。

编译器定义

请参阅CMake构建选项和CMakeLists.txt。在大多数情况下，相同的标识符是从cmake构建选项定义的：例如，如果您为cmake参数指定-DTINYUSDZ_PRODUCTION_BUILD=1，则会定义TINYUSDZ_PRODUCTION_BUILD。

CMake

提供了CMake构建。

Linux和macOS

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

请查看scripts/bootstrap-cmake-*.sh以了解一些构建配置。

Visual Studio

支持Visual Studio 2019和2022。为了方便在 Visual Studio 2019 和 Visual Studio 2022 上构建，提供了 CMakePresets.json，但它存在许多限制（并且似乎并行构建效果不佳，导致构建速度较慢）。

如果您需要更多灵活性，建议使用通过调用 vcsetup.bat 的普通 cmake .sln 生成方法。（在运行之前，根据需要编辑 vcsetup.bat 中的 VS 版本）

LLVM-MinGW 构建

提供了使用 llvm-mingw(clang) 的 MinGW 原生和交叉编译示例。详情请参见 scripts/bootstrap-cmake-mingw-win.sh 和 scripts/bootstrap-cmake-llvm-mingw-cross.sh。

使用 llvm-mingw 的一个好处是支持 Windows 应用程序的地址清理器。

要运行应用程序（.exe，您需要在工作目录或搜索路径中放置 libunwind.dll 和 libc++.dll）

对于 Windows 原生构建，我们假设系统中已安装 ninja.exe（您可以使用 Meson 包中的版本）

CMake 构建选项

TINYUSDZ_PRODUCTION_BUILD：生产构建。不输出调试日志。
TINYUSDZ_BUILD_TESTS：构建测试
TINYUSDZ_BUILD_EXAMPLES：构建示例（注意，并非 examples 文件夹中的所有示例都会被构建）
TINYUSDZ_WITH_OPENSUBDIV：使用 OpenSubdiv 对细分曲面进行镶嵌。
- OpenSubdiv 代码包含在 TinyUSDZ 仓库中。如果您想使用外部 OpenSubdiv 仓库，请使用 osd_DIR cmake 环境变量指定 OpenSubdiv 的路径。
TINYUSDZ_WITH_AUDIO：支持加载音频（mp3 和 wav）。
TINYUSDZ_WITH_EXR：通过 TinyEXR 支持加载 EXR 格式的 HDR 纹理。
TINYUSDZ_WITH_PXR_COMPAT_API：构建兼容 pxrUSD 的 API。

Windows 上的 clang-cl

假设已安装 ninja.exe 并将其路径添加到 %PATH% 中

在 bootstrap-clang-cl-win64.bat 中编辑 MSVC SDK 和 Windows SDK 的路径，然后

> bootstrap-clang-cl-win64.bat
> ninja.exe

工具和示例

tusdcat 解析 USDZ/USDA/USDC 并以 Ascii 格式打印（类似于 pxrUSD 中的 usdcat）。
- tusdcat 还执行 USD 组合（flatten）并包含 TinyUSDZ 组合 API 用例。
已弃用。请使用 tusdcat usda_parser 解析 USDA 并以 Ascii 格式打印。
已弃用。请使用 tusdcat usdc_parser 解析 USDC 并以 Ascii 格式打印。
简单 SDL 查看器
- 提供独立的 CMake 构建：参见 Readme
api_tutorial TinyUSDZ 核心 API 教程，用于构建 USD 场景数据。
tydra_api TinyUSDZ Tydra API 教程，用于访问/查询/转换 USD 场景数据。
asset_resolution 使用 AssetResolutionResolver API 从自定义 I/O（例如内存、网络、数据库等）加载 USD 的教程。
file_format 使用自定义 FileFormat 处理程序加载自定义文件格式中的 Prim 数据的教程。

更多示例请参见 examples 目录，但除上述示例外，其他示例可能不会积极维护。

作为外部项目的示例

通过扩展 Vulkan-glTF-PBR 实现 USDZ 模型的 Vulkan 渲染 https://github.com/syoyo/Vulkan-glTF-USDZ-PBR
- 使用 rendermesh-refactor 分支

USDZ 数据格式

参见 prim_format.md 和 preview_surface.md

示例

加载 USDA/USDC/USDZ 文件的最小示例。

// TinyUSDZ 不是一个仅头文件的库，所以不需要 TINYUSDZ_IMPLEMENTATIONS
#include "tinyusdz.hh"

// 如果您想打印 TinyUSDZ 类/结构/枚举，请包含 pprinter.hh 和 value-pprint.hh。
// `tinyusdz::to_string()` 和 TinyUSDZ 类/枚举的 `std::operator<<` 是分开提供的，以加快编译速度
#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; // USD 术语中的 Stage 基本上相当于通用 3D 图形术语中的 Scene。
  std::string warn;
  std::string err;

  // 自动检测 USDA/USDC/USDZ
  bool ret = tinyusdz::LoadUSDFromFile(filename, &stage, &warn, &err);

  if (warn.size()) {
    std::cout << "警告：" << warn << "\n";
  }

  if (!ret) {
    if (!err.empty()) {
      std::cerr << "错误：" << warn << "\n";
    }
    return EXIT_FAILURE;
  }

// 打印舞台(场景图) std::cout << tinyusdz::to_string(stage) << "\n";

// 你也可以像在pxrUSD中那样使用ExportToString() // std::cout << stage.ExportToString() << "\n";

// 使用stage.metas()获取场景元数据 for (const Prim &root_prim : stage.root_prims()) { std::cout << root_prim.absolute_path() << "\n"; // 你可以使用Prim::children()遍历Prim(场景图对象) // 详见examples/api_tutorial和examples/tydra_api。 }

return EXIT_SUCCESS; }


### 使用Core TinyUSDZ API

请参阅[api_tutorial](https://github.com/lighttransport/tinyusdz/blob/dev/examples/api_tutorial/

### 使用Tydra API

请参阅[tydra_api](https://github.com/lighttransport/tinyusdz/blob/dev/examples/tydra_api/


## 待办事项

### 高优先级

* [ ] 内置usdObj(wavefront .obj网格)支持。
  * 通过tinyobjloader。
* [x] 支持Crate(二进制)版本0.8.0(USD v20.11默认版本)
* [ ] usdSkel实用工具
  * [ ] 关节层次重建和计算蒙皮矩阵(usdSkel)
  * [ ] 混合形状
    * [x] 基本混合形状支持
    * [ ] 中间混合形状
* [ ] 以有限内存大小读取USD数据。这个功能对移动平台特别有用(例如在安全性、内存消耗等方面)
* [ ] USDC写入器
* [ ] 支持嵌套USDZ
* [ ] UDIM纹理支持
* [ ] MaterialX支持
  * [ ] 使用tinyxml2解析XML文件

### 中等优先级

* [ ] 组合弧
* [ ] 代码重构，代码优化

### 低优先级

* [ ] iOS示例？
* [ ] 支持AR相关的模式(由Reality Composer添加的游戏类功能？)
* [ ] 音频播放支持
  * [ ] 使用SoLoud或miniaudio(或Android的Oboe)播放音频
  * [ ] wav(dr_wav)
  * [ ] mp3(dr_mp3)
  * [ ] m4a(ALAC?)
* [ ] 使用Vulkan API的查看器。
* [ ] 用我们自己的细分库替换OpenSubdiv。
* [ ] 基于模式定义编写解析器。
* [ ] 支持大端架构。

## Python绑定和预构建包

提供Python绑定和预构建包(上传到PyPI)。

详情请参阅[python/README.md](python/README.md)和[doc/python_binding.md](https://github.com/lighttransport/tinyusdz/blob/dev/doc/python_binding.md)。

## CI构建

CI构建脚本是一个尝试尽可能以自包含方式构建TinyUSDZ的构建脚本(包括自定义Python构建)

### Linux/macOS

待补充。

### Windows

构建自定义Python，

ci-build-python-lib.bat


然后通过链接这个本地Python构建来构建TinyUSDZ。

ci-build-vs2022.bat


#### 在Linux上使用clang-cl + MSVC SDK进行交叉编译，并在WINE上运行(完全不需要Windows的解决方案！)

也支持clang-cl(MSVC cl.exe) + MSVC SDK交叉编译。

请查看[doc/wine_cl.md](https://github.com/lighttransport/tinyusdz/blob/dev/doc/wine_cl.md)

你可以在Linux CI机器上构建纯Windows版的TinyUSDZ。

## 许可证

TinyUSDZ主要在Apache 2.0许可下授权。
一些辅助代码在MIT许可下授权。

### 第三方许可证
* pxrUSD：Apache 2.0许可证。https://github.com/PixarAnimationStudios/USD
* OpenSubdiv：Apache 2.0许可证。https://github.com/PixarAnimationStudios/OpenSubdiv
* lz4：BSD-2许可证。http://www.lz4.org
* cnpy（未压缩ZIP解码/编码代码）：MIT许可证 https://github.com/rogersce/cnpy
* tinyexr：BSD许可证。
* tinyobjloader：MIT许可证。
* tinygltf：MIT许可证。
* tinycolorio：MIT许可证。https://github.com/syoyo/tinycolorio
* stb_image、stb_image_resize、stb_image_write、stb_truetype：公共领域。
* dr_libs：公共领域。https://github.com/mackron/dr_libs
* miniaudio：公共领域或MIT无归属许可证。https://github.com/dr-soft/miniaudio
* SDL2：zlib许可证。https://www.libsdl.org/index.php
* optional-lite：BSL 1.0许可证。https://github.com/martinmoene/optional-lite
* expected-lite：BSL 1.0许可证。https://github.com/martinmoene/expected-lite
* mapbox/earcut.hpp：ISC许可证。https://github.com/mapbox/earcut.hpp
* par_shapes.h 生成参数化表面和其他简单形状：MIT许可证 https://github.com/prideout/par
* MaterialX：Apache 2.0许可证。https://github.com/AcademySoftwareFoundation/MaterialX
* string_id：zlib许可证。https://github.com/foonathan/string_id
* cityhash：MIT许可证。https://github.com/google/cityhash
* fast_float：Apache 2.0/MIT双重许可证。https://github.com/fastfloat/fast_float
* jsteeman/atoi：Apache 2.0许可证。https://github.com/jsteemann/atoi
* formatxx：无许可证。https://github.com/seanmiddleditch/formatxx
* ubench.h：无许可证。https://github.com/sheredom/ubench.h
* thelink2012/any：BSL-1.0许可证。https://github.com/thelink2012/any
* simple_match：BSL-1.0许可证。https://github.com/jbandela/simple_match
* nanobind：BSD-3许可证。https://github.com/wjakob/nanobind
* pybind11：BSD-3许可证。https://github.com/pybind/pybind11
* pystring：BSD-3许可证。https://github.com/imageworks/pystring
* gulrak/filesytem：MIT许可证。https://github.com/gulrak/filesystem
* p-ranav/glob：MIT许可证。https://github.com/p-ranav/glob
* linalg.h：无许可证。https://github.com/sgorsten/linalg
* mapbox/eternal：ISC许可证。https://github.com/mapbox/eternal
* bvh：MIT许可证。https://github.com/madmann91/bvh
* dtoa_milo.h：MIT许可证。https://github.com/miloyip/dtoa-benchmark
* jeaiii/itoa：MIT许可证。https://github.com/jeaiii/itoa
* alac：Apache 2.0许可证。https://macosforge.github.io/alac/
* OpenFBX：MIT许可证。https://github.com/nem0/OpenFBX
* floaxie：Apache 2.0许可证。https://github.com/aclex/floaxie
* boost math sin_pi/cos_pi：BSL 1.0许可证。https://www.boost.org/
* Vulkan：MIT许可证。https://github.com/SaschaWillems/Vulkan
* Metal.cpp：Apache 2.0许可证。https://github.com/bkaradzic/metal-cpp https://developer.apple.com/metal/cpp/
* sRGB转换：MIT许可证。https://www.nayuki.io/page/srgb-transform-library
* virtualGizmo3D：BSD-2许可证。https://github.com/BrutPitt/virtualGizmo3D
* nanozlib：Apache 2.0许可证。https://github.com/lighttransport/nanozlib
* lz4.py：MIT许可证。https://github.com/SE2Dev/PyCoD/blob/master/_lz4.py
* pugixml：MIT许可证。https://github.com/zeux/pugixml
* nanoflann：2条款BSD许可证。https://github.com/jlblancoc/nanoflann
* tinymeshutils：MIT许可证。https://github.com/syoyo/tinymeshutils