بارگذاری مدلهای سهبعدی
@aspose/3d دو روش بارگذاری را بر روی Scene کلاس: open() برای بارگذاری مسیر‑فایل و openFromBuffer() برای دادههای در‑حافظه. تشخیص قالب بهصورت خودکار از اعداد جادویی باینری یا پسوند فایل انجام میشود، بنابراین بهندرت نیاز دارید قالب منبع را بهصورت صریح مشخص کنید.
بارگذاری از مسیر فایل
رشته مسیر فایل را به scene.open(). کتابخانه قالب را از پسوند فایل تشخیص میدهد و برای قالبهای باینری، از بایتهای جادویی:
import { Scene } from '@aspose/3d';
const scene = new Scene();
scene.open('model.fbx');
console.log(`Root children: ${scene.rootNode.childNodes.length}`);
console.log(`Animation clips: ${scene.animationClips.length}`);open() محتویات صحنه موجود را جایگزین میکند. اگر نیاز به بارگذاری چندین فایل دارید، نمونههای جداگانهای ایجاد کنید Scene نمونهها.
بارگذاری OBJ با مواد
فایلهای OBJ مواد را از طریق یک sidecar .mtl فایل. بارگذاری مواد است بهصورت پیشفرض فعال است (ObjLoadOptions.enableMaterials = true). عبور کنید ObjLoadOptions برای کنترل این گزینه و سایر گزینههای زمان بارگذاری:
import { Scene } from '@aspose/3d';
import { ObjLoadOptions } from '@aspose/3d/formats/obj';
const scene = new Scene();
const options = new ObjLoadOptions();
options.enableMaterials = true; // load the .mtl sidecar
options.flipCoordinateSystem = false; // keep original Y-up orientation
options.normalizeNormal = true; // fix degenerate normals
options.scale = 1.0; // unit scale multiplier
scene.open('character.obj', options);
// Inspect materials on the first node
const first = scene.rootNode.childNodes[0];
if (first) {
console.log(`Materials on ${first.name}: ${first.materials.length}`);
}بارگذاری از بافر
استفاده کنید openFromBuffer() زمانی که دادههای فایل قبلاً در حافظه هستند، برای مثال از یک درخواست HTTP، یک BLOB پایگاه داده، یا استخراج یک آرشیو zip. این کار از نوشتن روی دیسک جلوگیری میکند:
import { Scene } from '@aspose/3d';
import { ObjLoadOptions } from '@aspose/3d/formats/obj';
import * as fs from 'fs';
const buffer: Buffer = fs.readFileSync('model.obj');
const scene = new Scene();
const options = new ObjLoadOptions();
options.enableMaterials = true;
scene.openFromBuffer(buffer, options);
console.log(`Loaded ${scene.rootNode.childNodes.length} root nodes`);برای فرمتهای باینری (GLB، STL binary، 3MF)، کتابخانه بایتهای جادویی را از بافر میخواند تا فرمت را بهصورت خودکار تشخیص دهد، بنابراین میتوانید پاس کنید undefined بهعنوان آرگومان گزینهها:
import { Scene } from '@aspose/3d';
import * as fs from 'fs';
const glbBuffer: Buffer = fs.readFileSync('model.glb');
const scene = new Scene();
scene.openFromBuffer(glbBuffer); // format auto-detected from GLB magic bytes
بارگذاری از HTTP (Node.js 18+)
یک منبع ریموت را دریافت کنید و بدون دستکاری سیستم فایل بارگذاری کنید:
import { Scene } from '@aspose/3d';
async function loadFromUrl(url: string): Promise<Scene> {
const response = await fetch(url);
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const arrayBuffer = await response.arrayBuffer();
const buffer = Buffer.from(arrayBuffer);
const scene = new Scene();
scene.openFromBuffer(buffer);
return scene;
}
const scene = await loadFromUrl('https://example.com/model.glb');
console.log(`Loaded scene: ${scene.rootNode.childNodes.length} root nodes`);بازرسی صحنه بارگذاریشده
پس از بارگذاری، گراف صحنه را پیمایش کنید تا گرهها را فهرست کرده و هندسه را شناسایی کنید:
import { Scene, Mesh, Node } from '@aspose/3d';
const scene = new Scene();
scene.open('model.fbx');
function inspect(node: Node, depth: number = 0): void {
const indent = ' '.repeat(depth);
const entityType = node.entity ? node.entity.constructor.name : '(none)';
console.log(`${indent}${node.name} [${entityType}]`);
if (node.entity instanceof Mesh) {
const mesh = node.entity as Mesh;
console.log(`${indent} vertices: ${mesh.controlPoints.length}, polygons: ${mesh.polygonCount}`);
}
for (const child of node.childNodes) {
inspect(child, depth + 1);
}
}
inspect(scene.rootNode);خواندن متادیتای منبع
این assetInfo ویژگی متادیتای سطح فایل را نمایش میدهد:
import { Scene } from '@aspose/3d';
const scene = new Scene();
scene.open('model.fbx');
const info = scene.assetInfo;
if (info) {
console.log(`Creator: ${info.creator}`);
console.log(`Unit name: ${info.unitName}`);
console.log(`Unit scale: ${info.unitScaleFactor}`);
}همه فرمتها مقداردهی نمیشوند assetInfo. FBX و COLLADA دارای متادیتای غنی هستند؛ OBJ و STL معمولاً ندارند.
مرجع گزینههای بارگذاری مخصوص فرمت
| فرمت | کلاس گزینهها | مسیر واردات | گزینههای کلیدی |
|---|---|---|---|
| OBJ | ObjLoadOptions | @aspose/3d/formats/obj | enableMaterials, flipCoordinateSystem, scale, normalizeNormal |
| glTF / GLB | (نیازی نیست) | N/A | بهصورت خودکار شناسایی میشود؛ نیازی به کلاس گزینهها نیست |
| STL | StlLoadOptions | @aspose/3d/formats/stl | (در نسخهٔ فعلی گزینهٔ پیکربندیشدنی وجود ندارد) |
| FBX | FbxLoadOptions | @aspose/3d/formats/fbx | (در نسخهٔ فعلی گزینهٔ پیکربندیشدنی وجود ندارد) |
| COLLADA | ColladaLoadOptions | @aspose/3d/formats/collada | (بدون گزینههای قابل پیکربندی در نسخهٔ فعلی) |
| 3MF | (نیازی به هیچیک نیست) | N/A | تشخیص خودکار |
خطاهای متداول بارگذاری
| علائم | دلیل | رفع |
|---|---|---|
Error: Cannot find module '@aspose/3d/formats/obj' | moduleResolution تنظیم نشده به node | افزودن "moduleResolution": "node" به tsconfig.json |
| فهرست گره خالی پس از بارگذاری OBJ | .mtl sidecar موجود نیست یا enableMaterials تنظیم نشده | تنظیم options.enableMaterials = true و اطمینان حاصل کنید .mtl در همان پوشه است |
صحنه بارگذاری میشود اما rootNode.childNodes خالی است | فرمت از یک مش ریشهٔ واحد استفاده میکند، نه گرههای فرزند | دسترسی scene.rootNode.entity مستقیم |
openFromBuffer خطا میدهد با STL باینری | بافر بهدرستی برش داده نشد (بایتهای انتهایی گم شدهاند) | از کامل استفاده کنید readFileSync() خروجی بدون برش |
| آرایه کلیپهای انیمیشن پس از بارگذاری FBX خالی است | فایل FBX از baked transforms استفاده میکند، نه کلیپها | انیمیشن بهصورت baked در هر فریم است؛ آرایه کلیپ خالی خواهد بود |
همچنین ببینید
- ذخیرهسازی مدلهای 3D: گزینههای خروجی و
saveToBuffer - گراف صحنه: پیمایش و اصلاح سلسلهمراتب گرهها
- نمای کلی API: تمام کلاسها و شمارشها
- پشتیبانی از فرمتها: ماتریس کامل خواندن/نوشتن