Como exportar cenas 3D para glTF/GLB em TypeScript

Este guia mostra como exportar cenas 3D para o formato binário glTF 2.0 JSON e GLB usando Aspose.3D FOSS for TypeScript. Chame scene.save() com um descritivo ̋GltfFormat.getInstance (()) ∂ e um objeto ̨G ltfSaveOptions∂. Defina ゙GlttfSavetoops.binaryMode = true∂ para produzir um único contêiner de GLP, ou deixe-o no padrão ゚false∂ por um arquivo ⌒.gltf∂ com buffers binários separados.

Guia passo a passo

• Não, não.

Passo 1: Instalar @aspose/3d

Instalar o pacote a partir do registro npm usando o comando abaixo:

Confirmar que a versão Node.js instalada atende ao requisito mínimo de 18 ou mais recente:

node --version   # must be >= 16.0.0

Passo 2: Importar a cena, as opções de armazenamento e o formato da Gltf

Importar as classes necessárias para criar uma cena e configurar a exportação glTF:

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

GltfFormat é o descritivo de formato passado para ̋scene.save(). ∂GlttfSaveOptions carrega todas as configurações de exportação.

Se estiver a carregar também um ficheiro de origem (por exemplo, OBJ), importa as opções de carga correspondentes:

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

Passo 3: Criar ou carregar uma cena

Opção A: Carregar a partir de um ficheiro existente (conversão 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ção B: Construir uma cena mínima programaticamente.

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

Passo 4: Configurar as opções de armazenamento do GltfSave

Criar uma instância GltfSaveOptions para configurar o formato de saída e os detalhes da codificação para a exportação:

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ções adicionais que pode definir:

Passo 5: Salvar usando scene.save (s)

Passar o caminho de saída, o descritivo GltfFormat e as opções configuradas:

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

Para produzir um ficheiro JSON .gltf com buffers binários separados em vez de uma única GLB:

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

Passo 6: Verificar o ficheiro de saída

Verifique se o ficheiro de saída existe e tem um tamanho diferente do 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');
}

Para uma verificação de ida e volta, recarregar o GLB e inspecionar a contagem dos nós:

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

• Não, não.

Problemas comuns e soluções

Arquivo de material OBJ não encontrado após a exportação Quando o arquibo de materiais .mtl é salvo no OB J através do link scene.save(‘output.obj’)`, ele será automaticamente escrito ao lado do arquivos obj’).

Output .glb é menor do que o esperado / faltavam malhas Se a cena carregada tiver nós sem entidades (por exemplo, grupos vazios de um OBJ), esses nós não produzem geometria na saída GLB. Confirme seu arquivo de entrada tem dados polígonos reais usando `mesh.controlPoints.length > 0 Before saving.

Erro de resolução do módulo para “@aspose/3d/formats/gltf” Certifique-se que você está no Node.js 18+ e que @ aspose / 3d esteja instalado no mesmo node_modules` como seu ponto de entrada. Execute o @aspare/3Dヽs para confirmar a versão é 24.12.0 ou posterior.

GltfFormat.getInstance() retorna undefined Isto indica uma incompatibilidade de versão entre o principal pacote @aspose/3d e um cache mais antigo. Elimine os módulos ̋node_modules, ∂package-lock.json⌒ e execute novamente a instalação do ̨npm.

As texturas estão ausentes no GLB de saída Certifique-se que binaryMode = true é definido para produzir um GDB autocontido. Para a saída JSON glTF, os arquivos de imagem de textura devem estar presentes ao lado do arquivo de produção, uma vez que são referenciados por caminho relativo.

Erro de tipo TypeScript no argumento GltfSaveOptions Certifique-se que tanto Scene como ̋GltfSavetoopções` sejam importados da mesma instância do pacote instalado. Instalações mistas (global + local) podem causar desajustes na interface.

Perguntas Frequentes (FAQ)

Qual a diferença entre glTF e GLB? glTP 2.0 JSON (.gltf) armazena o gráfico de cena como um arquivo Json legível por humanos com buffers separados .bin e arquivos de imagem. O GLP (゚.glob`), empacotado em um único container binário, define ̋binaryMode = true⌒ para GLMB, ∂false⌒ Para JSn gltp.

Posso exportar uma cena que foi construída inteiramente em código (sem arquivo de origem)? Sim. Crie um Scene, adicione objetos do ̋Node∂, anexe ゙Mesh⌒ ou outras entidades e depois ligue para ゚scene.save()`. A cena não precisa ser originada a partir de um arquivos carregados.

A exportação glTF é sem perdas? Para geometria e transformações, sim. Os materiais são mapeados para propriedades de material PBR glTPF quando possível. As extensões proprietárias do material FBX podem perder a fidelidade durante a conversão.

Posso exportar para STL ou 3MF em vez disso? Sim. O padrão é idêntico; importa o formato correspondente *SaveOptions e ゚*Format.getInstance()⌒:

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

O scene.save funciona de forma assíncrona? Não. `scene. save (s) ̋ é sincrono. Enrole-o em um fio do trabalhador se precisar evitar bloquear o ciclo de eventos durante grandes exportações.

Que versões do Node.js são suportadas? Node .js 18, 20 e 22+. Node .js 16 ou anteriores não são apoiados.

Ver também:

• Como carregar modelos 3D em TypeScript
• Referência da API: GltfSaveOptions
• Referência da API: GltfFormat
• Referência API: Scene
• npm: @aspose/3d
• Objectivo 3D Base de conhecimentos da empresa