الخصائص والوظائف

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

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

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

ويهدف الحزمة إلى 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 for TypeScript يقرأ ويكتب ستة تنسيقات ملف 3D الرئيسية.تكتشف النماذج تلقائيًا من الأرقام السحرية الثنائية عند التحميل ، لذلك لا تحتاج إلى تحديد تنمية المصدر صراحة.

تحميل 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 (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);

مشاهدة Graph

كل محتوى 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: الترجمة المحلية ، الدوران (Euler و Quaternion) ، وتوسعها

عبر المسرحية الرسم البياني:

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 ويعرض نقاط التحكم (المتحولات) ومؤشرات البوليغون وعناصر الورق العادي والأشعة فوق البنفسجية والألوان المتحولة.

فئات الهندسة الجيولوجية الرئيسية:

• Mesh: البوليغون الماس مع controlPoints و polygonCount
• Geometry: الدرجة الأساسية مع إدارة العناصر الخلفية
• VertexElementNormal:-الطبيعيات البارية أو البوليغونية
• VertexElementUV: إحداثيات النسيج (قناة واحدة أو أكثر)
• VertexElementVertexColor: البيانات اللونية per-vertex
• MappingMode: يراقب كيفية خرائط البيانات عنصر إلى البوليغونات (CONTROL_POINT, POLYGON_VERTEX, POLYGON, EDGE, ALL_SAME)
• ReferenceMode: التحكم في استراتيجية التصنيف (DIRECT, INDEX, INDEX_TO_DIRECT)
• VertexElementType: يحدد الرماد من العنصر الخلفي
• TextureMapping: قناة النصوص القائمة

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

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 for 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);

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

السفن المكتبة مع مجموعة كاملة من أنواع الرياضيات 3D، كلها مكتوبة بالكامل:

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

الحساب صندوق الحدود من أطراف الماس:

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);

بناء تحويل من زوايا Euler:

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));

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

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

• AnimationClip: مجموعة اسمية من عقدة الرسوم المتحركة؛ تم الوصول إليها عبر scene.animationClips;· المعرضات animations: AnimationNode[]
• AnimationNode: اسم المجموعة من BindPoint(ب) تم إنشاؤه من خلال clip.createAnimationNode(name),الوصول عبر clip.animations
• BindPoint:• يربط واحد AnimationNode إلى ممتلكات محددة على موضوع مسرحي؛ عرض property و channelsCount
• AnimationChannel: توسيع KeyframeSequence;- يحتفظ بمفصل منفصل keyframeSequence;• تم الوصول إليها من خلال bindPoint.getChannel(name)
• KeyFrame: زوج واحد من الوقت / القيمة ؛ يحمل per-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() تحميل المشهد 3D مباشرة من الذاكرة 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 الثنائي، وطباعة المعلومات الطبيعية على التوالي، ثم إعادة تصدير المشهد كASCII STl والتحقق من المقطع.

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 عند إنتاج الأصول لمحركات الويب أو اللعبة.Binary GLB هو ملف واحد محمول الذاتي ويحمل في المتصفحات والمحرك أسرع من JSON + .bin split.
• استخدام openFromBuffer() في بيئات خالية من الخادم لتجنب الملف المؤقت I/O. إدخال الأصول، اجتياز Buffer مباشرة، وكتب النتيجة إلى تدفق أو غيره من البوفر.
• التحقق node.entity قبل أن يغطي:لا يحمل كل عقدة كيانًا، ويحمي دائمًّا مع واحد. instanceof التحقق قبل الوصول Mesh- خصائص خاصة مثل controlPoints.
• مجموعة normalizeNormal = true في ObjLoadOptions عندما يأتي ملفات المصدر OBJ من مصادر غير موثوق بها. وهذا يمنع التدهور العادي من الانتشار إلى خطوات التسليم أو التحقق من الانخفاض.
• الحفاظ على strict: true في tsconfig.json:مكتبة: مكتب مع noImplicitAny و strictNullChecks.- إلغاء strict يخفي خطأ النوع الحقيقي ويهزم قيمة API المكتوبة.
• عبر childNodes,لا يوجد مؤشر لون: من childNodes يعود الممتلكات إلى غير قابلة للتأكد؛ تجنب الاعتماد على المؤشر الرقمي للحصول على التوافق المتقدم.

القضايا المشتركة

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

هل تتطلب المكتبة أي إضافات أو حزم نظامية أصلية؟? No. 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 تنتج أ .gltf ملف JSON بالإضافة إلى ملفات منفصلة .bin بوفير الجانب الثنائي. binaryMode = true إنتاج واحد من المحتويات الذاتية .glb الملفات - استخدام true تسليم الأصول الإنتاجية.

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

هل دعم FBX كاملاً؟? لا يوجد فصول FBX المستوردة والمتصدرة موجودة في المكتبة، ولكن FB X غير مدمج في Scene.open() أو Scene.save() التفكير الذاتي - الاتصال scene.open('file.fbx') لن تستدعي المستورد FBX؛ سيتم التعامل مع الملف من خلال مسار الانخفاض STL. استخدم فصول المستثمر/المستورد على وجه التحديد FBx مباشرة إذا كنت بحاجة إلى FB X I/O. انظر جدول دعم النموذج أعلاه الذي يرمز إليه FB x No*.

هل يدعم المكتبة TypeScript 4.x؟? ينصح TypeScript 5.0+. يجب أن يعمل Typecript 4.7+ في الممارسة العملية ، ولكن يتم اختبار المكتبة ومؤلفها مقابل 5.0+.

إشارة API