Comment exporter des scènes 3D au format glTF/GLB en TypeScript

Aspose.3D FOSS prend en charge glTF 2.0 à la fois comme format d’importation et d’exportation. Le même objet Scene peut être peuplé à partir d’un fichier OBJ, FBX, STL ou autre source, puis écrit en .gltf (JSON + binaire externe) ou .glb (conteneur binaire unique) en définissant un drapeau sur GltfSaveOptions.

Guide étape par étape

npm install @aspose/3d

node --version   # must be >= 16.0.0

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

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

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

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

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;

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

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

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

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

Problèmes courants et solutions

Fichier de matériau OBJ introuvable après l’exportation
Lors de l’enregistrement au format OBJ via scene.save('output.obj'), le fichier de matériau .mtl est écrit automatiquement à côté du fichier .obj. Assurez‑vous que le répertoire de sortie est accessible en écriture et que les deux fichiers restent ensemble.

Output .glb is smaller than expected / meshes are missing
Si la scène chargée possède des nœuds sans entités (par exemple, des groupes vides provenant d’un OBJ), le GLB ne contiendra pas la géométrie de ces nœuds. Vérifiez que votre fichier d’entrée possède des données polygonales réelles en utilisant mesh.controlPoints.length > 0 avant d’enregistrer.

Impossible de trouver le module ‘@aspose/3d/formats/gltf’
Assurez‑vous d’utiliser Node.js 18+ et que @aspose/3d est installé dans le même node_modules que votre point d’entrée. Exécutez npm ls @aspose/3d pour confirmer que la version est 24.12.0 ou ultérieure.

GltfFormat.getInstance() renvoie undefined
Cela indique un problème de correspondance de version entre le package principal @aspose/3d et une version plus ancienne mise en cache. Supprimez node_modules et package-lock.json, puis exécutez à nouveau npm install.

Les textures sont manquantes dans le GLB de sortie
Assurez-vous que binaryMode = true est configuré pour produire un GLB autonome. Pour la sortie JSON glTF, les fichiers d’image de texture doivent être présents à côté du fichier de sortie puisqu’ils sont référencés par un chemin relatif.

Erreur de type : l’argument de type ‘GltfSaveOptions’ n’est pas assignable
Assurez-vous que Scene et GltfSaveOptions sont importés depuis la même instance du package installé. Les installations mixtes (globales + locales) peuvent provoquer des incompatibilités d’interface.

Foire aux questions (FAQ)

Quelle est la différence entre glTF et GLB ? glTF 2.0 JSON (.gltf) stocke le graphe de scène sous forme de fichier JSON lisible par l’homme avec des tampons .bin séparés et des fichiers image. GLB (.glb) regroupe tout dans un seul conteneur binaire. Définissez binaryMode = true pour GLB, false pour le glTF JSON.

Puis-je exporter une scène qui a été entièrement construite en code (sans fichier source) ?
Oui. Créez un Scene, ajoutez des objets Node, attachez Mesh ou d’autres entités, puis appelez scene.save(). La scène n’a pas besoin d’être issue d’un fichier chargé.

L’exportation glTF est-elle sans perte ?
Pour la géométrie et les transformations, oui. Les matériaux sont mappés aux propriétés de matériau PBR de glTF lorsque cela est possible. Les extensions de matériaux FBX propriétaires peuvent ne pas être parfaitement réversibles.

Puis-je exporter en STL ou 3MF à la place ?
Oui. Le modèle est identique ; importez les *SaveOptions et *Format.getInstance() du format correspondant :

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

scene.save() s’exécute-t-elle de manière asynchrone ?
Non. scene.save() est synchrone. Enveloppez‑la dans un thread de travail si vous devez éviter de bloquer la boucle d’événements lors de grosses exportations.

Quelles versions de Node.js sont prises en charge ?
Node.js 18, 20 et 22+. Node.js 16 et les versions antérieures ne sont pas prises en charge.

Voir aussi

• Comment charger des modèles 3D en TypeScript
• Référence API : GltfSaveOptions
• Référence API : GltfFormat
• Référence API : Scene
• npm : @aspose/3d