Huggingface.js documentation
@huggingface/usd-web-viewer
@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' |
maxTextureSize | 1024 | الطول الطويل للأنسجة المفكوكة، بالبكسل |
signal | إشارة AbortSignal؛ يتم رفض التحميل بخطأ UsdLoadError برمز aborted | |
onProgress | تُستدعى مع المرحلة ونسبة fraction إجمالية من 0 إلى 1 | |
files | تحميل الملفات المفقودة أو المُلتقطة بدلاً من الشبكة (انظر أدناه) | |
wasmUrl, workerUrl | بجانب الحزمة | الموقع الذي تُقدَّم منه وحدة WASM الثنائية وسكربت العامل |
maxConcurrentFetches | 16 | الطلبات الجارية في وقت واحد |
maxLayerBytes, maxLayers | 768 ميغابايت، 1024 | حدود تنزيل الطبقات |
maxTextureBytes | 512 ميغابايت | حد تنزيل النسيج |
maxTriangles, maxInstances | 20M, 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.