تحميل نموذج 3D
@aspose/3d يوفر طريقتين للتحميل على الـ Scene الفئة: open() للتحميل عبر مسار الملف و openFromBuffer() للبيانات في الذاكرة. اكتشاف الصيغة يتم تلقائيًا من أرقام السحر الثنائية أو امتداد الملف، لذا نادرًا ما تحتاج إلى تحديد صيغة المصدر صراحةً.
التحميل من مسار ملف
مرّر سلسلة مسار الملف إلى scene.open(). المكتبة تكتشف الصيغة من امتداد الملف، وللصيغ الثنائية من البايتات السحرية:
import { Scene } from '@aspose/3d';
const scene = new Scene();
scene.open('model.fbx');
console.log(`Root children: ${scene.rootNode.childNodes.length}`);
console.log(`Animation clips: ${scene.animationClips.length}`);open() يستبدل أي محتوى مشهد موجود. إذا كنت بحاجة إلى تحميل ملفات متعددة، أنشئ منفصل Scene الحالات.
تحميل OBJ مع المواد
ملفات OBJ تُشير إلى المواد عبر ملف جانبي .mtl ملف. تحميل المواد هو مُفعَّل افتراضيًا (ObjLoadOptions.enableMaterials = true). مرّر ObjLoadOptions للتحكم في هذا وغيرها من خيارات وقت التحميل:
import { Scene } from '@aspose/3d';
import { ObjLoadOptions } from '@aspose/3d/formats/obj';
const scene = new Scene();
const options = new ObjLoadOptions();
options.enableMaterials = true; // load the .mtl sidecar
options.flipCoordinateSystem = false; // keep original Y-up orientation
options.normalizeNormal = true; // fix degenerate normals
options.scale = 1.0; // unit scale multiplier
scene.open('character.obj', options);
// Inspect materials on the first node
const first = scene.rootNode.childNodes[0];
if (first) {
console.log(`Materials on ${first.name}: ${first.materials.length}`);
}التحميل من الذاكرة المؤقتة
استخدم openFromBuffer() عندما تكون بيانات الملف موجودة بالفعل في الذاكرة، على سبيل المثال من جلب HTTP، أو BLOB في قاعدة البيانات، أو استخراج من أرشيف zip. هذا يتجنب الكتابة إلى القرص:
import { Scene } from '@aspose/3d';
import { ObjLoadOptions } from '@aspose/3d/formats/obj';
import * as fs from 'fs';
const buffer: Buffer = fs.readFileSync('model.obj');
const scene = new Scene();
const options = new ObjLoadOptions();
options.enableMaterials = true;
scene.openFromBuffer(buffer, options);
console.log(`Loaded ${scene.rootNode.childNodes.length} root nodes`);بالنسبة إلى الصيغ الثنائية (GLB، STL binary، 3MF)، تقوم المكتبة بقراءة البايتات السحرية من الذاكرة المؤقتة لاكتشاف الصيغة تلقائيًا، لذا يمكنك تمرير undefined كوسيط الخيارات:
import { Scene } from '@aspose/3d';
import * as fs from 'fs';
const glbBuffer: Buffer = fs.readFileSync('model.glb');
const scene = new Scene();
scene.openFromBuffer(glbBuffer); // format auto-detected from GLB magic bytes
التحميل من HTTP (Node.js 18+)
اجلب أصلًا بعيدًا وحمّله دون التفاعل مع نظام الملفات:
import { Scene } from '@aspose/3d';
async function loadFromUrl(url: string): Promise<Scene> {
const response = await fetch(url);
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const arrayBuffer = await response.arrayBuffer();
const buffer = Buffer.from(arrayBuffer);
const scene = new Scene();
scene.openFromBuffer(buffer);
return scene;
}
const scene = await loadFromUrl('https://example.com/model.glb');
console.log(`Loaded scene: ${scene.rootNode.childNodes.length} root nodes`);فحص المشهد المحمّل
بعد التحميل، تجول في رسم المشهد لتعداد العقد وتحديد الهندسة:
import { Scene, Mesh, Node } from '@aspose/3d';
const scene = new Scene();
scene.open('model.fbx');
function inspect(node: Node, depth: number = 0): void {
const indent = ' '.repeat(depth);
const entityType = node.entity ? node.entity.constructor.name : '(none)';
console.log(`${indent}${node.name} [${entityType}]`);
if (node.entity instanceof Mesh) {
const mesh = node.entity as Mesh;
console.log(`${indent} vertices: ${mesh.controlPoints.length}, polygons: ${mesh.polygonCount}`);
}
for (const child of node.childNodes) {
inspect(child, depth + 1);
}
}
inspect(scene.rootNode);قراءة بيانات تعريف الأصل
ال assetInfo الخاصية تكشف عن بيانات التعريف على مستوى الملف:
import { Scene } from '@aspose/3d';
const scene = new Scene();
scene.open('model.fbx');
const info = scene.assetInfo;
if (info) {
console.log(`Creator: ${info.creator}`);
console.log(`Unit name: ${info.unitName}`);
console.log(`Unit scale: ${info.unitScaleFactor}`);
}ليس كل الصيغ تُملأ assetInfo. يحتوي FBX و COLLADA على بيانات تعريف غنية؛ عادةً لا يحتوي OBJ و STL على ذلك.
مرجع خيارات التحميل الخاصة بـ Format
| الصيغة | فئة الخيارات | مسار الاستيراد | الخيارات الرئيسية |
|---|---|---|---|
| OBJ | ObjLoadOptions | @aspose/3d/formats/obj | enableMaterials, flipCoordinateSystem, scale, normalizeNormal |
| glTF / GLB | (لا شيء مطلوب) | N/A | تم الكشف تلقائيًا؛ لا حاجة لفئة الخيارات |
| STL | StlLoadOptions | @aspose/3d/formats/stl | (لا توجد خيارات قابلة للتكوين في الإصدار الحالي) |
| FBX | FbxLoadOptions | @aspose/3d/formats/fbx | (لا توجد خيارات قابلة للتكوين في الإصدار الحالي) |
| COLLADA | ColladaLoadOptions | @aspose/3d/formats/collada | (لا توجد خيارات قابلة للتكوين في الإصدار الحالي) |
| 3MF | (لا شيء مطلوب) | N/A | تم الكشف تلقائيًا |
أخطاء التحميل الشائعة
| العَرَض | السبب | إصلاح |
|---|---|---|
Error: Cannot find module '@aspose/3d/formats/obj' | moduleResolution لم يتم تعيينه إلى node | إضافة "moduleResolution": "node" إلى tsconfig.json |
| قائمة العقد فارغة بعد تحميل OBJ | .mtl sidecar مفقود أو enableMaterials غير مُعيّن | تعيين options.enableMaterials = true وتأكد من .mtl في نفس الدليل |
المشهد يُحمَّل ولكن rootNode.childNodes فارغ | يستخدم التنسيق شبكة جذرية واحدة، وليس عقدًا فرعية | الوصول scene.rootNode.entity مباشرة |
openFromBuffer يرمي مع STL ثنائي | تم تقطيع الذاكرة المؤقتة بشكل غير صحيح (البتات المتبقية مفقودة) | استخدم الكامل readFileSync() الإخراج دون تقطيع |
| مصفوفة مقاطع الرسوم المتحركة فارغة بعد تحميل FBX | ملف FBX يستخدم التحويلات المخبوزة، وليس المقاطع | يتم تثبيت الرسوم المتحركة لكل إطار؛ ستكون مصفوفة المقاطع فارغة |
انظر أيضًا
- حفظ نماذج 3D: خيارات التصدير و
saveToBuffer - مخطط المشهد: استعراض وتعديل تسلسل العقد
- نظرة عامة على API: جميع الفئات والتعدادات
- دعم الصيغ: مصفوفة القراءة/الكتابة الكاملة