Logo
Project Icon

tinyusdz

轻量级跨平台USD文件处理库

TinyUSDZUSDZUSDCUSDAC++14Github开源项目

TinyUSDZ是一个C++14实现的USDZ/USDC/USDA文件处理库。它具有轻量级、安全和跨平台特性,仅依赖C++ STL。支持Linux、Windows、macOS、iOS、Android和WebAssembly平台。该库重视安全性,提供内存预算功能防范恶意文件。目前支持基本USD元素,正在开发高级功能。

访问官网访问官网GithubGithub文档文档论文论文
介绍相关项目

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

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

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

（来自 https://github.com/syoyo/Vulkan-glTF-USDZ-PBR） （来自ASF MaterialXViewer分支 https://github.com/lighttransport/materialx）

高优先级

中期待办事项

构建状态

LinuxWindowsmacOSiOSAndroid
开发版Linux 构建Windows CI 构建
Windows ARM CI 构建		macOS 构建iOS 构建Android arm64v8a 构建

支持的平台

LinuxWindowsmacOSiOSAndroidWASM(WASI)WASM(Emscripten)
开发版✅ 64位
✅ 32位
✅ aarch64		✅ 64位
✅ 32位
✅ 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，主要是访问材质/着色器属性）。

  • USDZ/USDC（Crate）解析器
    • 支持USDC Crate版本v0.8.0（截至2022年11月最常用的版本）或更高版本。
  • USDZ/USDC（Crate）写入器（开发中）
  • USDA解析器（从零开始手写。无需Bison/Flex依赖！）
  • USDA写入器
  • 支持基本图元（Xform、Mesh、BasisCurves等）、基本灯光和着色器（UsdPreviewSurface、UsdUVTexture、UsdPrimvarReader）
  • 实验性支持部分组合功能 https://github.com/syoyo/tinyusdz/issues/25
    • subLayers
    • references
    • payload
    • inherits
    • variants
    • specializes

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

  • 用于语言绑定的基本C API（c-tinyusd）
  • 编写简单的SDL查看器示例（预计2024年夏季）
  • 编写iOS和Android示例（预计2024年冬季）
  • 编写Vision OS示例？
  • Vulkan或OptiX/HIP RT光线追踪查看器示例
  • USD <-> glTF转换器示例
  • 使用Three.js的Web演示？

讨论

我们已经开放了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的项目

其他相关项目

支持的平台

  • Linux 64位或更高版本
    • ARM AARCH64
    • x86-64
    • RISC-V（应该可以工作）
    • SPARC, POWER（大端机器）。可能可以工作（理论上）
  • Android arm64v8a
  • iOS
  • macOS（Arm, x86-64）
  • Windows 10 64位或更高版本
    • Windows ARM
    • clang-cl + MSVC SDK交叉编译
  • WebAssembly
  • WASI（通过WASI工具链）

要求

也支持使用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 目录，但除上述示例外，其他示例可能不会积极维护。

作为外部项目的示例

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
相关项目
项目侧边栏1项目侧边栏2
推荐项目
Project Cover

豆包MarsCode

豆包 MarsCode 是一款革命性的编程助手，通过AI技术提供代码补全、单测生成、代码解释和智能问答等功能，支持100+编程语言，与主流编辑器无缝集成，显著提升开发效率和代码质量。

Project Cover

AI写歌

Suno AI是一个革命性的AI音乐创作平台，能在短短30秒内帮助用户创作出一首完整的歌曲。无论是寻找创作灵感还是需要快速制作音乐，Suno AI都是音乐爱好者和专业人士的理想选择。

Project Cover

有言AI

有言平台提供一站式AIGC视频创作解决方案，通过智能技术简化视频制作流程。无论是企业宣传还是个人分享，有言都能帮助用户快速、轻松地制作出专业级别的视频内容。

Project Cover

Kimi

Kimi AI助手提供多语言对话支持，能够阅读和理解用户上传的文件内容，解析网页信息，并结合搜索结果为用户提供详尽的答案。无论是日常咨询还是专业问题，Kimi都能以友好、专业的方式提供帮助。

Project Cover

阿里绘蛙

绘蛙是阿里巴巴集团推出的革命性AI电商营销平台。利用尖端人工智能技术，为商家提供一键生成商品图和营销文案的服务，显著提升内容创作效率和营销效果。适用于淘宝、天猫等电商平台，让商品第一时间被种草。

Project Cover

吐司

探索Tensor.Art平台的独特AI模型，免费访问各种图像生成与AI训练工具，从Stable Diffusion等基础模型开始，轻松实现创新图像生成。体验前沿的AI技术，推动个人和企业的创新发展。

Project Cover

SubCat字幕猫

SubCat字幕猫APP是一款创新的视频播放器，它将改变您观看视频的方式！SubCat结合了先进的人工智能技术，为您提供即时视频字幕翻译，无论是本地视频还是网络流媒体，让您轻松享受各种语言的内容。

Project Cover

美间AI

美间AI创意设计平台，利用前沿AI技术，为设计师和营销人员提供一站式设计解决方案。从智能海报到3D效果图，再到文案生成，美间让创意设计更简单、更高效。

Project Cover

AIWritePaper论文写作

AIWritePaper论文写作是一站式AI论文写作辅助工具，简化了选题、文献检索至论文撰写的整个过程。通过简单设定，平台可快速生成高质量论文大纲和全文，配合图表、参考文献等一应俱全，同时提供开题报告和答辩PPT等增值服务，保障数据安全，有效提升写作效率和论文质量。

使用协议隐私政策广告服务
投诉举报邮箱: service@vectorlightyear.com
@2024 懂AI·鲁ICP备2024100362号-6·鲁公网安备37021002001498号