Jak exportovat 3D scény do glTF/GLB v TypeScriptu

Aspose.3D FOSS podporuje glTF 2.0 jako importní i exportní formát. Stejný Scene objekt může být naplněn z OBJ, FBX, STL nebo jiného zdrojového souboru a poté zapsán do .gltf (JSON + externí binární) nebo .glb (jediný binární kontejner) nastavením jednoho příznaku na GltfSaveOptions.

Návod krok za krokem

Krok 1: Nainstalujte @aspose/3d

npm install @aspose/3d

Ověřte, že je aktivní Node.js 18 nebo novější:

node --version   # must be >= 16.0.0

Krok 2: Importujte Scene, GltfSaveOptions a GltfFormat

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

GltfFormat je popisovač formátu předán do scene.save(). GltfSaveOptions nese veškerou konfiguraci exportu.

Pokud také načítáte zdrojový soubor (např. OBJ), importujte odpovídající možnosti načítání:

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

Krok 3: Vytvořte nebo načtěte scénu

Možnost A: Načíst z existujícího souboru (konverze OBJ → GLB):

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žnost B: Programově vytvořit minimální scénu:

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: Nakonfigurujte GltfSaveOptions

GltfSaveOptions řídí výstupní formát a podrobnosti kódování.

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;

Další možnosti, které můžete nastavit:

Vlastnost	Typ	Výchozí	Efekt
`binaryMode`	`boolean`	`false`	`true` → GLB, `false` → glTF JSON
`flipTexCoordV`	`boolean`	`true`	Převrátit vertikální osu UV pro kompatibilitu s enginem

Krok 5: Uložte pomocí scene.save()

Předávejte výstupní cestu, GltfFormat popisovač 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');

Pro vytvoření JSON .gltf soubor místo toho:

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

Krok 6: Ověřte výstupní soubor

Zkontrolujte, že výstupní soubor existuje a má nenulovou velikost:

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

Pro ověření celého cyklu načtěte GLB znovu a zkontrolujte počet uzlů:

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

Časté problémy a opravy

Soubor materiálu OBJ nebyl po exportu nalezen Při ukládání do OBJ pomocí scene.save('output.obj'), the .mtl soubor materiálu je zapsán vedle .obj soubor automaticky. Ujistěte se, že výstupní adresář je zapisovatelný a že oba soubory jsou uloženy společně.

Výstupní .glb je menší, než se očekávalo / chybí meshe Pokud načtená scéna obsahuje uzly bez entit (např. prázdné skupiny z OBJ), GLB nebude obsahovat geometrii těchto uzlů. Ověřte, že váš vstupní soubor obsahuje skutečná polygonová data pomocí mesh.controlPoints.length > 0 před uložením.

Nelze najít modul ‘@aspose/3d/formats/gltf’ Ujistěte se, že používáte Node.js 18+ a že @aspose/3d je nainstalován ve stejném node_modules jako váš vstupní bod. Spusťte npm ls @aspose/3d pro potvrzení, že verze je 24.12.0 nebo novější.

GltfFormat.getInstance() vrací undefined To naznačuje nesoulad verzí mezi hlavním @aspose/3d balíčkem a uloženou starší verzí. Odstraňte node_modules a package-lock.json, pak spusťte npm install znovu.

Textury chybí ve výstupním GLB Zajistěte binaryMode = true je nastaveno tak, aby vytvářelo samostatný GLB. Pro výstup glTF JSON musí být soubory s texturami přítomny vedle výstupního souboru, protože jsou odkazovány relativní cestou.

Chyba typu: Argument typu ‘GltfSaveOptions’ nelze přiřadit Zajistěte, aby oba Scene a GltfSaveOptions jsou importovány ze stejné nainstalované instance balíčku. Smíšené instalace (globální + lokální) mohou způsobit nesoulad rozhraní.

Často kladené otázky (FAQ)

Jaký je rozdíl mezi glTF a GLB? glTF 2.0 JSON (.gltf) ukládá graf scény jako čitelný JSON soubor s oddělenými .bin bufferami a soubory obrázků. GLB (.glb) balí vše do jediného binárního kontejneru. Nastavte binaryMode = true pro GLB, false pro JSON glTF.

Mohu exportovat scénu, která byla vytvořena výhradně v kódu (bez zdrojového souboru)? Ano. Vytvořte Scene, přidejte Node objekty, připojte Mesh nebo jiné entity, pak zavolejte scene.save(). Scéna nemusí pocházet z načteného souboru.

Je export do glTF bezztrátový? Pro geometrii a transformace, ano. Materiály jsou tam, kde je to možné, mapovány na vlastnosti materiálu glTF PBR. Proprietární rozšíření materiálů FBX nemusí být dokonale přenášena tam i zpět.

Mohu místo toho exportovat do STL nebo 3MF? Ano. Vzor je identický; importujte odpovídající 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);

Spouští se scene.save() asynchronně? Ne. scene.save() je synchronní. Zabalte jej do pracovního vlákna, pokud potřebujete zabránit blokování smyčky událostí během velkých exportů.

Jaké verze Node.js jsou podporovány? Node.js 18, 20 a 22+. Node.js 16 a starší nejsou podporovány.