Hoe 3D‑scènes exporteren naar glTF/GLB in TypeScript

Aspose.3D FOSS ondersteunt glTF 2.0 zowel als import‑ als exportformaat. Hetzelfde Scene‑object kan worden gevuld vanuit een OBJ, FBX, STL of ander bronbestand en vervolgens worden weggeschreven naar .gltf (JSON + externe binaire) of .glb (enkele binaire container) door één vlag in te stellen op GltfSaveOptions.

Stapsgewijze handleiding

Stap 1: Installeer @aspose/3d

npm install @aspose/3d

Bevestig dat Node.js 18 of hoger actief is:

node --version   # must be >= 16.0.0

Stap 2: Import Scene, GltfSaveOptions en GltfFormat

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

GltfFormat is de formaatdescriptor die wordt doorgegeven aan scene.save(). GltfSaveOptions bevat alle exportconfiguratie.

Als u ook een bronbestand laadt (bijv. OBJ), importeer dan de bijbehorende laadopties:

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

Stap 3: Bouw of laad een scène

Optie A: Laden vanuit een bestaand bestand (OBJ → GLB-conversie):

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

Optie B: Bouw een minimale scène programmatisch:

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

Stap 4: Configureer GltfSaveOptions

GltfSaveOptions regelt het uitvoerformaat en de coderingsdetails.

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;

Aanvullende opties die u kunt instellen:

Eigenschap	Type	Standaard	Effect
`binaryMode`	`boolean`	`false`	`true` → GLB, `false` → glTF JSON
`flipTexCoordV`	`boolean`	`true`	Draai de verticale UV-as om voor engine-compatibiliteit

Stap 5: Opslaan met scene.save()

Geef het uitvoerpad, de GltfFormat descriptor en de geconfigureerde opties door:

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

Om in plaats daarvan een JSON .gltf-bestand te produceren:

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

Stap 6: Verifieer het uitvoerbestand

Controleer of het uitvoerbestand bestaat en een niet‑nul grootte heeft:

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

Voor een round-trip verificatie, laad de GLB opnieuw en inspecteer het aantal knooppunten:

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

Veelvoorkomende problemen en oplossingen

OBJ-materiaalbestand niet gevonden na export
Bij het opslaan naar OBJ via scene.save('output.obj'), wordt het .mtl‑materiaalbestand automatisch naast het .obj‑bestand geschreven. Zorg ervoor dat de uitvoermap beschrijfbaar is en dat beide bestanden samen worden bewaard.

Uitvoer .glb is kleiner dan verwacht / meshes ontbreken
Als de geladen scène knooppunten zonder entiteiten bevat (bijv. lege groepen van een OBJ), zal de GLB de geometrie van die knooppunten niet bevatten. Controleer of uw invoerbestand daadwerkelijke polygongegevens bevat met mesh.controlPoints.length > 0 voordat u opslaat.

Kan module ‘@aspose/3d/formats/gltf’ niet vinden
Zorg ervoor dat u Node.js 18+ gebruikt en dat @aspose/3d is geïnstalleerd in dezelfde node_modules als uw entry point. Voer npm ls @aspose/3d uit om te bevestigen dat de versie 24.12.0 of hoger is.

GltfFormat.getInstance() retourneert undefined
Dit duidt op een versieconflict tussen het hoofd @aspose/3d-pakket en een gecachte oudere versie. Verwijder node_modules en package-lock.json, en voer vervolgens npm install opnieuw uit.

Texturen ontbreken in de uitvoer‑GLB
Zorg ervoor dat binaryMode = true is ingesteld om een zelfvoorzienende GLB te produceren. Voor glTF JSON‑uitvoer moeten texture‑afbeeldingsbestanden aanwezig zijn naast het uitvoerbestand, omdat ze via een relatief pad worden gerefereerd.

Typefout: Argument van type ‘GltfSaveOptions’ is niet toewijsbaar
Zorg ervoor dat zowel Scene als GltfSaveOptions uit dezelfde geïnstalleerde pakketinstantie worden geïmporteerd. Gemengde installaties (globaal + lokaal) kunnen interface‑mismatches veroorzaken.

Veelgestelde vragen (FAQ)

Wat is het verschil tussen glTF en GLB?
glTF 2.0 JSON (.gltf) slaat de scènegrafiek op als een menselijk leesbaar JSON‑bestand met afzonderlijke .bin‑buffers en afbeeldingsbestanden. GLB (.glb) verpakt alles in één binaire container. Stel binaryMode = true in voor GLB, false voor JSON glTF.

Kan ik een scène exporteren die volledig in code is opgebouwd (geen bronbestand)?
Ja. Maak een Scene, voeg Node objecten toe, koppel Mesh of andere entiteiten, en roep vervolgens scene.save() aan. De scène hoeft niet afkomstig te zijn van een geladen bestand.

Is glTF-export verliesloos?
Voor geometrie en transformaties, ja. Materialen worden, waar mogelijk, gemapt naar glTF PBR‑materiaal‑eigenschappen. Propriëtaire FBX‑materiaalextensies kunnen mogelijk niet perfect round‑trippen.

Kan ik in plaats daarvan exporteren naar STL of 3MF? Ja. Het patroon is identiek; importeer de overeenkomstige formaten *SaveOptions en *Format.getInstance():

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

Werkt scene.save() asynchroon?
Nee. scene.save() is synchroon. Plaats het in een worker thread als je de event loop wilt vermijden tijdens grote exports.

Welke Node.js‑versies worden ondersteund?
Node.js 18, 20 en 22+. Node.js 16 en eerdere versies worden niet ondersteund.