USD from glTF

用于将 glTF 模型转换为 [USD] (https://graphics.pixar.com/usd/docs/index.html) 格式资源的库、命令行工具和导入插件，以便在 AR Quick Look 中显示。

请注意，这并非 Google 官方支持的产品。

这是一个 C++ 原生库，可作为现有脚本解决方案的替代方案。其主要优势在于提升了与 iOS 的兼容性和转换速度（详见兼容性和性能）。它将 USDZ 视为一种传输格式而非交换格式。有关传输和交换文件格式的更多信息，请参见此处。

简明步骤：安装后，使用以下命令进行转换：usd_from_gltf <source.gltf> <destination.usdz>

背景

glTF 是一种 3D 资产传输格式，通过移除对于高效显示资产非必需的数据，非常适合 Web 和移动设备。USD 是一种交换格式，可用于数字内容创建工具（如 Maya）中的文件编辑。

然而，iOS Quick Look 支持显示符合 USD 文件规范子集的 USDZ 文件。此工具将 glTF 文件转换为 USDZ，以便在 Quick Look 中显示，并尝试在 iOS Quick Look 运行时尽可能多地模拟 glTF 的功能。

模拟过程是有损的。例如，为了支持双面 glTF 材质，几何体需要加倍。这使得转换后的 glTF 能在 iOS 上正确显示，但将其导回数字内容创建（DCC）应用程序时，数据将与原始源文件不同。

此工具专门针对 glTF->USDZ->QuickLook 的文件转换使用场景。从 DCC 到 glTF 的转换会优化资产以适应运行时查看，如果将转换后的 USDZ 导回 DCC 工具，可能会丢失细分曲面等信息。

当进行 glTF->USD->DCC 转换时，Apple 的 USDPython 工具能更好地保留 glTF 文件中的数据，但代价是与现有 iOS Quick Look 版本的兼容性可能会降低。

安装步骤

• 下载并构建 USD。有关先决条件和构建步骤，请参阅相关的 README。将 USD 安装目录称为 {USD}。

• 安装 NASM。

  • (Linux) sudo apt-get install nasm
  • (OSX) brew install nasm（需要 Homebrew）
  • (Windows) 使用最新稳定版本的安装程序。

• 安装 PIL。

  • pip install Pillow

• 将 usd_from_gltf 源代码下载到 {UFG_SRC}。

• 安装到 {UFG_BUILD}（包含可选的测试数据）：

  python {UFG_SRC}/tools/ufginstall/ufginstall.py {UFG_BUILD} {USD} --testdata
  

• (Linux/OSX) 将 LD_LIBRARY_PATH 设置为 USD 和 usd_from_gltf 的 lib 目录。有关路径，请参见 ufginstall 脚本输出。

• (可选) 将可执行文件添加到 PATH。有关可执行文件路径，请参见 ufginstall 脚本输出。

• (可选) 构建测试数据。有关 ufgtest.py 命令，请参见 ufginstall 脚本输出。

• (可选) 设置 PXR_PLUGINPATH_NAME，以便在 Usdview 中使用 glTF 导入插件。有关路径，请参见 ufginstall 脚本输出。

使用命令行工具

命令行工具名为 usd_from_gltf，位于 {UFG_BUILD}/bin 目录中。运行方式如下（使用 --help 获取完整文档）：

usd_from_gltf <source.gltf> <destination.usdz>

批量转换和测试

该库包含 {UFG_SRC}/tools/ufgbatch/ufgbatch.py，用于方便批量转换。运行方式如下（使用 --help 获取完整文档）：

python {UFG_SRC}/tools/ufgbatch/ufgbatch.py my_tests.csv --exe "{UFG_BUILD}/bin/usd_from_gltf"

每个输入 CSV 包含一系列转换任务，格式如下：

name,path/to/input.gltf,dir/to/output/usd[, optional usd_from_gltf flags]

该库还包含 {UFG_SRC}/tools/ufgbatch/ufgtest.py，用于方便测试和预览部署。运行方式如下（使用 --help 获取完整文档）：

python {UFG_SRC}/tools/ufgbatch/ufgtest.py my_tests.csv --exe "{UFG_BUILD}/bin/usd_from_gltf"

对于开发和测试，ufgtest.py 有几个额外功能：

• 黄金文件差异对比。构建完成后，该工具会将构建的文件与已知良好的“黄金”目录中的文件进行比较。这有助于确定库的更改是否影响生成的数据。可以使用 --nodiff 禁用此功能。
• 预览网站部署。这会将更改后的 USDZ 文件（与黄金文件不同的文件）复制到一个目录，并生成 index.html，以便在浏览器中查看列表，与 iOS 上的 QuickLook 兼容。可以使用 --nodeploy 禁用此功能。

使用库

可通过 {UFG_BUILD}/lib/ufg 中的库将转换器与其他应用程序链接。调用 ufg::ConvertGltfToUsd 可将 glTF 文件转换为 USD。

使用导入插件

该插件并非转换所必需，但有助于在 UsdView 中预览 glTF 文件。

使用时，需将 PXR_PLUGINPATH_NAME 环境变量设置为包含 plugInfo.json 的目录。有关路径信息，请参见 ufginstall 脚本的输出。

兼容性

尽管 USD 是一种通用格式，但本库着重于与 AR Quick Look 的兼容性。不过，AR Quick Look 渲染器仅支持 glTF 2.0 规范 的一个子集，因此存在一些限制。在合理情况下，会模拟缺失的功能，以尽可能在 iOS 上忠实地再现 glTF 文件。模拟过程可能会有损耗，且输出不适合用作交换格式。

主要功能

• 读取文本（glTF）和二进制（GLB）输入文件。
• 生成 USDA 和/或 USDZ 输出文件。
• 读取嵌入式二进制数据和 Draco 压缩网格。
• 刚性和蒙皮动画。
• 无纹理、有纹理、无光照和 PBR 光照材质。
• glTF 扩展：KHR_materials_unlit、KHR_materials_pbrSpecularGlossiness、KHR_texture_transform（部分支持，见下文说明）、KHR_draco_mesh_compression
• 预期可转换所有格式良好的 glTF 文件，尽管某些功能可能缺失或需要模拟。已知可处理所有 Khronos glTF 示例 和 参考 模型。

为 AR Quick Look 模拟的功能

AR Quick Look 当前不支持 glTF 的多项渲染功能，但在合理情况下会对这些功能进行模拟。模拟的功能如下：

• 纹理通道引用。USD 支持此功能，但目前 AR Quick Look 要求粗糙度、金属度和 occlusion 通道使用不同的纹理。转换器会将通道分割为单独的纹理，并在必要时重新压缩。
• 纹理颜色缩放和偏移。这些通过将缩放和偏移烘焙到纹理中来模拟。如果一个纹理被多次引用且设置不同，这可能会增加输出大小。
• 纹理 UV 变换。这些通过将变换烘焙到顶点 UV 中来模拟。请注意，由于它们被烘焙到模型的单个 UV 集中，因此不同的纹理无法在同一网格上使用不同的变换。
• 高光工作流。目前 AR Quick Look 不支持此功能。转换器会生成金属度+粗糙度纹理作为近似。
• 任意资源大小。AR Quick Look 对解压缩大小有一定限制（根据经验，约为 200MB），超过此限制的模型将无法加载。转换器通过全局调整纹理大小以适应配置的限制来解决此问题。
• 非光照材质。转换器使用纯自发光材质来模拟非光照材质。这在大多数情况下有效，但由于 AR Quick Look 渲染器中的边缘光因素，可能存在一些差异。
• sRGB 自发光纹理。AR Quick Look 错误地将自发光纹理视为线性而非 sRGB，因此转换器通过转换为线性来解决此问题。
• 阿尔法剪切。对于阿尔法剪切材质，转换器通过将阿尔法值烘焙为 0 或 1 来解决此问题。如果纹理被具有不同剪切状态的材质引用，这会增加输出大小。此外，由于缺乏透明度排序，阿尔法剪切材质可能会出现排序错误。
• 双面几何体。转换器通过复制几何体来解决此问题。
• 法线贴图归一化。AR Quick Look 不对法线贴图的法线进行归一化，导致某些纹理的光照不正确。转换器会显式地重新归一化法线贴图纹理以解决此问题。
• 反转变换。AR Quick Look 会对反转的几何体进行错误的面剔除，因此转换器在必要时通过将反转的多边形绕序烘焙到网格中来解决此问题。
• 基于四元数的刚性动画。iOS 12 不支持此功能。转换器通过转换为欧拉角来解决此问题，但可能会遇到 万向节锁 问题。为了减少误差，转换器会以更高的频率烘焙欧拉关键帧，这可能会增加动画大小。
• 旋转的球面线性（slerp）插值。所有插值均为线性，因此矩阵或四元数关键帧之间的混合不正确，并可能导致缩放变化。转换器通过为刚性动画转换为欧拉角，以及为蒙皮动画以更高频率烘焙四元数关键帧来解决此问题。
• 每关节动画通道。蒙皮不使用独立的动画通道，因此转换器会将源通道扩展为（关节 * 关键帧）元素的网格。对于复杂骨骼，动画将比其 glTF 源显著增大。
• 多个骨骼。AR Quick Look 仅支持单个骨骼，因此转换器通过将多个骨骼合并为一个来模拟（这会在一定程度上增加动画大小）。
• 阶跃和三次动画插值模式。转换器通过将这些模式烘焙为线性来模拟（同样会增加动画大小）。
• 顶点量化/压缩。所有顶点组件都转换为全浮点精度，并且 Draco 压缩的网格会被解压缩。

AR Quick Look 不支持的功能

以下功能在 AR Quick Look 中不受支持，并且转换器也无法合理地支持这些功能。

• 顶点颜色。
• 变形目标和顶点动画。
• 纹理过滤模式。所有纹理均采用线性采样，并启用纹理映射（mipmapping）。
• 纹理的钳位（Clamp）和镜像（Mirror）环绕模式。所有纹理均使用重复（Repeat）模式。
• 相机。
• 阴影动画。阴影仅从第一帧生成。
• 透明阴影。当地面上存在透明几何体时，这一点尤为明显，由于阴影衰减，这些几何体看起来会非常暗。
• 多 UV 集。转换器通过禁用使用次级 UV 集的纹理来解决此问题，这对于最常见的使用场景（环境光遮蔽，AO）效果最佳。
• 多个动画。转换器仅导出单个动画。
• 多个场景。转换器仅导出单个场景。
• 透明度排序。重叠的透明表面看起来可能不正确。
• 顶点法线的蒙皮动画。蒙皮模型的光照效果会显得不正确，这在高反射表面上尤为明显（光照会呈现出“绘制上去”的外观）。转换器尝试通过将法线烘焙到动画的第一帧来缓解此问题，但效果仍然会不准确。

glTF 与 AR Quick Look 之间的渲染差异

AR Quick Look 的渲染器与 glTF 规范中描述的渲染模型并不完全一致，但已相当接近。不过，存在一些例外情况：

• 环境光遮蔽（AO）应用于输出颜色而非环境光，因此阴影区域看起来比在 glTF 中暗得多。在某些情况下，这可能导致模型完全显示为黑色，因此转换器通过禁用全黑的环境光遮蔽来解决此问题。
• 透明区域显得暗淡且褪色，这似乎是由于预乘 alpha 应用不当所致。
• 零高度处的阴影几何体存在 Z 轴冲突（Z-fighting）。

不支持问题的潜在解决方案

• USD 规范支持相机、顶点动画和顶点颜色，但 AR Quick Look 目前不支持。为了完整性和未来兼容性，应添加这些功能。
• 通过镜像纹理来模拟纹理镜像环绕模式。这种方法简单，但可能会将纹理大小增加高达 4 倍。
• 通过裁剪 UV 来模拟纹理钳位环绕模式。这涉及相对复杂的裁剪，但对模型大小不应有显著影响。
• 通过将顶点颜色烘焙到纹理中来模拟顶点颜色。一般来说，这很难实现，因为它可能涉及重新 UV 映射模型——这最好留给内容创作者处理。不过，对于某些特殊情况，可以简化此操作（例如，仅具有顶点颜色的无纹理模型可以使用简单的颜色图集）。
• 合并多个 UV 集。这很难实现，因为它需要重新 UV 映射模型——这最好留给内容创作者处理。

性能

usd_from_gltf 比当前替代方案大约快 10-15 倍。

转换时间的大部分用于图像处理和重新压缩，这对于模拟 AR Quick Look 中其他不支持的功能是必要的。

主要优化

• 采用原生 C++ 实现。
• 通过 ufgbatch.py 脚本支持多进程模型转换。
• 可在单次处理中生成 USDA 和 USDZ 文件。

基准测试

每个基准测试在 Xeon E5-1650 @ 3.50GHz（6 核，2 倍超线程，共 12 个硬件线程）上运行 3 次。

将 55 个 glTF 示例模型 转换为 USDZ：

• usd_from_gltf，1 进程：20.1、19.9、19.9（平均：20 秒）
• usd_from_gltf，12 进程：6.9、6.9、6.7（平均：6.8 秒）

将 28 个复杂的蒙皮和动画 glTF 模型转换为 USDZ：

• usd_from_gltf，1 进程：22.6、22.5、22.6（平均：22.6 秒）
• usd_from_gltf，12 进程：5.0、5.3、5.1（平均：5.2 秒）

故障排除

如果在构建或运行 usd_from_gltf 时遇到问题，请按照以下步骤操作。

• 确保安装 USD 后正确设置了环境变量。
• 将 Zlib 库添加到您的 PATH 中。