@huggingface/usd-web-viewer

在浏览器中使用 OpenUSD：基于 WebAssembly 的 USD 组合，构建于 openusd（纯 Rust）之上，并使用 three.js 进行渲染。支持读取 .usd、.usda、.usdc 和 .usdz；加载过程在 Web Worker 中运行。

npm install @huggingface/usd-web-viewer three

用法

现成的查看器（渲染器、光照、轨道控制）：

import { createViewer } from '@huggingface/usd-web-viewer';

const viewer = createViewer(document.getElementById('viewer')); // a container element
const { info } = await viewer.load(
  'https://huggingface.co/datasets/Robotiq-Official/simready-assets/resolve/main/Robotiq_2F_85/simready_usd/Robotiq_2F_85.usda',
);

或者放入你自己的 three.js 场景中：

import { loadUsd } from '@huggingface/usd-web-viewer';

const { root, complete, dispose } = await loadUsd(url);
scene.add(root); // a THREE.Group, Y-up, in meters
await complete; // textures stream in after the geometry

选项

loadUsd(url, options) 和 viewer.load(url, options) 接受以下参数：

createViewer(container, options) 接受 background（默认透明）、onContextLost 和 onContextRestored（在重新加载最后显示的模型时调用）。

失败是带有 code（aborted、fetch、compose、worker、webgl）的 UsdLoadError；任何无法忠实显示的内容都会列在 info.warnings 中。每个选项、错误和警告都有类型。

加载不受信任的文件

• 请求的发送方式与 <model-viewer> 相同：Cookie 仅发送到页面自身的源（credentials: 'same-origin'），不发送自定义请求头，也不包含 Referer。
• 图层和纹理仅通过 http(s) 获取。
• 解析在编译为 WebAssembly 的 Rust 中运行，位于 Web Worker 内。
• 每次加载均有上限：maxLayerBytes（768 MiB）、maxLayers（1024）、maxTextureBytes（512 MiB）、maxTriangles（2000 万）以及 maxInstances（100,000）；图像每边最大 16384 像素，面积最大 8192 x 8192 像素；图元嵌套深度最多 256 层；.usdz 条目单个最大 512 MiB，总计最大 1 GiB，且以未压缩形式存储。
• 格式错误的文件在加载时会抛出 UsdLoadError。

本地文件

要显示拖放到页面上或通过 <input type="file" webkitdirectory> 选取的文件，请将它们作为 files 传入，并以它们在包中的路径作为键，然后加载根层的键。文件中的相对路径会相互解析；不会为它们发起任何获取请求。

const files = new Map([...input.files].map((file) => [file.webkitRelativePath || file.name, file]));
await viewer.load('chair/simready_usd/sm_chair.usd', { files });

打包器

Worker 和 WASM 二进制文件通过 new URL(..., import.meta.url) 查找，Vite、webpack 和其他打包工具会解析并输出该路径。在使用 Vite 开发服务器时，请将此包从依赖预打包中排除：

// vite.config.js
export default { optimizeDeps: { exclude: ['@huggingface/usd-web-viewer'] } };

采用 MIT 许可证。编译到 WASM 二进制文件中的 Rust 软件包的许可证位于 THIRD_PARTY_LICENSES 中。