بارگذاری مدل‌های سه‌بعدی

@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 معمولاً ندارند.

مرجع گزینه‌های بارگذاری مخصوص فرمت

فرمتکلاس گزینه‌هامسیر وارداتگزینه‌های کلیدی
OBJObjLoadOptions@aspose/3d/formats/objenableMaterials, flipCoordinateSystem, scale, normalizeNormal
glTF / GLB(نیازی نیست)N/Aبه‌صورت خودکار شناسایی می‌شود؛ نیازی به کلاس گزینه‌ها نیست
STLStlLoadOptions@aspose/3d/formats/stl(در نسخهٔ فعلی گزینهٔ پیکربندی‌شدنی وجود ندارد)
FBXFbxLoadOptions@aspose/3d/formats/fbx(در نسخهٔ فعلی گزینهٔ پیکربندی‌شدنی وجود ندارد)
COLLADAColladaLoadOptions@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 در هر فریم است؛ آرایه کلیپ خالی خواهد بود

همچنین ببینید

 فارسی