چگونه مدلهای سهبعدی را در TypeScript بارگذاری کنیم
این @aspose/3d پکیج یک API ساده برای برنامههای TypeScript و Node.js جهت باز کردن فایلهای صحنه 3D فراهم میکند. Scene شیء ریشه است: فراخوانی کنید scene.open() با مسیر فایل و گزینههای بارگذاری اختیاری مخصوص فرمت، سپس پیمایش کنید scene.rootNode برای دسترسی به هندسه، مواد و تبدیلات.
راهنمای گام به گام
مرحله ۱: نصب @aspose/3d از طریق npm
پکیج را به پروژه خود اضافه کنید. نیازی به باینریهای بومی یا ابزارهای ساخت مخصوص پلتفرم نیست؛ فقط Node.js نسخه ۱۸ یا بالاتر کافی است.
npm install @aspose/3dبرای پروژههای TypeScript، تعاریف نوع همراه با پکیج بستهبندی شدهاند:
##tsconfig.json: minimum required settings
{
"compilerOptions": {
"target": "ES2020",
"module": "commonjs",
"strict": true
}
}مرحله ۲: وارد کردن Scene و گزینههای مخصوص فرمت
هر فرمت کلاس لودر و شیء گزینههای مخصوص خود را در یک زیرمسیر ارائه میدهد. فقط آنچه نیاز دارید را وارد کنید:
import { Scene } from '@aspose/3d';
import { ObjLoadOptions } from '@aspose/3d/formats/obj';برای سایر فرمتها الگو یکسان است:
import { GltfLoadOptions } from '@aspose/3d/formats/gltf';
import { FbxLoadOptions } from '@aspose/3d/formats/fbx';
import { StlLoadOptions } from '@aspose/3d/formats/stl';مرحله ۳: باز کردن یک فایل ۳بعدی با استفاده از scene.open()
یک Scene نمونه، سپس فراخوانی کنید scene.open() با مسیر فایل و یک شیء گزینههای بارگذاری اختیاری. این فراخوانی به صورت همزمان است.
import { Scene } 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);
console.log('Scene loaded successfully');برای بارگذاری از یک Buffer که قبلاً در حافظه موجود است (در محیطهای بدون سرور یا جریاندار مفید است):
import * as fs from 'fs';
import { Scene } from '@aspose/3d';
import { ObjLoadOptions } from '@aspose/3d/formats/obj';
const buffer = fs.readFileSync('model.obj');
const scene = new Scene();
scene.openFromBuffer(buffer, new ObjLoadOptions());مرحله ۴: تکرار بر روی گرههای صحنه
گراف صحنه یک درخت است که ریشهدار در scene.rootNode. هر Node میتواند گرههای فرزند و یک … اختیاری داشته باشد entity (mesh، دوربین، نور، و غیره).
import { Scene } from '@aspose/3d';
import { ObjLoadOptions } from '@aspose/3d/formats/obj';
const scene = new Scene();
scene.open('model.obj', new ObjLoadOptions());
function visitNode(node: any, depth: number = 0): void {
const indent = ' '.repeat(depth);
console.log(`${indent}Node: ${node.name}`);
if (node.entity) {
console.log(`${indent} Entity type: ${node.entity.constructor.name}`);
}
for (const child of node.childNodes) {
visitNode(child, depth + 1);
}
}
visitNode(scene.rootNode);مرحله ۵: دسترسی به دادههای رئوس مش از طریق controlPoints
وقتی موجودیت یک گره یک Mesh,، میتوانید نقاط کنترل خام (رئوس) را از controlPoints آرایه. هر ورودی یک Vector4 با x, y, z,، و w مؤلفهها.
import { Scene } from '@aspose/3d';
import { ObjLoadOptions } from '@aspose/3d/formats/obj';
const scene = new Scene();
scene.open('model.obj', new ObjLoadOptions());
for (const node of scene.rootNode.childNodes) {
if (!node.entity) continue;
const entity = node.entity;
// Check if the entity is a Mesh by duck-typing controlPoints
if ('controlPoints' in entity) {
const mesh = entity as any;
console.log(`Mesh "${node.name}": ${mesh.controlPoints.length} vertices`);
// Print first three vertices
for (let i = 0; i < Math.min(3, mesh.controlPoints.length); i++) {
const v = mesh.controlPoints[i];
console.log(` v[${i}]: x=${v.x.toFixed(4)}, y=${v.y.toFixed(4)}, z=${v.z.toFixed(4)}`);
}
}
}مرحله ۶: پیکربندی ObjLoadOptions برای بارگذاری مواد
ObjLoadOptions ویژگیهایی را برای کنترل چگونگی همراهی .mtl فایلهای متریال و بافتها حل میشوند.
import { Scene } from '@aspose/3d';
import { ObjLoadOptions } from '@aspose/3d/formats/obj';
const options = new ObjLoadOptions();
options.enableMaterials = true; // parse .mtl file if present
const scene = new Scene();
scene.open('model.obj', options);
// Inspect materials attached to nodes
for (const node of scene.rootNode.childNodes) {
if (node.material) {
console.log(`Material on "${node.name}": ${node.material.constructor.name}`);
}
}مشکلات رایج و راهحلها
خطا: ماژول ‘@aspose/3d/formats/obj’ یافت نشد زیرمسیرهای فرمت نیاز به صادرات بستههای Node.js نسخه 12.7+ دارند. اطمینان حاصل کنید که از Node.js نسخه 18 یا بالاتر استفاده میکنید. اگر از TypeScript استفاده میکنید، تنظیم کنید "moduleResolution": "node16" یا "bundler" در tsconfig.json.
scene.rootNode.childNodes پس از open() خالی است برخی از فایلهای OBJ از پایان خطوط غیر استاندارد استفاده میکنند یا newline انتهایی ندارند. با باز کردن فایل در یک ویرایشگر متن، صحت یک OBJ معتبر را تأیید کنید. همچنین اطمینان حاصل کنید که پاس دادهاید ObjLoadOptions و نه یک عمومی LoadOptions: گزینههای مخصوص به فرمت برای ارسال صحیح لازم هستند.
آرایه controlPoints طول صفر دارد ممکن است مش بارگذاری شده باشد اما حاوی هندسه نیست (مثلاً یک گروه خالی در OBJ). از mesh.polygonCount برای بررسی قبل از تکرار رئوس استفاده کنید.
مصرف حافظه برای فایلهای بزرگ زیاد است بارگذاری از بافر با scene.openFromBuffer() حافظه اوج را کاهش نمیدهد: باید کل فایل تجزیه شود. برای فایلهای بزرگ (> 100 مگابایت)، اطمینان حاصل کنید که فرآیند Node.js شما حافظه heap کافی دارد: node --max-old-space-size=4096 yourScript.js.
خطاهای نوع: ’entity’ از نوع ‘unknown’ است این entity ویژگی بهصورت کلی تایپ شده است. تبدیل به any یا به یک کلاس خاص (Mesh, Camera,، و غیره) بسته به آنچه در صحنهتان انتظار دارید.
سوالات متداول (FAQ)
کدام فرمتها میتوانند با scene.open() بارگذاری شوند؟? OBJ، glTF 2.0 (.gltf + .bin)، GLB، STL، 3MF، FBX و COLLADA (.dae) همگی برای وارد کردن پشتیبانی میشوند. کلاس مربوط به هر فرمت را پاس دهید *LoadOptions کلاس برای هر فرمت.
آیا میتوانم فایلی را بدون مشخص کردن گزینهها بارگذاری کنم؟? بله. scene.open('model.glb') بدون گزینهها برای فرمتهایی که نیازی به پیکربندی خاص ندارند کار میکند. پاس کردن گزینهها برای OBJ توصیه میشود زیرا حل مواد به enableMaterials.
آیا بارگذاری به صورت ناهمزمان اجرا میشود؟? خیر. scene.open() و scene.openFromBuffer() همزمان هستند. آنها را در یک رشتهٔ کارگر بپیچید یا setImmediate اگر نیاز دارید حلقهٔ رویداد پاسخگو بماند.
آیا خروجی OBJ پشتیبانی میشود؟? بله. خروجی OBJ از طریق scene.save('output.obj'). فایل .mtl فایـل متریال بهصورت خودکار در کنار .obj فایل.
فایل .mtl هنگام بارگذاری OBJ در کجا انتظار میرود؟? بهطور پیشفرض، پارسر به دنبال .mtl فایلی که در داخل OBJ ارجاع داده شده است (mtllib دستورات) نسبت به مسیر پوشهٔ فایل OBJ. مطمئن شوید هر دو فایل در یک پوشه هستند.