@huggingface/usd-web-viewer

OpenUSD를 브라우저에서: openusd(순수 Rust) 기반의 WebAssembly에서 USD 구성을 처리하고, 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가 포함된 UsdLoadError입니다(aborted, fetch, compose, worker, webgl). 충실히 표시할 수 없었던 항목은 모두 info.warnings에 나열됩니다. 모든 옵션, 오류 및 경고는 타입이 지정되어 있습니다.

신뢰할 수 없는 파일 로드

• 요청은 <model-viewer>와 동일하게 전송됩니다: 쿠키는 페이지 자체의 origin(credentials: 'same-origin')으로만 전송되며, 커스텀 헤더와 referrer는 포함되지 않습니다.
• 레이어와 텍스처는 http(s)를 통해서만 가져옵니다.
• Web Worker에서 WebAssembly로 컴파일된 Rust로 파싱이 실행됩니다.
• 각 로드에는 한도가 있습니다: maxLayerBytes(768 MiB), maxLayers(1024), maxTextureBytes(512 MiB), maxTriangles(20M), maxInstances(100,000); 이미지는 한 변 최대 16384 px, 면적 최대 8192 x 8192 px; 프리미티브는 최대 256단계까지 중첩 가능; .usdz 항목은 각각 최대 512 MiB, 전체 최대 1 GiB이며 압축되지 않은 상태로 저장됩니다.
• 잘못된 형식의 파일은 UsdLoadError와 함께 로드 실패합니다.

로컬 파일

<input type="file" webkitdirectory>를 사용하여 선택하거나 페이지에 드롭한 파일을 표시하려면, 패키지 내 경로로 키를 지정하여 files로 전달하고 루트 레이어의 키를 로드하세요. 파일 내 상대 경로는 서로를 기준으로 해석되며, 이를 위해 별도로 가져오기(fetch)가 수행되지 않습니다.

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에 있습니다.