دعم 3D Format

Aspose.3D FOSS لـ TypeScript يقرأ ويكتب سبعة صيغ ملفات 3D رئيسية. اكتشاف الصيغة يتم تلقائيًا عند التحميل: المكتبة تفحص أرقام السحر الثنائية لذا لا تحتاج إلى تحديد صيغة المصدر. فئات الخيارات الخاصة بكل صيغة تُستورد من مسارات فرعية داخل الـ @aspose/3d الحزمة.

التنسيقات المدعومة

OBJ (Wavefront)

يدعم OBJ كلًا من الاستيراد والتصدير في @aspose/3d. عند الحفظ كـ OBJ، مكتبة المواد (.mtl) يُكتب تلقائيًا بجانب الـ .obj ملف. استخدم ObjLoadOptions للتحكم في تحميل المواد وسلوك نظام الإحداثيات.

الخيارات الرئيسية لـ ObjLoadOptions:

import { Scene } from '@aspose/3d';
import { ObjLoadOptions } from '@aspose/3d/formats/obj';

const scene = new Scene();
const opts = new ObjLoadOptions();
opts.enableMaterials = true;
opts.normalizeNormal = true;

scene.open('model.obj', opts);
console.log(`Loaded ${scene.rootNode.childNodes.length} top-level node(s)`);

لتحويل ملف OBJ إلى أي تنسيق قابل للكتابة، قم بتحميله واستدعِ scene.save() مع فئة التنسيق الهدف.

glTF و GLB

glTF 2.0 هو تنسيق التبادل الموصى به للاستخدام على الويب ومحركات الألعاب. المكتبة تستخدم نفس GltfFormat الفئة لكلا .gltf (JSON + sidecar) و .glb (ثنائي، مستقل) ناتج. التبديل بينهما باستخدام GltfSaveOptions.binaryMode.

تحميل glTF أو GLB:

import { Scene } from '@aspose/3d';
import { GltfLoadOptions } from '@aspose/3d/formats/gltf';

const scene = new Scene();
scene.open('model.gltf', new GltfLoadOptions());
// or
scene.open('model.glb');  // format detected from magic bytes

تصدير كـ JSON glTF (.gltf + .bin):

import { Scene } from '@aspose/3d';
import { GltfSaveOptions, GltfFormat } from '@aspose/3d/formats/gltf';

const scene = new Scene();
scene.open('input.fbx');

const opts = new GltfSaveOptions();
opts.binaryMode = false;  // produces output.gltf + output.bin
scene.save('output.gltf', GltfFormat.getInstance(), opts);

تصدير كـ ثنائي GLB (.glb):

import { Scene } from '@aspose/3d';
import { GltfSaveOptions, GltfFormat } from '@aspose/3d/formats/gltf';

const scene = new Scene();
scene.open('input.obj');

const opts = new GltfSaveOptions();
opts.binaryMode = true;  // single self-contained file
scene.save('output.glb', GltfFormat.getInstance(), opts);

استخدم binaryMode = true لتسليم الأصول في الإنتاج. ملف واحد .glb يتم تحميله أسرع في المتصفحات والمحركات مقارنةً بالزوج النصي + الثنائي المنفصل.

STL

STL هو تنسيق شبكة مثلثية يُستخدم في CAD والطباعة ثلاثية الأبعاد. يتم دعم كل من STL الثنائي وASCII للإدخال والإخراج. StlSaveOptions.binaryMode يتحكم فيما إذا كان الإخراج ثنائيًا (مضغوطًا) أو ASCII (قابلًا للقراءة من قبل الإنسان).

import { Scene } from '@aspose/3d';
import { StlLoadOptions, StlSaveOptions } from '@aspose/3d/formats/stl';

const scene = new Scene();
scene.open('model.stl', new StlLoadOptions());

// Export as binary STL (default, compact)
const binaryOpts = new StlSaveOptions();
binaryOpts.binaryMode = true;
scene.save('output_binary.stl', binaryOpts);

// Export as ASCII STL (human-readable)
const asciiOpts = new StlSaveOptions();
asciiOpts.binaryMode = false;
scene.save('output_ascii.stl', asciiOpts);

يخزن STL فقط الهندسة المثلثية والاتجاهات العمودية للرؤوس. لا يتم حفظ بيانات المواد وUV في STL.

3MF (3D Manufacturing Format)

3MF is an XML-based format designed for additive manufacturing. It supports color and material metadata alongside geometry. Use it when exchanging files with 3D printing slicers or manufacturing workflows.

import { Scene } from '@aspose/3d';
import { ThreeMfSaveOptions } from '@aspose/3d/formats/3mf';

const scene = new Scene();
scene.open('model.3mf');

// Re-export as 3MF
scene.save('output.3mf', new ThreeMfSaveOptions());

3MF files are ZIP archives internally. The library handles archive creation and extraction automatically.

FBX

تحذير: فئات مستورد ومصدّر FBX (FbxImporter, FbxExporter) موجودة في المكتبة، لكن الكشف التلقائي عن تنسيق FBX هو غير موصل إلى scene.open() أو scene.save(). استدعاء scene.open('file.fbx') لن يستدعي مستورد FBX — سيتجاوز الملف إلى بديل STL. استدعاء scene.save('output.fbx', opts) لن يستدعي مُصدّر FBX. جدول دعم الصيغ أعلاه يحدد FBX كـ No* لهذا السبب. استخدم GLB أو COLLADA للاستيراد والتصدير الكامل عبر scene.open() / scene.save().

COLLADA (DAE)

COLLADA هو تنسيق تبادل قائم على XML يدعمه مجموعة واسعة من أدوات DCC (Blender, Maya, Cinema 4D). تستخدم المكتبة xmldom التبعية لتحليل XML؛ يتم تثبيتها تلقائيًا مع npm install @aspose/3d.

import { Scene } from '@aspose/3d';
import { ColladaSaveOptions } from '@aspose/3d/formats/collada';

const scene = new Scene();
scene.open('model.dae');

// Re-export as COLLADA
const saveOpts = new ColladaSaveOptions();
scene.save('output.dae', saveOpts);

قد تحتوي ملفات COLLADA على بيانات تعريف مقياس الوحدات (<unit> العنصر). تقوم المكتبة بتطبيق تحويل الوحدات تلقائيًا عند التحميل.

الكشف التلقائي عن الصيغة

عند التحميل من مسار ملف، تحاول المكتبة اكتشاف الصيغة من أرقام السحر الثنائية قبل الرجوع إلى امتداد الملف. هذا يعني أنه يمكنك تحميل ملف GLB باسم .bin أو ملف STL باسم .model دون تحديد الصيغة صراحةً.

عند التحميل من Buffer مع scene.openFromBuffer(), اكتشاف رقم السحر هو الآلية الأساسية:

import { Scene } from '@aspose/3d';
import * as fs from 'fs';

const buffer = fs.readFileSync('model.glb');
const scene = new Scene();
scene.openFromBuffer(buffer);  // format detected from magic bytes: 'glTF'

console.log(`Root has ${scene.rootNode.childNodes.length} child node(s)`);

الصيغ ذات أرقام السحر الموثوقة: GLB (glTF), STL ثنائي (80-byte header + triangle count), 3MF (ZIP magic PK). OBJ و COLLADA نصيان ويتم اكتشافهما من امتداد الملف أو من خلال فئة الخيارات التي تمررها.

نصائح

• OBJ يدعم كل من الاستيراد والتصدير: عند الحفظ كـ OBJ، الـ .mtl ملف المادة يُكتب تلقائيًا بجانب الـ .obj ملف.
• استخدم GLB لتسليم الويب:تنسيق الثنائي المستقل يتجنب مشكلات CORS مع .bin sidecars ويُحمّل أسرع في عارضات WebGL.
• مرّر خيارات خاصة بالتنسيق: عام scene.open(path) يعمل مع معظم التنسيقات، لكن تمرير فئة خيارات التحميل يتيح سلوكًا خاصًا بالتنسيق مثل تحميل مواد OBJ أو تطبيع إحداثيات STL.
• xmldom مطلوب لـ COLLADA: يتم تثبيته تلقائيًا. لا تقم بإضافته إلى peerDependencies أو حاول إزالته؛ قارئ COLLADA يستدعيه مباشرةً.

المشكلات الشائعة

انظر أيضًا

• الميزات والوظائف: رسم المشهد، الشبكة، المواد، الرسوم المتحركة، وواجهات برمجة التطبيقات الرياضية APIs.
• رسم المشهد: بناء وتصفح شجرة العقد.
• كيفية بناء 3D Mesh برمجيًا