Hvordan eksportere 3D‑scener til glTF/GLB i TypeScript

Aspose.3D FOSS støtter glTF 2.0 både som import- og eksportformat. Det samme Scene‑objektet kan fylles fra en OBJ, FBX, STL eller annen kildefil og deretter skrives til .gltf (JSON + ekstern binær) eller .glb (enkelt binærbeholder) ved å sette ett flagg på GltfSaveOptions.

Steg-for-steg guide

Trinn 1: Installer @aspose/3d

npm install @aspose/3d

Bekreft at Node.js 18 eller nyere er aktiv:

node --version   # must be >= 16.0.0

Trinn 2: Importer Scene, GltfSaveOptions og GltfFormat

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

GltfFormat er formatbeskrivelsen som sendes til scene.save(). GltfSaveOptions inneholder all eksportkonfigurasjon.

Hvis du også laster inn en kildefil (f.eks. OBJ), importer de tilsvarende lastalternativene:

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

Steg 3: Bygg eller last inn en scene

Alternativ A: Last inn fra en eksisterende fil (OBJ → GLB‑konvertering):

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

Alternativ B: Bygg en minimal scene programmatisk:

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

Trinn 4: Konfigurer GltfSaveOptions

GltfSaveOptions kontrollerer utdataformatet og kodingsdetaljene.

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;

Ytterligere alternativer du kan angi:

Egenskap	Type	Standard	Effekt
`binaryMode`	`boolean`	`false`	`true` → GLB, `false` → glTF JSON
`flipTexCoordV`	`boolean`	`true`	Vend UV-vertikalaksen for motor-kompatibilitet

Steg 5: Lagre ved å bruke scene.save()

Oppgi utdata‑stien, GltfFormat‑beskrivelsen og de konfigurerte alternativene:

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

For å produsere en JSON .gltf-fil i stedet:

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

Steg 6: Verifiser utdatafilen

Sjekk at utdatafilen finnes og har en størrelse som er større enn null:

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

For en rundturverifisering, last inn GLB på nytt og inspiser nodetellingen:

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

Vanlige problemer og løsninger

OBJ-materialfil ikke funnet etter eksport
Når du lagrer til OBJ via scene.save('output.obj'), blir .mtl-materialfilen skrevet ved siden av .obj-filen automatisk. Sørg for at målmappe er skrivbar og at begge filene holdes sammen.

Output .glb is smaller than expected / meshes are missing
Hvis den innlastede scenen har noder uten enheter (f.eks. tomme grupper fra en OBJ), vil GLB-filen ikke inneholde geometrien til disse nodene. Bekreft at inndatafilen har faktiske polygondata ved å bruke mesh.controlPoints.length > 0 før du lagrer.

Kan ikke finne modulen ‘@aspose/3d/formats/gltf’ Sørg for at du bruker Node.js 18+ og at @aspose/3d er installert i samme node_modules som inngangspunktet ditt. Kjør npm ls @aspose/3d for å bekrefte at versjonen er 24.12.0 eller nyere.

GltfFormat.getInstance() returns undefined
Dette indikerer en versjonskonflikt mellom hovedpakken @aspose/3d og en cachet eldre versjon. Slett node_modules og package-lock.json, og kjør deretter npm install på nytt.

Teksturer mangler i den genererte GLB
Sørg for at binaryMode = true er satt til å produsere en selvstendig GLB. For glTF JSON‑utdata må teksturbildefiler være til stede ved siden av utdatafilen siden de refereres via relativ sti.

Typefeil: Argument av typen ‘GltfSaveOptions’ kan ikke tilordnes
Sørg for at både Scene og GltfSaveOptions er importert fra samme installerte pakkeinstans. Blandet installasjoner (global + lokal) kan forårsake grensesnittmismatch.

Ofte stilte spørsmål (FAQ)

Hva er forskjellen mellom glTF og GLB?
glTF 2.0 JSON (.gltf) lagrer scene‑grafen som en menneskelig lesbar JSON‑fil med separate .bin‑buffere og bildefiler. GLB (.glb) pakker alt inn i en enkelt binær beholder. Sett binaryMode = true for GLB, false for JSON glTF.

Kan jeg eksportere en scene som ble bygget helt i kode (ingen kildefil)? Ja. Opprett en Scene, legg til Node‑objekter, fest Mesh eller andre enheter, og kall deretter scene.save(). Scenen trenger ikke å ha sitt opphav fra en lastet fil.

Er glTF-eksport tapsfri? For geometri og transformasjoner, ja. Materialer blir kartlagt til glTF PBR-materialegenskaper der det er mulig. Proprietære FBX-materialutvidelser kan muligens ikke gå gjennom en round‑trip helt perfekt.

Kan jeg eksportere til STL eller 3MF i stedet? Ja. Mønsteret er identisk; importer den tilsvarende formatets *SaveOptions og *Format.getInstance():

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

Kjører scene.save() asynkront?
Nei. scene.save() er synkron. Pakk den inn i en worker‑tråd hvis du trenger å unngå å blokkere hendelsesløkken under store eksporteringer.

Hvilke Node.js‑versjoner støttes? Node.js 18, 20, og 22+. Node.js 16 og tidligere støttes ikke.