Hur man exporterar 3D-scener till glTF/GLB i TypeScript

Aspose.3D FOSS stödjer glTF 2.0 både som import- och exportformat. Samma Scene objektet kan fyllas från en OBJ, FBX, STL eller annan källfil och sedan skrivas till .gltf (JSON + extern binär) eller .glb (enkel binärbehållare) genom att sätta en flagga på GltfSaveOptions.

Steg-för-steg-guide

Steg 1: Installera @aspose/3d

npm install @aspose/3d

Bekräfta att Node.js 18 eller senare är aktivt:

node --version   # must be >= 16.0.0

Steg 2: Importera Scene, GltfSaveOptions och GltfFormat

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

GltfFormat är formatbeskrivaren som skickas till scene.save(). GltfSaveOptions bär all exportkonfiguration.

Om du också laddar en källfil (t.ex. OBJ), importera motsvarande laddningsalternativ:

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

Steg 3: Bygg eller ladda en scen

Alternativ A: Ladda från en befintlig 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 scen programatiskt:

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

Steg 4: Konfigurera GltfSaveOptions

GltfSaveOptions styr utdataformatet och kodningsdetaljerna.

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;

Ytterligare alternativ du kan ställa in:

Egenskap	Typ	Standard	Effekt
`binaryMode`	`boolean`	`false`	`true` → GLB, `false` → glTF JSON
`flipTexCoordV`	`boolean`	`true`	Vänd UV:s vertikala axel för motorkompatibilitet

Steg 5: Spara med scene.save()

Skicka utdata-sökvägen, den GltfFormat beskrivaren och de konfigurerade alternativen:

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

För att producera en JSON .gltf fil istället:

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

Steg 6: Verifiera utdatafilen

Kontrollera att utdatafilen finns och har en icke‑noll storlek:

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

För en rundresa‑verifiering, ladda om GLB‑filen och inspektera antalet noder:

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

Vanliga problem och lösningar

OBJ-materialfil hittades inte efter export När du sparar till OBJ via scene.save('output.obj'), den .mtl materialfilen skrivs bredvid den .obj filen automatiskt. Se till att utdatamappen är skrivbar och att båda filerna hålls ihop.

Utdata .glb är mindre än förväntat / meshar saknas Om den inlästa scenen har noder utan entiteter (t.ex. tomma grupper från en OBJ), kommer GLB-filen inte att innehålla dessa noders geometri. Bekräfta att din indatafil har faktiska polygondata med hjälp av mesh.controlPoints.length > 0 innan du sparar.

Kan inte hitta modulen ‘@aspose/3d/formats/gltf’ Se till att du använder Node.js 18+ och att @aspose/3d är installerad i samma node_modules som din ingångspunkt. Kör npm ls @aspose/3d för att bekräfta att versionen är 24.12.0 eller senare.

GltfFormat.getInstance() returnerar undefined Detta indikerar en versionskonflikt mellan huvud @aspose/3d paketet och en cachad äldre version. Ta bort node_modules och package-lock.json, kör sedan npm install igen.

Texturer saknas i utdata-GLB Säkerställ binaryMode = true är inställd på att producera en självständig GLB. För glTF JSON-utdata måste texturfilbilder finnas bredvid utdatafilen eftersom de refereras via relativ sökväg.

Typfel: Argument av typen ‘GltfSaveOptions’ kan inte tilldelas Säkerställ att båda Scene och GltfSaveOptions importeras från samma installerade paketinstans. Blandade installationer (global + lokal) kan orsaka gränssnittsmissmatch.

Vanliga frågor (FAQ)

Vad är skillnaden mellan glTF och GLB? glTF 2.0 JSON (.gltf) lagrar scengrafen som en människoläsbar JSON-fil med separata .bin buffertar och bildfiler. GLB (.glb) paketerar allt i en enda binärbehållare. Ställ in binaryMode = true för GLB, false för JSON glTF.

Kan jag exportera en scen som byggts helt i kod (ingen källfil)? Ja. Skapa en Scene, lägg till Node objekt, fäst Mesh eller andra enheter, och sedan anropa scene.save(). Scenen behöver inte ha sitt ursprung i en inläst fil.

Är glTF-export förlustfri? För geometri och transformationer, ja. Material mappas till glTF PBR-materialegenskaper där det är möjligt. Proprietära FBX-materialtillägg kanske inte återges perfekt.

Kan jag exportera till STL eller 3MF istället? Ja. Mönstret är identiskt; importera motsvarande formats *SaveOptions och *Format.getInstance():

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

Kör scene.save() asynkront? Nej. scene.save() är synkron. Packa in det i en worker-tråd om du behöver undvika att blockera event loop under stora exporteringar.

Vilka Node.js-versioner stöds? Node.js 18, 20 och 22+. Node.js 16 och tidigare stöds inte.