Huggingface.js documentation

@huggingface/usd-web-viewer

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

@huggingface/usd-web-viewer

OpenUSD في المتصفح: تركيب USD في WebAssembly، مبني على 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

الفيزياء والمفاصل

info يُبلّغ أيضًا عن ما كتبه مؤلفو المرحلة لمحاكاة (UsdPhysics) ووسوم UsdSemantics الخاصة بها، كما كُتبت: لا يوجد أي تقدير. الكتل بالكيلوغرام، والكثافات بالكيلوغرام/م³، والعزم بالكيلوغرام·م²، وحدود المفاصل ومواقعها بالدرجات أو الأمتار؛ المواقع والمصفوفات في مساحة المرحلة، مثل الشبكات تحت root.

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

تتميز حركة الجسم بأنها حركية بحتة (بدون تصادمات أو جاذبية) وهي رخيصة التكلفة بما يكفي لكل إطار من إطارات سحب شريط التمرير أو التسجيل.

خيارات

loadUsd(url, options) و viewer.load(url, options) تقبلان:

خيارافتراضي
textures'preview''none'، 'preview' (اللون الأساسي، خرائط بيانات صغيرة، بدون خرائط طبيعية) أو 'full'
maxTextureSize1024الطول الطويل للأنسجة المفكوكة، بالبكسل
signalإشارة AbortSignal؛ يتم رفض التحميل بخطأ UsdLoadError برمز aborted
onProgressتُستدعى مع المرحلة ونسبة fraction إجمالية من 0 إلى 1
filesتحميل الملفات المفقودة أو المُلتقطة بدلاً من الشبكة (انظر أدناه)
wasmUrl, workerUrlبجانب الحزمةالموقع الذي تُقدَّم منه وحدة WASM الثنائية وسكربت العامل
maxConcurrentFetches16الطلبات الجارية في وقت واحد
maxLayerBytes, maxLayers768 ميغابايت، 1024حدود تنزيل الطبقات
maxTextureBytes512 ميغابايتحد تنزيل النسيج
maxTriangles, maxInstances20M, 100,000ما يُرسم على الأكثر

createViewer(container, options) يتلقى background (الافتراضي شفاف)، وonContextLost وonContextRestored (تُستدعى مع إعادة تحميل آخر نموذج معروض).

تكون الأخطاء من نوع UsdLoadError مع code (aborted، fetch، compose، worker، webgl)؛ وتُدرج في info.warnings أي عناصر تعذّر عرضها بدقة. جميع الخيارات والأخطاء والتحذيرات مُعرّفة الأنواع.

تحميل ملفات غير موثوقة

  • تُرسل الطلبات على غرار طلبات <model-viewer>: ملفات تعريف الارتباط إلى نطاق الصفحة نفسها فقط (credentials: 'same-origin')، دون ترويسات مخصصة، ودون مُرسل.
  • تتم استعادة الطبقات والملمس عبر بروتوكول http(s) فقط.
  • تتم عملية التحليل في Rust المُجمَّعة إلى WebAssembly، داخل Web Worker.
  • يخضع كل تحميل لحدود قصوى: maxLayerBytes (768 ميغابايت)، maxLayers (1024)، maxTextureBytes (512 ميغابايت)، maxTriangles (20 مليونًا) وmaxInstances (100,000)؛ الصور حتى 16384 بكسل في كل جانب و8192 x 8192 بكسل في المساحة؛ العناصر الأولية المتداخلة حتى 256 مستوى عمقًا؛ إدخالات .usdz حتى 512 ميغابايت لكل منها و1 غيغابايت إجمالًا، مخزنة دون ضغط.
  • تفشل الملفات غير الصيغة في التحميل مع 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. تراخيص حزم Rust المُجمَّعة في ملف WASM موجودة في THIRD_PARTY_LICENSES.

Update on GitHub