تحميل نموذج 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

الصيغةفئة الخياراتمسار الاستيرادالخيارات الرئيسية
OBJObjLoadOptions@aspose/3d/formats/objenableMaterials, flipCoordinateSystem, scale, normalizeNormal
glTF / GLB(لا شيء مطلوب)N/Aتم الكشف تلقائيًا؛ لا حاجة لفئة الخيارات
STLStlLoadOptions@aspose/3d/formats/stl(لا توجد خيارات قابلة للتكوين في الإصدار الحالي)
FBXFbxLoadOptions@aspose/3d/formats/fbx(لا توجد خيارات قابلة للتكوين في الإصدار الحالي)
COLLADAColladaLoadOptions@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 يستخدم التحويلات المخبوزة، وليس المقاطعيتم تثبيت الرسوم المتحركة لكل إطار؛ ستكون مصفوفة المقاطع فارغة

انظر أيضًا

 العربية