Ako exportovať 3D scény do glTF/GLB v TypeScript

Aspose.3D FOSS podporuje glTF 2.0 ako formát na import aj export. Ten istý Scene objekt môže byť naplnený z OBJ, FBX, STL alebo iného zdrojového súboru a potom zapísaný do .gltf (JSON + externý binárny) alebo .glb (jediný binárny kontajner) nastavením jedného príznaku na GltfSaveOptions.

Návod krok za krokom

Krok 1: Nainštalujte @aspose/3d

npm install @aspose/3d

Potvrďte, že je aktívny Node.js 18 alebo novší:

node --version   # must be >= 16.0.0

Krok 2: Importovať Scene, GltfSaveOptions a GltfFormat

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

GltfFormat je popisovač formátu odovzdaný do scene.save(). GltfSaveOptions nesie všetku konfiguráciu exportu.

Ak načítavate aj zdrojový súbor (napr. OBJ), importujte zodpovedajúce možnosti načítania:

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

Krok 3: Vytvoriť alebo načítať scénu

Možnosť A: Načítať z existujúceho súboru (OBJ → GLB konverzia):

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());

Možnosť B: Vytvorte minimálnu scénu programovo:

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

Krok 4: Konfigurovať GltfSaveOptions

GltfSaveOptions riadi výstupný formát a podrobnosti o kódovaní.

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;

Ďalšie možnosti, ktoré môžete nastaviť:

Vlastnosť	Typ	Predvolené	Účinok
`binaryMode`	`boolean`	`false`	`true` → GLB, `false` → glTF JSON
`flipTexCoordV`	`boolean`	`true`	Preklopiť vertikálnu os UV pre kompatibilitu s enginom

Krok 5: Uložte pomocou scene.save()

Zadajte výstupnú cestu, deskriptor GltfFormat a nakonfigurované možnosti:

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');

Pre vytvorenie súboru JSON .gltf namiesto:

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

Krok 6: Overte výstupný súbor

Skontrolujte, či výstupný súbor existuje a má nenulovú veľkosť:

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');
}

Pre overenie round‑trip načítajte GLB znova a skontrolujte počet uzlov:

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`);

Bežné problémy a riešenia

OBJ material file not found after export Pri ukladaní do OBJ cez scene.save('output.obj') sa súbor materiálu .mtl automaticky zapíše vedľa súboru .obj. Uistite sa, že výstupný adresár je zapisovateľný a že oba súbory zostanú spolu.

Výstup .glb je menší, než sa očakáva / chýbajú siete
Ak načítaná scéna obsahuje uzly bez entít (napr. prázdne skupiny z OBJ), GLB nebude obsahovať geometriu týchto uzlov. Pred uložením potvrďte, že váš vstupný súbor obsahuje skutočné polygonové dáta pomocou mesh.controlPoints.length > 0.

Nemožno nájsť modul ‘@aspose/3d/formats/gltf’
Uistite sa, že používate Node.js 18+ a že @aspose/3d je nainštalovaný v rovnakom node_modules ako váš vstupný bod. Spustite npm ls @aspose/3d a overte, že verzia je 24.12.0 alebo novšia.

GltfFormat.getInstance() vracia undefined
Toto naznačuje nezhodu verzií medzi hlavnou @aspose/3d balíčkom a uloženou staršou verziou v cache. Odstráňte node_modules a package-lock.json, potom spustite npm install znova.

Textúry chýbajú vo výstupnom GLB
Uistite sa, že binaryMode = true je nastavený na vytvorenie samozahŕňajúceho GLB. Pre výstup glTF JSON musia byť súbory obrázkov textúr prítomné vedľa výstupného súboru, pretože sú odkazované relatívnou cestou.

Typová chyba: Argument typu ‘GltfSaveOptions’ nie je priraditeľný
Uistite sa, že Scene a GltfSaveOptions sú importované z rovnakej inštancie nainštalovaného balíka. Zmiešané inštalácie (globálne + lokálne) môžu spôsobiť nezhody rozhraní.

Často kladené otázky (FAQ)

Aký je rozdiel medzi glTF a GLB?
glTF 2.0 JSON (.gltf) ukladá graf scény ako ľudsky čitateľný JSON súbor s oddelenými .bin bufferami a súbormi obrázkov. GLB (.glb) balí všetko do jedného binárneho kontajnera. Nastavte binaryMode = true pre GLB, false pre JSON glTF.

Môžem exportovať scénu, ktorá bola postavená výlučne v kóde (bez zdrojového súboru)?
Áno. Vytvorte Scene, pridajte objekty Node, pripojte Mesh alebo ďalšie entity a potom zavolajte scene.save(). Scéna nemusí pochádzať z načítaného súboru.

Je export glTF bezstratový?
Pre geometriu a transformácie, áno. Materiály sú mapované na vlastnosti materiálu glTF PBR, kde je to možné. Proprietárne rozšírenia materiálu FBX nemusia dokonale prejsť späť.

Môžem exportovať do STL alebo 3MF namiesto toho? Áno. Vzor je identický; importujte príslušný formát *SaveOptions a *Format.getInstance():

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

Spúšťa sa scene.save() asynchrónne?
Nie. scene.save() je synchronný. Zabaľte ho do pracovného vlákna, ak potrebujete zabrániť blokovaniu slučky udalostí počas veľkých exportov.

Aké verzie Node.js sú podporované? Node.js 18, 20 a 22+. Node.js 16 a staršie nie sú podporované.