Как да експортирате 3D сцени в glTF/GLB с TypeScript

Aspose.3D FOSS поддържа glTF 2.0 както като формат за импортиране, така и за експортиране. Същият Scene обект може да бъде попълнен от OBJ, FBX, STL или друг изходен файл и след това записан в .gltf (JSON + външен бинарен) или .glb (единен бинарен контейнер), като се зададе един флаг в GltfSaveOptions.

Ръководство стъпка по стъпка

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. При изход glTF JSON, файловете с изображения на текстурите трябва да присъстват до изходния файл, тъй като те се препращат чрез относителен път.

Грешка тип: Аргумент от тип ‘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 може да не се предават напълно без загуба.

Мога ли вместо това да експортирам в 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