Aspose.3D FOSS
TypeScript
Cum să exportați scene 3D în glTF/GLB în TypeScript

Cum să exportați scene 3D în glTF/GLB în TypeScript

Aspose.3D FOSS acceptă glTF 2.0 atât ca format de import, cât și de export. Același obiect Scene poate fi populat dintr-un fișier OBJ, FBX, STL sau alt fișier sursă și apoi scris în .gltf (JSON + binar extern) sau .glb (container binar unic) prin setarea unui singur flag pe GltfSaveOptions.

Ghid pas cu pas

Pasul 1: Instalați @aspose/3d 

npm install @aspose/3d

Confirmați că Node.js 18 sau o versiune ulterioară este activă:

node --version   # must be >= 16.0.0

Pasul 2: Importați Scene, GltfSaveOptions și GltfFormat 

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

GltfFormat este descriptorul de format transmis către scene.save(). GltfSaveOptions conține toate configurațiile de export.

Dacă încărcați și un fișier sursă (de exemplu, OBJ), importați opțiunile de încărcare corespunzătoare:

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

Pasul 3: Construiește sau încarcă o scenă

Opțiunea A: Încărcați dintr-un fișier existent (conversie 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());

Opțiunea B: Construiește o scenă minimală programatic:

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

Pasul 4: Configurați GltfSaveOptions

GltfSaveOptions controlează formatul de ieșire și detaliile de codare.

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;

Opțiuni suplimentare pe care le puteți seta:

ProprietateTipImplicitEfect
binaryModebooleanfalsetrue → GLB, false → glTF JSON
flipTexCoordVbooleantrueInversează axa verticală UV pentru compatibilitatea cu motorul

Pasul 5: Salvați utilizând scene.save()

Transmite calea de ieșire, descriptorul GltfFormat și opțiunile configurate:

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

Pentru a produce un fișier JSON .gltf în schimb:

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

Pasul 6: Verificați fișierul de ieșire

Verificați că fișierul de ieșire există și are o dimensiune diferită 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');
}

Pentru o verificare round‑trip, reîncărcați GLB‑ul și inspectaţi numărul de noduri:

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

Probleme comune și remedii

Fișierul material OBJ nu a fost găsit după export
Când salvați în format OBJ prin scene.save('output.obj'), fișierul material .mtl este scris automat alături de fișierul .obj. Asigurați-vă că directorul de ieșire este scriabil și că ambele fișiere sunt păstrate împreună.

Output .glb este mai mic decât se așteaptă / plasele lipsesc
Dacă scena încărcată are noduri fără entități (de exemplu, grupuri goale dintr-un OBJ), GLB-ul nu va conține geometria acelor noduri. Confirmați că fișierul de intrare conține date poligonale reale utilizând mesh.controlPoints.length > 0 înainte de a salva.

Nu se poate găsi modulul ‘@aspose/3d/formats/gltf’
Asigurați-vă că utilizați Node.js 18+ și că @aspose/3d este instalat în același node_modules cu punctul de intrare. Rulați npm ls @aspose/3d pentru a confirma că versiunea este 24.12.0 sau ulterioară.

GltfFormat.getInstance() returnează undefined
Acest lucru indică o nepotrivire de versiune între pachetul principal @aspose/3d și o versiune mai veche stocată în cache. Ștergeți node_modules și package-lock.json, apoi rulați din nou npm install.

Textures are missing in the output GLB
Asiguraţi-vă că binaryMode = true este setat să producă un GLB auto‑conţinut. Pentru ieşirea JSON glTF, fişierele de imagini ale texturilor trebuie să fie prezente alături de fişierul de ieşire, deoarece sunt referenţiate prin cale relativă.

Eroare de tip: Argumentul de tip ‘GltfSaveOptions’ nu poate fi atribuit
Asigurați-vă că atât Scene, cât și GltfSaveOptions sunt importate din aceeași instanță a pachetului instalat. Instalările mixte (global + local) pot cauza nepotriviri de interfață.

Întrebări frecvente (FAQ)

Care este diferența dintre glTF și GLB?
glTF 2.0 JSON (.gltf) stochează graficul scenei ca un fișier JSON ușor de citit, cu buffere .bin și fișiere de imagini separate. GLB (.glb) împachetează totul într-un singur container binar. Setează binaryMode = true pentru GLB, false pentru glTF JSON.

Pot exporta o scenă care a fost construită complet în cod (fără fișier sursă)?
Da. Creați un Scene, adăugați obiecte Node, atașați Mesh sau alte entități, apoi apelați scene.save(). Scena nu trebuie să provină dintr-un fișier încărcat.

Exportul glTF este fără pierderi?
Pentru geometrie și transformări, da. Materialele sunt mapate la proprietățile de material PBR ale glTF acolo unde este posibil. Extensiile de material proprietare FBX s-ar putea să nu facă un ciclu complet perfect.

Pot exporta în STL sau 3MF în schimb? Da. Modelul este identic; importați *SaveOptions și *Format.getInstance() ale formatului corespunzător:

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

Se execută scene.save() asincron?
Nu. scene.save() este sincron. Înfășurați-l într-un fir de lucru dacă trebuie să evitați blocarea buclei de evenimente în timpul exporturilor mari.

Ce versiuni Node.js sunt suportate? Node.js 18, 20 și 22+. Node.js 16 și versiunile anterioare nu sunt suportate.

Vezi și

 Română