Huggingface.js documentation
@huggingface/usd-web-viewer
@huggingface/usd-web-viewer
OpenUSD trong trình duyệt: tổ hợp USD trong WebAssembly, được xây dựng trên openusd (Rust thuần), hiển thị bằng three.js. Đọc .usd, .usda, .usdc và .usdz; quá trình tải được chạy trong Web Worker.
npm install @huggingface/usd-web-viewer three
Cách sử dụng
Một trình xem (trình hiển thị, ánh sáng, điều khiển quỹ đạo) có sẵn:
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',
);Hoặc vào cảnh three.js của riêng bạn:
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 geometryTùy chọn
loadUsd(url, options) và viewer.load(url, options) nhận:
| Tùy chọn | Mặc định | |
|---|---|---|
textures | 'preview' | 'none', 'preview' (màu cơ bản, bản đồ dữ liệu nhỏ, không có bản đồ pháp tuyến) hoặc 'full' |
maxTextureSize | 1024 | Độ dài cạnh dài của các texture đã giải mã, tính bằng pixel |
signal | Một AbortSignal; việc tải sẽ bị từ chối với UsdLoadError có mã aborted | |
onProgress | Được gọi với stage và một fraction tổng thể từ 0 đến 1 | |
files | Tải các tệp đã bị rơi hoặc đã chọn thay vì từ mạng (xem bên dưới) | |
wasmUrl, workerUrl | bên cạnh gói | Nơi binary WASM và script worker được phục vụ |
maxConcurrentFetches | 16 | Số yêu cầu đang xử lý đồng thời |
maxLayerBytes, maxLayers | 768 MiB, 1024 | Giới hạn tải xuống lớp |
maxTextureBytes | 512 MiB | Giới hạn tải xuống texture |
maxTriangles, maxInstances | 20M, 100,000 | Số lượng tối đa được vẽ |
createViewer(container, options) nhận background (mặc định là trong suốt), onContextLost và onContextRestored (được gọi kèm theo việc tải lại mô hình cuối cùng đã hiển thị).
Các lỗi là UsdLoadError có code (aborted, fetch, compose, worker, webgl); mọi thứ không thể hiển thị trung thực sẽ được liệt kê trong info.warnings. Mọi tùy chọn, lỗi và cảnh báo đều được định kiểu.
Tải tệp không đáng tin
- Các yêu cầu được gửi giống như của
<model-viewer>: cookie chỉ đến origin của chính trang (credentials: 'same-origin'), không có header tùy chỉnh, không có referrer. - Các lớp và kết cấu chỉ được lấy qua http(s).
- Việc phân tích cú pháp được thực hiện bằng Rust được biên dịch thành WebAssembly, trong một Web Worker.
- Mỗi lần nạp có giới hạn:
maxLayerBytes(768 MiB),maxLayers(1024),maxTextureBytes(512 MiB),maxTriangles(20M) vàmaxInstances(100.000); hình ảnh tối đa 16384 px mỗi cạnh và 8192 x 8192 px về diện tích; các prim lồng nhau sâu tối đa 256 cấp; các mục.usdztối đa 512 MiB mỗi mục và 1 GiB tổng cộng, lưu trữ không nén. - Các tệp không hợp lệ sẽ gây lỗi khi tải với
UsdLoadError.
Tệp cục bộ
Để hiển thị các tệp được thả vào trang hoặc được chọn bằng <input type="file" webkitdirectory>, hãy truyền chúng dưới dạng files, được đánh dấu khóa theo đường dẫn của chúng trong gói, và nạp khóa của lớp gốc. Các đường dẫn tương đối trong các tệp sẽ được phân giải dựa trên nhau; không có gì được lấy cho chúng.
const files = new Map([...input.files].map((file) => [file.webkitRelativePath || file.name, file]));
await viewer.load('chair/simready_usd/sm_chair.usd', { files });Công cụ đóng gói
Worker và binary WASM được tìm thấy bằng new URL(..., import.meta.url), mà Vite, webpack và các bundler khác sẽ phân giải và xuất ra. Với dev server của Vite, hãy loại trừ gói này khỏi quá trình pre-bundling dependency:
// vite.config.js
export default { optimizeDeps: { exclude: ['@huggingface/usd-web-viewer'] } };Giấy phép MIT. Giấy phép của các crate Rust được biên dịch vào binary WASM nằm trong THIRD_PARTY_LICENSES.