Aspose.3D Lliure i de Codi Obert
TypeScript
Com exportar escenes 3D a glTF/GLB amb TypeScript

Com exportar escenes 3D a glTF/GLB amb TypeScript

Aspose.3D FOSS admet glTF 2.0 tant com a format d’importació com d’exportació. El mateix objecte Scene pot ser poblat des d’un fitxer OBJ, FBX, STL o un altre fitxer font i després escrit a .gltf (JSON + binari extern) o .glb (contenidor binari únic) establint una bandera a GltfSaveOptions.

Guia pas a pas

Pas 1: Instal·la @aspose/3d 

npm install @aspose/3d

Confirmeu que Node.js 18 o posterior està actiu:

node --version   # must be >= 16.0.0

Pas 2: Importa Scene, GltfSaveOptions i GltfFormat 

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

GltfFormat és el descriptor de format que es passa a scene.save(). GltfSaveOptions conté tota la configuració d’exportació.

Si també esteu carregant un fitxer d’origen (p. ex., OBJ), importeu les opcions de càrrega corresponents:

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

Pas 3: Crea o carrega una escena

Opció A: Carrega des d’un fitxer existent (conversió 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());

Opció B: Construeix una escena mínima de forma programàtica:

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

Pas 4: Configura GltfSaveOptions

GltfSaveOptions controla el format de sortida i els detalls de codificació.

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;

Opcions addicionals que podeu establir:

PropietatTipusPer defecteEfecte
binaryModebooleanfalsetrue → GLB, false → glTF JSON
flipTexCoordVbooleantrueCapgira l’eix vertical UV per a la compatibilitat del motor

Pas 5: Desa utilitzant scene.save()

Passeu el camí de sortida, el descriptor GltfFormat i les opcions configurades:

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

Per generar un fitxer JSON .gltf en canvi:

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

Pas 6: Verifiqueu el fitxer de sortida

Comproveu que el fitxer de sortida existeix i té una mida diferent de zero:

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

Per a una verificació d’anada i tornada, torneu a carregar el GLB i inspeccioneu el recompte de nodes:

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

Problemes comuns i solucions

Fitxer de material OBJ no trobat després de l’exportació
En desar a OBJ mitjançant scene.save('output.obj'), el fitxer de material .mtl s’escriu al costat del fitxer .obj automàticament. Assegureu-vos que el directori de sortida sigui gravable i que ambdós fitxers es mantinguin junts.

Sortida .glb és més petita del que s’esperava / falten malles
Si l’escena carregada té nodes sense entitats (p. ex., grups buits d’un OBJ), el GLB no contindrà la geometria d’aquests nodes. Confirmeu que el vostre fitxer d’entrada disposi de dades de polígon real utilitzant mesh.controlPoints.length > 0 abans de desar.

No es pot trobar el mòdul ‘@aspose/3d/formats/gltf’ Assegureu-vos que esteu a Node.js 18+ i que @aspose/3d està instal·lat al mateix node_modules que el vostre punt d’entrada. Executeu npm ls @aspose/3d per confirmar que la versió és 24.12.0 o posterior.

GltfFormat.getInstance() retorna undefined
Això indica una discrepància de versions entre el paquet principal @aspose/3d i una versió antiga emmagatzemada en caché. Suprimeix node_modules i package-lock.json, i després executa npm install de nou.

Les textures falten a la sortida GLB
Assegureu-vos que binaryMode = true estigui configurat per produir un GLB autocontingut. Per a la sortida JSON de glTF, els fitxers d’imatge de les textures han d’estar presents al costat del fitxer de sortida ja que es fan referència per via relativa.

Error de tipus: L’argument del tipus ‘GltfSaveOptions’ no és assignable
Assegureu-vos que tant Scene com GltfSaveOptions s’importin des de la mateixa instància del paquet instal·lat. Les instal·lacions mixtes (global + local) poden provocar desajustos d’interfície.

Preguntes freqüents (FAQ)

Quina és la diferència entre glTF i GLB?
glTF 2.0 JSON (.gltf) emmagatzema el gràfic de l’escena com un fitxer JSON llegible per humans amb buffers .bin separats i fitxers d’imatge. GLB (.glb) empaqueta tot en un únic contenidor binari. Defineix binaryMode = true per a GLB, false per a JSON glTF.

Puc exportar una escena que s’ha construït completament amb codi (sense fitxer font)?
Sí. Creeu un Scene, afegiu objectes Node, adjunteu Mesh o altres entitats, i després invoqueu scene.save(). L’escena no cal que provingués d’un fitxer carregat.

És l’exportació glTF sense pèrdues?
Per a geometria i transformacions, sí. Els materials es mapegen a les propietats de material PBR de glTF quan és possible. Les extensions de material propietàries de FBX poden no tornar a viatjar perfectament.

Puc exportar a STL o 3MF en canvi?
Sí. El patró és idèntic; importa els formats corresponents *SaveOptions i *Format.getInstance():

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

S’executa scene.save() de manera asíncrona?
No. scene.save() és sincrònic. Envolta’l en un fil de treball si necessites evitar bloquejar el bucle d’esdeveniments durant exportacions grans.

Quines versions de Node.js són compatibles? Node.js 18, 20 i 22+. Node.js 16 i versions anteriors no són compatibles.

Vegeu també

 Català