ویژگی‌ها و عملکردها

Aspose.3D FOSS برای TypeScript یک کتابخانه Node.js تحت مجوز MIT است که برای بارگذاری، ساخت و خروجی‌گیری صحنه‌های سه‌بعدی استفاده می‌شود. این کتابخانه همراه با تعاریف کامل نوع TypeScript و یک وابستگی زمان اجرا (xmldom), و پشتیبانی از شش فرمت فایل سه‌بعدی اصلی. این صفحه مرجع اصلی برای تمام حوزه‌های ویژگی است و شامل مثال‌های کد TypeScript قابل اجرا برای هر یک می‌باشد.

نصب و راه‌اندازی

پکیج را از npm با یک فرمان واحد نصب کنید:

npm install @aspose/3d

این بسته برای CommonJS هدف‌گذاری شده و به Node.js نسخه ۱۸ یا بالاتر نیاز دارد. پس از نصب، اطمینان حاصل کنید که 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 شش فرمت اصلی فایل‌های سه‌بعدی را می‌خواند و می‌نویسد. تشخیص فرمت به‌صورت خودکار از اعداد جادویی باینری هنگام بارگذاری انجام می‌شود، بنابراین نیازی به مشخص کردن صریح فرمت منبع ندارید.

بارگذاری 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);

گراف صحنه

تمام محتوای سه‌بعدی به صورت یک درخت از 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: نرمال‌های per-vertex یا per-polygon-vertex
• VertexElementUV: مختصات بافت (یک یا چند کانال UV)
• 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 برای TypeScript از سه نوع متریال پشتیبانی می‌کند که تمام بازه از سایه‌زنی Phong قدیمی تا رندر فیزیکی‑مبنا را پوشش می‌دهند:

• LambertMaterial: رنگ diffuse و رنگ ambient؛ به مواد ساده 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: بردار ۳ مؤلفه‌ای؛ پشتیبانی می‌کند minus(), times(), dot(), cross(), normalize(), length, angleBetween()
• Vector4: بردار ۴ مؤلفه‌ای برای مختصات همگن
• Matrix4: ماتریس تبدیل ۴×۴ با 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));

سیستم انیمیشن

API انیمیشن کلیپ‌ها، گره‌ها، کانال‌ها و توالی‌های فریم کلیدی را مدل‌سازی می‌کند:

• AnimationClip: مجموعه نام‌گذاری‌شده‌ای از گره‌های انیمیشن؛ دسترسی از طریق scene.animationClips; نمایش می‌دهد animations: AnimationNode[]
• AnimationNode: گروه نام‌گذاری‌شده‌ای از BindPointها; ایجاد شده از طریق 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: enum: LINEAR, CONSTANT, BEZIER, B_SPLINE, CARDINAL_SPLINE, TCB_SPLINE
• Extrapolation: class با type: ExtrapolationType و repeatCount: number
• ExtrapolationType: enum: 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 بدون نیاز به تعیین پارامتر قالب شناسایی می‌شوند.

نمونه‌های استفاده

مثال ۱: بارگذاری 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');

مثال ۲: مسیر دورانی 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() در محیط‌های بدون سرور برای جلوگیری از I/O فایل موقت. دارایی را واکشی کنید، آن را Buffer مستقیم، و خروجی را به یک جریان یا بافر دیگر بنویسید.
• بررسی node.entity قبل از تبدیل: همه گره‌ها موجودیتی ندارند. همیشه با یک instanceof بررسی قبل از دسترسی Meshویژگی‌های خاص مانند controlPoints.
• تنظیم normalizeNormal = true در ObjLoadOptions زمانی که فایل‌های OBJ منبع شما از منابع غیرقابل اعتماد می‌آیند. این کار از انتشار نرمال‌های معیوب به مراحل رندرینگ یا اعتبارسنجی بعدی جلوگیری می‌کند.
• نگه دارید strict: true در tsconfig.json: کتابخانه با noImplicitAny و strictNullChecks. غیرفعال‌سازی strict خطاهای واقعی نوع را پنهان می‌کند و ارزش API تایپ‌شده را از بین می‌برد.
• پیمایش از طریق childNodes,، نه یک حلقه ایندکس: این childNodes ویژگی یک iterable برمی‌گرداند؛ از تکیه بر ایندکس عددی برای سازگاری آینده خودداری کنید.

مشکلات رایج

سوالات متداول

آیا library به هیچ افزونهٔ بومی یا بستهٔ سیستمی نیاز دارد؟? شماره Aspose.3D FOSS برای TypeScript یک وابستگی زمان اجرا دارد: xmldom,، که یک JavaScript خالص است و به‌صورت خودکار توسط npm نصب می‌شود. هیچ .node افزونه بومی وجود ندارد و هیچ بسته سیستمی برای نصب وجود ندارد.

کدام نسخه‌های Node.js پشتیبانی می‌شوند؟? Node.js 18، 20 و 22 LTS. این کتابخانه خروجی CommonJS هدف دارد و به‌صورت داخلی از ویژگی‌های زبانی ES2020 استفاده می‌کند.

آیا می‌توانم از این کتابخانه در یک باندل مرورگر (webpack/esbuild) استفاده کنم؟? این کتابخانه هدف Node.js را دارد و از Node.js fs و Buffer APIها. بسته‌بندی برای مرورگر به‌صورت رسمی پشتیبانی نمی‌شود. برای استفاده در مرورگر، صحنه را در سمت سرور بارگذاری کنید و نتیجه را (مثلاً به‌صورت GLB) به کلاینت منتقل کنید.

تفاوت بین چیست؟ GltfSaveOptions.binaryMode = true و false? binaryMode = false یک … تولید می‌کند .gltf فایل JSON به‌همراه یک … جداگانه .bin بافر باینری sidecar. 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') فراخوانی نخواهد شد؛ فایل توسط مسیر پشتیبان STL پردازش می‌شود. اگر به ورودی/خروجی FBX نیاز دارید، مستقیماً از کلاس‌های واردکننده/صادرکننده مخصوص FBX استفاده کنید. جدول پشتیبانی فرمت‌های بالا را ببینید که FBX را به عنوان No*.

آیا کتابخانه از TypeScript 4.x پشتیبانی می‌کند؟? TypeScript 5.0+ توصیه می‌شود. TypeScript 4.7+ در عمل باید کار کند، اما کتابخانه در مقابل 5.0+ تست و توسعه یافته است.

خلاصه مرجع API