نحوه استخراج صحنه‌های سه‌بعدی به فرمت glTF/GLB در TypeScript

Aspose.3D FOSS از glTF 2.0 به عنوان فرمت واردات و صادرات پشتیبانی می‌کند. همان شیء Scene می‌تواند از یک فایل OBJ، FBX، STL یا سایر فایل‌های منبع پر شود و سپس با تنظیم یک پرچم بر روی GltfSaveOptions به .gltf (JSON + باینری خارجی) یا .glb (کانتینر باینری تک) نوشته شود.

راهنمای گام به گام

npm install @aspose/3d

node --version   # must be >= 16.0.0

import { Scene } from '@aspose/3d';
import { GltfSaveOptions, GltfFormat } from '@aspose/3d/formats/gltf';

import { ObjLoadOptions } from '@aspose/3d/formats/obj';

import { Scene } from '@aspose/3d';
import { ObjLoadOptions } from '@aspose/3d/formats/obj';
import { GltfSaveOptions, GltfFormat } from '@aspose/3d/formats/gltf';

const scene = new Scene();
scene.open('model.obj', new ObjLoadOptions());

import { Scene, Node, Mesh } from '@aspose/3d';
import { GltfSaveOptions, GltfFormat } from '@aspose/3d/formats/gltf';

const scene = new Scene();
const childNode = new Node('cube');
scene.rootNode.addChildNode(childNode);
// Attach geometry to childNode as needed

const saveOpts = new GltfSaveOptions();

// Set to true for a single binary .glb file
// Set to false (default) for JSON .gltf + separate .bin
saveOpts.binaryMode = true;

import { Scene } from '@aspose/3d';
import { ObjLoadOptions } from '@aspose/3d/formats/obj';
import { GltfSaveOptions, GltfFormat } from '@aspose/3d/formats/gltf';

const scene = new Scene();
scene.open('model.obj', new ObjLoadOptions());

const saveOpts = new GltfSaveOptions();
saveOpts.binaryMode = true;   // produce .glb

scene.save('output.glb', GltfFormat.getInstance(), saveOpts);
console.log('Converted to GLB successfully');

saveOpts.binaryMode = false;
scene.save('output.gltf', GltfFormat.getInstance(), saveOpts);
console.log('Exported to glTF JSON successfully');

import * as fs from 'fs';

const outputPath = 'output.glb';
const stats = fs.statSync(outputPath);
console.log(`Output file size: ${stats.size} bytes`);

if (stats.size === 0) {
    throw new Error('Export produced an empty file: check scene content');
}

import { Scene } from '@aspose/3d';
import { GltfLoadOptions } from '@aspose/3d/formats/gltf';

const verify = new Scene();
verify.open('output.glb', new GltfLoadOptions());

let nodeCount = 0;
function countNodes(node: any): void {
    nodeCount++;
    for (const child of node.childNodes) countNodes(child);
}
countNodes(verify.rootNode);

console.log(`Round-trip verification: ${nodeCount} node(s) in output`);

مسائل رایج و راه‌حل‌ها

فایل متریال OBJ پس از خروجی یافت نشد
هنگام ذخیره به OBJ از طریق scene.save('output.obj')، فایل متریال .mtl به‌صورت خودکار در کنار فایل .obj نوشته می‌شود. اطمینان حاصل کنید که پوشه خروجی قابل نوشتن باشد و هر دو فایل همراه هم نگه داشته شوند.

خروجی .glb کوچکتر از انتظار است / مش‌ها گم شده‌اند
اگر صحنه بارگذاری‌شده گره‌هایی بدون موجودیت داشته باشد (مثلاً گروه‌های خالی از یک OBJ)، GLB شامل هندسهٔ آن گره‌ها نخواهد بود. قبل از ذخیره‌سازی، با استفاده از mesh.controlPoints.length > 0 تأیید کنید که فایل ورودی شما داده‌های چندضلعی واقعی دارد.

ماژول ‘@aspose/3d/formats/gltf’ یافت نشد
اطمینان حاصل کنید که از Node.js 18+ استفاده می‌کنید و @aspose/3d در همان node_modules که نقطه ورود شماست نصب شده باشد. npm ls @aspose/3d را اجرا کنید تا نسخه 24.12.0 یا بالاتر را تأیید کنید.

GltfFormat.getInstance() مقدار undefined برمی‌گرداند
این نشان‌دهنده عدم تطابق نسخه بین بسته اصلی @aspose/3d و یک نسخهٔ کش‌شدهٔ قدیمی است. node_modules و package-lock.json را حذف کنید، سپس npm install را دوباره اجرا کنید.

بافت‌ها در GLB خروجی گم شده‌اند
اطمینان حاصل کنید که binaryMode = true برای تولید یک GLB خودمحافظ تنظیم شده باشد. برای خروجی JSON glTF، فایل‌های تصویر بافت باید در کنار فایل خروجی موجود باشند زیرا به‌صورت مسیر نسبی ارجاع داده می‌شوند.

خطای نوع: آرگومان از نوع ‘GltfSaveOptions’ قابل انتساب نیست
اطمینان حاصل کنید که هر دو Scene و GltfSaveOptions از یک نمونه بسته نصب‌شده وارد شده‌اند. نصب‌های ترکیبی (سراسری + محلی) می‌توانند باعث عدم تطابق رابط‌ها شوند.

سوالات متداول (FAQ)

تفاوت glTF و GLB چیست؟
glTF 2.0 JSON (.gltf) صحنه گراف را به عنوان یک فایل JSON قابل خواندن برای انسان ذخیره می‌کند با بافرهای .bin جداگانه و فایل‌های تصویر. GLB (.glb) همه چیز را در یک محفظه باینری واحد بسته‌بندی می‌کند. binaryMode = true را برای GLB تنظیم کنید، false را برای JSON glTF.

آیا می‌توانم صحنه‌ای که کاملاً با کد ساخته شده است (بدون فایل منبع) را صادر کنم؟
بله. یک Scene ایجاد کنید، اشیاء Node را اضافه کنید، Mesh یا سایر موجودیت‌ها را متصل کنید، سپس scene.save() را فراخوانی کنید. صحنه نیازی به منبع از یک فایل بارگذاری‌شده ندارد.

آیا خروجی glTF بدون افت کیفیت است؟
برای هندسه و تبدیلات، بله. مواد به ویژگی‌های ماده PBR glTF در صورت امکان نگاشته می‌شوند. افزونه‌های مواد مالکیتی FBX ممکن است به‌صورت کامل round‑trip نباشند.

آیا می‌توانم به جای آن به STL یا 3MF صادر کنم؟
بله. الگو یکسان است؛ قالب‌های مربوطه *SaveOptions و *Format.getInstance() را وارد کنید:

import { StlSaveOptions, StlFormat } from '@aspose/3d/formats/stl';
const opts = new StlSaveOptions();
scene.save('output.stl', StlFormat.getInstance(), opts);

آیا scene.save() به صورت ناهمزمان اجرا می‌شود؟
خیر. scene.save() به صورت همزمان است. اگر نیاز دارید تا از مسدود شدن حلقهٔ رویداد در هنگام صادرات بزرگ جلوگیری کنید، آن را در یک رشتهٔ کارگر بپیچید.

کدام نسخه‌های Node.js پشتیبانی می‌شوند؟ Node.js 18، 20 و 22+. Node.js 16 و نسخه‌های قبلی پشتیبانی نمی‌شوند.

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

• چگونه مدل‌های 3D را در TypeScript بارگذاری کنیم
• مرجع API: GltfSaveOptions
• مرجع API: GltfFormat
• مرجع API: Scene
• npm: @aspose/3d