الميزات والوظائف

Aspose.3D FOSS for TypeScript هي مكتبة Node.js مرخصة MIT لتحميل، إنشاء وتصدير المشاهد ثلاثية الأبعاد. تتضمن تعريفات نوع TypeScript كاملة، واعتماد تشغيل واحد (xmldom)، ودعم لست صيغ ملفات ثلاثية الأبعاد رئيسية. هذه الصفحة هي المرجع الأساسي لجميع مجالات الميزات وتحتوي على أمثلة شفرة TypeScript قابلة للتنفيذ لكل منها.

التثبيت والإعداد

قم بتثبيت الحزمة من npm باستخدام أمر واحد:

npm install @aspose/3d

الحزمة تستهدف CommonJS وتتطلب Node.js 18 أو أحدث. بعد التثبيت، تحقق من أن tsconfig.json يحتوي على خيارات المترجم التالية لضمان التوافق الكامل:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "moduleResolution": "node",
    "esModuleInterop": true,
    "strict": true
  }
}

استورد الفئة الرئيسية Scene من جذر الحزمة. يتم استيراد فئات الخيارات الخاصة بكل تنسيق من المسارات الفرعية الخاصة بها:

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

الميزات والوظائف

دعم الصيغ

تقوم Aspose.3D FOSS لـ TypeScript بقراءة وكتابة ست صيغ ملفات ثلاثية الأبعاد رئيسية. يتم الكشف عن الصيغة تلقائيًا من أرقام السحر الثنائية عند التحميل، لذا لا تحتاج إلى تحديد صيغة المصدر صراحةً.

تحميل OBJ مع المواد:

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

const scene = new Scene();
const options = new ObjLoadOptions();
options.enableMaterials = true;
options.flipCoordinateSystem = false;
options.scale = 1.0;
options.normalizeNormal = true;
scene.open('model.obj', options);

حفظ إلى GLB (binary glTF):

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

const scene = new Scene();
// ... build or load scene content

const opts = new GltfSaveOptions();
opts.binaryMode = true;
scene.save('output.glb', GltfFormat.getInstance(), opts);

مخطط المشهد

يتم تنظيم جميع محتوى 3D كشجرة من كائنات Node تتجذر في scene.rootNode. يمكن لكل عقدة أن تحمل Entity (Mesh، Camera، Light، أو SceneObject أخرى) وTransform يحدد موقعها بالنسبة للوالد.

الفئات الرئيسية لمخطط المشهد:

• Scene: الحاوية ذات المستوى الأعلى; يحتوي على rootNode و animationClips
• Node: عقدة شجرة مسماة مع childNodes، entity، transform، و materials
• Entity: فئة أساسية للكائنات القابلة للإرفاق (Mesh، Camera، Light)
• SceneObject: فئة أساسية مشتركة بين Node و Entity
• A3DObject: فئة أساسية جذرية مع name وحقيبة الخصائص
• Transform: تحويل محلي، دوران (إيلر وكواترنيون)، ومقياس

التنقل عبر مخطط المشهد:

import { Scene, Node, Mesh } from '@aspose/3d';

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

function visit(node: Node, depth: number = 0): void {
  const indent = '  '.repeat(depth);
  console.log(`${indent}Node: ${node.name}`);
  if (node.entity) {
    console.log(`${indent}  Entity: ${node.entity.constructor.name}`);
  }
  for (const child of node.childNodes) {
    visit(child, depth + 1);
  }
}

visit(scene.rootNode);

إنشاء تسلسل هرمي للمشهد برمجيًا:

import { Scene, Node } from '@aspose/3d';

const scene = new Scene();
const parent = scene.rootNode.createChildNode('chassis');
const wheel = parent.createChildNode('wheel_fl');
wheel.transform.translation.set(0.9, -0.3, 1.4);

الهندسة والشبكة

Mesh هو نوع الهندسة الأساسي. يمد Geometry ويكشف عن نقاط التحكم (الرؤوس)، مؤشرات المضلعات، وعناصر الرؤوس للاتجاهات العادية، وإحداثيات UV، وألوان الرؤوس.

فئات الهندسة الأساسية:

• Mesh: شبكة مضلعات مع controlPoints و polygonCount
• Geometry: فئة أساسية مع إدارة عناصر الرؤوس
• VertexElementNormal: متجهات عادية لكل رأس أو لكل رأس مضلع
• VertexElementUV: إحداثيات النسيج (قناة UV واحدة أو أكثر)
• VertexElementVertexColor: بيانات لون لكل رأس
• MappingMode: يتحكم في كيفية ربط بيانات العنصر بالمضلعات (CONTROL_POINT، POLYGON_VERTEX، POLYGON، EDGE، ALL_SAME)
• ReferenceMode: يتحكم في استراتيجية الفهرسة (DIRECT، INDEX، INDEX_TO_DIRECT)
• VertexElementType: يحدد الدلالة لعنصر الرأس
• TextureMapping: تعداد قناة النسيج

قراءة بيانات mesh من مشهد محمَّل:

import { Scene, Mesh, VertexElementType } from '@aspose/3d';

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

for (const node of scene.rootNode.childNodes) {
  if (node.entity instanceof Mesh) {
    const mesh = node.entity as Mesh;
    console.log(`Mesh "${node.name}": ${mesh.controlPoints.length} vertices, ${mesh.polygonCount} polygons`);

    const normals = mesh.getElement(VertexElementType.NORMAL);
    if (normals) {
      console.log(`  Normal mapping: ${normals.mappingMode}`);
    }
  }
}

نظام المواد

يدعم Aspose.3D FOSS لـ TypeScript ثلاثة أنواع من المواد تغطي النطاق الكامل من التظليل الفونغ التقليدي إلى التصيير القائم على الفيزياء:

• LambertMaterial: اللون المنتشر واللون المحيط؛ يطابق مواد OBJ/DAE البسيطة
• PhongMaterial: يضيف اللون اللامع، اللمعان، والإنبعاث؛ نوع مادة OBJ الافتراضي
• PbrMaterial: نموذج الخشونة/المعدنية القائم على الفيزياء؛ يُستخدم لاستيراد وتصدير glTF 2.0

قراءة المواد من مشهد OBJ محمَّل:

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

const scene = new Scene();
const options = new ObjLoadOptions();
options.enableMaterials = true;
scene.open('model.obj', options);

for (const node of scene.rootNode.childNodes) {
  for (const mat of node.materials) {
    if (mat instanceof PhongMaterial) {
      const phong = mat as PhongMaterial;
      console.log(`  Phong: diffuse=${JSON.stringify(phong.diffuseColor)}, shininess=${phong.shininess}`);
    } else if (mat instanceof LambertMaterial) {
      console.log(`  Lambert: diffuse=${JSON.stringify((mat as LambertMaterial).diffuseColor)}`);
    }
  }
}

تطبيق مادة PBR عند بناء مشهد glTF:

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

const scene = new Scene();
const node = scene.rootNode.createChildNode('sphere');
const mat = new PbrMaterial();
mat.albedo = new Vector3(0.8, 0.2, 0.2);   // red-tinted albedo; albedo starts null, must assign
mat.metallicFactor = 0.0;
mat.roughnessFactor = 0.5;
node.material = mat;

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

أدوات الرياضيات

تأتي المكتبة مع مجموعة كاملة من أنواع الرياضيات ثلاثية الأبعاد، جميعها مكتوبة بالكامل:

• Vector3: متجه ثلاثي المكوّنات؛ يدعم minus()، times()، dot()، cross()، normalize()، length، angleBetween()
• Vector4: متجه رباعي المكوّنات للإحداثيات المتجانسة
• Matrix4: مصفوفة تحويل 4×4 مع concatenate()، transpose، decompose، setTRS
• Quaternion: كواترن دوران مع fromEulerAngle() (ثابت، مفرد)، eulerAngles() (طريقة كائن)، slerp()، normalize()
• BoundingBox: صندوق احتواء محاذى للمحاور مع minimum، maximum، center، size، merge
• FVector3: نسخة ذات دقة مفردة من Vector3 تُستخدم في بيانات عنصر القمة

حساب صندوق حدودي من رؤوس الشبكة:

import { Scene, Mesh, Vector3, BoundingBox } from '@aspose/3d';

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

let box = new BoundingBox();
for (const node of scene.rootNode.childNodes) {
  if (node.entity instanceof Mesh) {
    for (const pt of (node.entity as Mesh).controlPoints) {
      box.merge(new Vector3(pt.x, pt.y, pt.z));
    }
  }
}
console.log('Center:', box.center);
console.log('Extents:', box.size);

إنشاء تحويل من زوايا أويلر:

import { Quaternion, Vector3, Matrix4 } from '@aspose/3d';

const rot = Quaternion.fromEulerAngle(0, Math.PI / 4, 0); // 45° around Y
const mat = new Matrix4();
mat.setTRS(new Vector3(0, 0, 0), rot, new Vector3(1, 1, 1));

نظام الرسوم المتحركة

نموذج واجهة برمجة تطبيقات الرسوم المتحركة للقطات والعقد والقنوات وتسلسلات الإطارات المفتاحية:

• AnimationClip: مجموعة مسماة من عقد الرسوم المتحركة؛ يتم الوصول إليها عبر scene.animationClips؛ تكشف animations: AnimationNode[]
• AnimationNode: مجموعة مسماة من BindPoints؛ تم إنشاؤها عبر clip.createAnimationNode(name)، ويتم الوصول إليها عبر clip.animations
• BindPoint: يربط AnimationNode بخصائص محددة على كائن المشهد؛ يكشف property وchannelsCount
• AnimationChannel: يمد KeyframeSequence؛ يحتوي على keyframeSequence منفصل؛ يتم الوصول إليه عبر bindPoint.getChannel(name)
• KeyFrame: زوج وقت/قيمة واحد؛ يحمل interpolation: Interpolation لكل إطار مفتاح
• KeyframeSequence: قائمة مرتبة من كائنات KeyFrame عبر keyFrames؛ تحتوي على preBehavior وpostBehavior (Extrapolation)
• Interpolation: تعداد: LINEAR, CONSTANT, BEZIER, B_SPLINE, CARDINAL_SPLINE, TCB_SPLINE
• Extrapolation: فئة تحتوي على type: ExtrapolationType وrepeatCount: number
• ExtrapolationType: تعداد: CONSTANT, GRADIENT, CYCLE, CYCLE_RELATIVE, OSCILLATE

قراءة بيانات الرسوم المتحركة من مشهد محمَّل:

import { Scene, AnimationNode, BindPoint } from '@aspose/3d';

const scene = new Scene();
scene.open('animated.dae');   // COLLADA animation import is supported

for (const clip of scene.animationClips) {
  console.log(`Clip: "${clip.name}"`);
  for (const animNode of clip.animations) {          // clip.animations, not clip.nodes
    console.log(`  AnimationNode: ${animNode.name}`);
    for (const bp of animNode.bindPoints) {           // animNode.bindPoints, not animNode.channels
      console.log(`  BindPoint: property="${bp.property.name}", channels=${bp.channelsCount}`);
    }
  }
}

دعم التدفق والذاكرة المؤقتة

استخدم scene.openFromBuffer() لتحميل مشهد ثلاثي الأبعاد مباشرةً من Buffer في الذاكرة. هذا هو النمط الموصى به للوظائف بدون خادم، خطوط الأنابيب المتدفقة، ومعالجة الأصول التي يتم جلبها عبر HTTP دون الكتابة إلى القرص.

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

// Load file into memory, then parse from buffer
const buffer: Buffer = fs.readFileSync('model.obj');
const scene = new Scene();
const options = new ObjLoadOptions();
options.enableMaterials = true;
scene.openFromBuffer(buffer, options);

for (const node of scene.rootNode.childNodes) {
  if (node.entity) {
    console.log(node.name, node.entity.constructor.name);
  }
}

يتم تطبيق الكشف التلقائي عن الصيغة من أرقام السحر الثنائية عند التحميل من الذاكرة المؤقتة، لذا يتم التعرف على ملفات GLB و STL الثنائية و 3MF دون الحاجة لتحديد معامل الصيغة.

أمثلة الاستخدام

مثال 1: تحميل OBJ وتصدير إلى GLB

يقوم هذا المثال بتحميل ملف Wavefront OBJ مع المواد، ثم يعيد تصدير المشهد كملف glTF ثنائي (GLB) مناسب للاستخدام على الويب ومحركات الألعاب.

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

function convertObjToGlb(inputPath: string, outputPath: string): void {
  const scene = new Scene();

  const loadOpts = new ObjLoadOptions();
  loadOpts.enableMaterials = true;
  loadOpts.flipCoordinateSystem = false;
  loadOpts.normalizeNormal = true;
  scene.open(inputPath, loadOpts);

  // Report what was loaded
  for (const node of scene.rootNode.childNodes) {
    if (node.entity) {
      console.log(`Loaded: ${node.name} (${node.entity.constructor.name})`);
    }
  }

  const saveOpts = new GltfSaveOptions();
  saveOpts.binaryMode = true; // write .glb instead of .gltf + .bin
  scene.save(outputPath, GltfFormat.getInstance(), saveOpts);

  console.log(`Exported GLB to: ${outputPath}`);
}

convertObjToGlb('input.obj', 'output.glb');

المثال 2: STL ذهابًا وإيابًا مع التحقق من المتجهات العادية

يقوم هذا المثال بتحميل ملف STL ثنائي، ويطبع معلومات المتجهات العادية لكل رأس، ثم يعيد تصدير المشهد كملف STL نصي (ASCII) ويتحقق من صحة العملية المتبادلة.

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

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

let totalPolygons = 0;
for (const node of scene.rootNode.childNodes) {
  if (node.entity instanceof Mesh) {
    const mesh = node.entity as Mesh;
    totalPolygons += mesh.polygonCount;

    const normElem = mesh.getElement(VertexElementType.NORMAL) as VertexElementNormal | null;
    if (normElem) {
      console.log(`  Normals: ${normElem.data.length} entries, mapping=${normElem.mappingMode}`);
    }
  }
}
console.log(`Total polygons: ${totalPolygons}`);

// Re-export as ASCII STL
const saveOpts = new StlSaveOptions();
saveOpts.binaryMode = false; // ASCII output
scene.save('output_ascii.stl', saveOpts);

المثال 3: بناء مشهد برمجيًا وحفظه كـ glTF

يبني هذا المثال مشهدًا بمواد PBR من الصفر ويحفظه كملف JSON glTF.

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

const scene = new Scene();
const node = scene.rootNode.createChildNode('floor');

// Build a simple quad mesh (two triangles)
// controlPoints are Vector4 (x, y, z, w) where w=1 for positions
const mesh = new Mesh();
mesh.controlPoints.push(
  new Vector4(-1, 0, -1, 1),
  new Vector4( 1, 0, -1, 1),
  new Vector4( 1, 0,  1, 1),
  new Vector4(-1, 0,  1, 1),
);
mesh.createPolygon([0, 1, 2]);
mesh.createPolygon([0, 2, 3]);
node.entity = mesh;

// Apply a PBR material
const mat = new PbrMaterial();
mat.albedo = new Vector3(0.6, 0.6, 0.6);   // albedo starts null, must assign
mat.metallicFactor = 0.0;
mat.roughnessFactor = 0.8;
node.material = mat;

// Save as JSON glTF
const opts = new GltfSaveOptions();
opts.binaryMode = false;
scene.save('floor.gltf', GltfFormat.getInstance(), opts);
console.log('Scene written to floor.gltf');

نصائح وأفضل الممارسات

• استخدم ObjLoadOptions.enableMaterials = true كلما احتجت إلى بيانات المواد من ملفات .mtl. بدونها، ستكون قائمة المواد على كل عقدة فارغة.
• يفضل binaryMode = true لـ GLB عند إنتاج الأصول للويب أو محركات الألعاب. الـ GLB الثنائي هو ملف واحد مستقل ويُحمَّل أسرع في المتصفحات والمحركات مقارنةً بتقسيم JSON + .bin.
• استخدم openFromBuffer() في بيئات الخوادم غير التقليدية لتجنب عمليات الإدخال/الإخراج للملفات المؤقتة. احصل على الأصل، مرّر Buffer مباشرة، واكتب الناتج إلى تدفق أو مخزن مؤقت آخر.
• تحقق من node.entity قبل التحويل: ليست كل العقد تحمل كيانًا. احرص دائمًا على فحص instanceof قبل الوصول إلى خصائص خاصة بـ Mesh مثل controlPoints.
• عيّن normalizeNormal = true في ObjLoadOptions عندما تكون ملفات OBJ المصدرية من مصادر غير موثوقة. هذا يمنع القيم غير الصالحة للمتجهات العمودية من الانتشار إلى عمليات العرض أو التحقق اللاحقة.
• احتفظ بـ strict: true في tsconfig.json: المكتبة مكتوبة باستخدام noImplicitAny و strictNullChecks. تعطيل strict يخفي الأخطاء النوعية الحقيقية ويقوض قيمة الـ API المكتوبة بأنواع.
• تجول عبر childNodes، وليس عبر حلقة فهرسة: خاصية childNodes تُعيد كائنًا قابلًا للتكرار؛ تجنّب الاعتماد على الفهرسة الرقمية لضمان التوافق المستقبلي.

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

الأسئلة المتكررة

هل تتطلب المكتبة أي إضافات أصلية أو حزم نظام؟ لا. Aspose.3D FOSS for TypeScript لديها اعتماد تشغيل واحد: xmldom، وهو جافاسكريبت نقي ويتم تثبيته تلقائيًا عبر npm. لا توجد إضافات أصلية .node ولا حزم نظام للتثبيت.

أي إصدارات Node.js مدعومة؟ Node.js 18، 20، و 22 LTS. تستهدف المكتبة إخراج CommonJS وتستخدم ميزات لغة ES2020 داخليًا.

هل يمكنني استخدام المكتبة في حزمة متصفح (webpack/esbuild)؟ المكتبة تستهدف Node.js وتستخدم واجهات Node.js fs وBuffer. تجميع المتصفح غير مدعوم رسميًا. للاستخدام في المتصفح، قم بتحميل المشهد على الخادم ثم انقل النتيجة (مثلاً كـ GLB) إلى العميل.

ما الفرق بين GltfSaveOptions.binaryMode = true و false؟ binaryMode = false ينتج ملف JSON .gltf بالإضافة إلى مخزن ثنائي منفصل .bin كملف جانبي. binaryMode = true ينتج ملف .glb واحد مكتمل ذاتيًا. استخدم true لتسليم الأصول في الإنتاج.

هل يمكنني تحميل ملف من استجابة HTTP دون حفظه على القرص؟ نعم. احصل على الاستجابة كـ Buffer (مثلاً باستخدام node-fetch أو المدمج fetch في Node 18+)، ثم استدعِ scene.openFromBuffer(buffer, options).

هل دعم FBX كامل؟
لا. فئات المستورد والمصدر لـ FBX موجودة في المكتبة، لكن FBX غير مدمجة في Scene.open() أو Scene.save() الكشف التلقائي. استدعاء scene.open('file.fbx') لن يُشغّل المستورد الخاص بـ FBX؛ سيتم معالجة الملف عبر مسار الاحتياطي STL. استخدم فئات المستورد/المصدر الخاصة بـ FBX مباشرةً إذا كنت بحاجة إلى إدخال/إخراج FBX. انظر جدول دعم الصيغ أعلاه الذي يحدد FBX كـ No*.

هل تدعم المكتبة TypeScript 4.x؟ يوصى باستخدام TypeScript 5.0+. يجب أن يعمل TypeScript 4.7+ عمليًا، لكن المكتبة تم اختبارها وتطويرها مقابل 5.0+.

ملخص مرجع API