@huggingface/usd-web-viewer

Tarayıcıda OpenUSD: openusd (saf Rust) üzerine inşa edilmiş, three.js ile render edilen WebAssembly tabanlı USD kompozisyonu. .usd, .usda, .usdc ve .usdz dosyalarını okur; yükleme işlemleri bir Web Worker içinde çalışır.

npm install @huggingface/usd-web-viewer three

Kullanım

Hazır bir görüntüleyici (renderleyici, aydınlatma, yörünge kontrolleri):

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',
);

Kendi three.js sahnenize ekleyin:

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

Fizik ve eklem

info, simülasyon (UsdPhysics) ve UsdSemantics etiketleri için sahne yazarlarının, yazarlık yapıldığı gibi, ne bildirdiğini de raporlar: hiçbir şey tahmin edilmez. Kütleler kilogram, yoğunluklar kg/m³, atalet kg·m², eklem sınırları ve konumları derece veya metre cinsindendir; konumlar ve matrisler, root altındaki mesh'ler gibi sahne uzayındadır.

const { info, joints, setJointPositions, resetJointPositions, getJointPositions, getWorldMatrix } = await viewer.load(url);

info.physics.bodies; // rigid bodies: mass, center of mass, inertia, colliders, bodies fixed to them
info.physics.colliders; // shape, approximation (convexHull, sdf, ...), physics material
info.physics.materials; // density, friction, restitution
info.physics.joints; // revolute, prismatic, spherical, distance, fixed and generic joints with their limits and drives
info.physics.articulationRoots; // where articulations (bodies solved together, like a robot) start
info.physics.frames; // Xforms under a body, often points with no mesh, like a gripper's tip
info.labels; // e.g. { path: '/RootNode', taxonomy: 'wikidata_class', values: ['cabinet'] }
info.variantSelections; // e.g. { prim: '/Robotiq_2F_85', set: 'Physics', selection: 'Physx_parallel_grip' }
info.dependencies; // every layer and texture the stage read, with its size

joints; // the joints setJointPositions can move, e.g. to build sliders
setJointPositions({ '/Robotiq_2F_85/Robotiq_2F_85/Joints/finger_joint': 40 }); // revolute and prismatic joints, any number at once; what hangs from them and mimic joints follow
getJointPositions(); // where every revolute and prismatic joint is now
getWorldMatrix('/SO101/gripper/gripper_frame_link'); // where a body, frame or mesh under a body is now and which way it faces, as a THREE.Matrix4 in the scene; null if it is none of those
resetJointPositions(); // back to the authored pose

Pozeleme yalnızca kinematiktir (çarpışma veya yerçekimi yoktur) ve bir kaydırıcı sürükleme veya kayıtlama sırasında her kare için yeterince ucuzdur.

Seçenekler

loadUsd(url, options) ve viewer.load(url, options) şu parametreleri alır:

createViewer(container, options), background (varsayılan: şeffaf), onContextLost ve onContextRestored (son gösterilen modelin yeniden yüklenmesiyle çağrılır) parametrelerini alır.

Hatalar, code (aborted, fetch, compose, worker, webgl) içeren UsdLoadError türündedir; sadık bir şekilde gösterilemeyen her şey info.warnings içinde listelenir. Her seçenek, hata ve uyarı tiplidir.

Güvenilmeyen dosyaları yükleme

• İstekler <model-viewer>’ınkileri gibi gönderilir: çerezler yalnızca sayfanın kendi kökenine (credentials: 'same-origin'), özel başlıklar yok, yönlendiren (referrer) yok.
• Katmanlar ve dokular yalnızca http(s) üzerinden alınır.
• Ayrıştırma, Web Worker içinde, WebAssembly'e derlenmiş Rust ile çalışır.
• Her yükleme sınırlıdır: maxLayerBytes (768 MiB), maxLayers (1024), maxTextureBytes (512 MiB), maxTriangles (20M) ve maxInstances (100.000); kenar başına en fazla 16384 px ve alan olarak 8192 x 8192 px boyutlarında görüntüler; en fazla 256 seviye derinliğe kadar iç içe geçmiş primler; .usdz girdileri her biri en fazla 512 MiB ve toplamda 1 GiB, sıkıştırılmamış olarak saklanır.
• Bozuk dosyalar, yükleme işlemi sırasında UsdLoadError hatasıyla başarısız olur.

Yerel dosyalar

Sayfaya bırakılan veya <input type="file" webkitdirectory> ile seçilen dosyaları göstermek için, bunları paket içindeki yollarına göre anahtarlanmış olarak files parametresine iletin ve kök katmanının anahtarını yükleyin. Dosyalardaki göreli yollar birbirine göre çözümlenir; bunlar için hiçbir şey getirilmez.

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

Bundlers

Worker ve WASM ikilisi, Vite, webpack ve diğer paketleyicilerin çözüp yayınladığı new URL(..., import.meta.url) ile bulunur. Vite geliştirme sunucusuyla, paketi bağımlılık ön paketlemeden hariç tutun:

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

MIT lisanslıdır. WASM ikili dosyasına derlenen Rust crate'lerinin lisansları THIRD_PARTY_LICENSES dosyasında yer alır.