Как экспортировать 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) упаковывает всё в один бинарный контейнер. Set binaryMode = true для GLB, false для JSON glTF.

Могу ли я экспортировать сцену, построенную полностью в коде (без исходного файла)? Да. Создайте Scene, добавьте Node объекты, присоедините Mesh или другие сущности, затем вызвать scene.save().Сцена не обязана исходить из загруженного файла.

Экспорт glTF без потерь? Для геометрии и трансформаций — да. Материалы по возможности сопоставляются со свойствами материалов glTF PBR. Проприетарные расширения материалов 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() является синхронным. Оберните его в worker thread, если вам нужно избежать блокировки event loop при больших экспортах.

Какие версии Node.js поддерживаются? Node.js 18, 20 и 22+. Node.js 16 и более ранние версии не поддерживаются.

См. также

• Как загрузить 3D‑модели в TypeScript
• Справочник API: GltfSaveOptions
• Справочник API: GltfFormat
• Справочник API: Scene
• npm: @aspose/3d