Suporte a Formatos 3D

Aspose.3D FOSS para TypeScript lê e grava sete principais formatos de arquivo 3D. A detecção de formato é automática ao carregar: a biblioteca inspeciona números mágicos binários, portanto você não precisa especificar o formato de origem. Classes de opções específicas de formato são importadas de subcaminhos do @aspose/3d pacote.

Formatos suportados

OBJ (Wavefront)

OBJ suporta tanto importação quanto exportação em @aspose/3d. Ao salvar como OBJ, a biblioteca de materiais (.mtl) é gravada automaticamente ao lado do .obj arquivo. Use ObjLoadOptions para controlar o carregamento de materiais e o comportamento do sistema de coordenadas.

Opções principais para ObjLoadOptions:

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

const scene = new Scene();
const opts = new ObjLoadOptions();
opts.enableMaterials = true;
opts.normalizeNormal = true;

scene.open('model.obj', opts);
console.log(`Loaded ${scene.rootNode.childNodes.length} top-level node(s)`);

Para converter um OBJ para qualquer formato gravável, carregue-o e chame scene.save() com a classe do formato de destino.

glTF e GLB

glTF 2.0 é o formato de intercâmbio recomendado para uso na web e em motores de jogo. A biblioteca usa o mesmo GltfFormat classe para ambos .gltf (JSON + sidecar) e .glb saída (binária, autônoma). Alternar entre elas com GltfSaveOptions.binaryMode.

Carregar glTF ou GLB:

import { Scene } from '@aspose/3d';
import { GltfLoadOptions } from '@aspose/3d/formats/gltf';

const scene = new Scene();
scene.open('model.gltf', new GltfLoadOptions());
// or
scene.open('model.glb');  // format detected from magic bytes

Exportar como JSON glTF (.gltf + .bin):

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

const scene = new Scene();
scene.open('input.fbx');

const opts = new GltfSaveOptions();
opts.binaryMode = false;  // produces output.gltf + output.bin
scene.save('output.gltf', GltfFormat.getInstance(), opts);

Exportar como GLB binário (.glb):

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

const scene = new Scene();
scene.open('input.obj');

const opts = new GltfSaveOptions();
opts.binaryMode = true;  // single self-contained file
scene.save('output.glb', GltfFormat.getInstance(), opts);

Usar binaryMode = true para entrega de ativos em produção. Um único .glb carrega mais rápido em navegadores e engines do que o par texto + binário separado.

STL

STL é um formato de malha triangulada usado em CAD e impressão 3D. Tanto STL binário quanto ASCII são suportados para entrada e saída. StlSaveOptions.binaryMode controla se a saída é binária (compacta) ou ASCII (legível por humanos).

import { Scene } from '@aspose/3d';
import { StlLoadOptions, StlSaveOptions } from '@aspose/3d/formats/stl';

const scene = new Scene();
scene.open('model.stl', new StlLoadOptions());

// Export as binary STL (default, compact)
const binaryOpts = new StlSaveOptions();
binaryOpts.binaryMode = true;
scene.save('output_binary.stl', binaryOpts);

// Export as ASCII STL (human-readable)
const asciiOpts = new StlSaveOptions();
asciiOpts.binaryMode = false;
scene.save('output_ascii.stl', asciiOpts);

STL armazena apenas geometria triangulada e normais de vértice. Dados de material e UV não são preservados no STL.

3MF (3D Manufacturing Format)

3MF is an XML-based format designed for additive manufacturing. It supports color and material metadata alongside geometry. Use it when exchanging files with 3D printing slicers or manufacturing workflows.

import { Scene } from '@aspose/3d';
import { ThreeMfSaveOptions } from '@aspose/3d/formats/3mf';

const scene = new Scene();
scene.open('model.3mf');

// Re-export as 3MF
scene.save('output.3mf', new ThreeMfSaveOptions());

3MF files are ZIP archives internally. The library handles archive creation and extraction automatically.

FBX

Aviso: classes de importação e exportação FBX (FbxImporter, FbxExporter) existem na biblioteca, mas a detecção automática do formato FBX é não está conectada em scene.open() ou scene.save(). Chamando scene.open('file.fbx') não invocará o importador FBX — o arquivo passará para a alternativa STL. Chamando scene.save('output.fbx', opts) não invocará o exportador FBX. A tabela de suporte a formatos acima marca o FBX como No* por esse motivo. Use GLB ou COLLADA para importação e exportação totalmente funcionais via scene.open() / scene.save().

COLLADA (DAE)

COLLADA é um formato de intercâmbio baseado em XML suportado por uma ampla gama de ferramentas DCC (Blender, Maya, Cinema 4D). A biblioteca usa o xmldom dependência para análise XML; ela é instalada automaticamente com npm install @aspose/3d.

import { Scene } from '@aspose/3d';
import { ColladaSaveOptions } from '@aspose/3d/formats/collada';

const scene = new Scene();
scene.open('model.dae');

// Re-export as COLLADA
const saveOpts = new ColladaSaveOptions();
scene.save('output.dae', saveOpts);

arquivos COLLADA podem conter metadados de escala de unidades (<unit> elemento). A biblioteca aplica a conversão de unidades automaticamente ao carregar.

Detecção Automática de Formato

Ao carregar a partir de um caminho de arquivo, a biblioteca tenta detectar o formato a partir de números mágicos binários antes de recorrer à extensão do arquivo. Isso significa que você pode carregar um arquivo GLB chamado .bin ou um arquivo STL chamado .model sem especificar o formato explicitamente.

Ao carregar de um Buffer com scene.openFromBuffer(), a detecção por número mágico é o mecanismo principal:

import { Scene } from '@aspose/3d';
import * as fs from 'fs';

const buffer = fs.readFileSync('model.glb');
const scene = new Scene();
scene.openFromBuffer(buffer);  // format detected from magic bytes: 'glTF'

console.log(`Root has ${scene.rootNode.childNodes.length} child node(s)`);

Formatos com números mágicos confiáveis: GLB (glTF), STL binário (cabeçalho de 80 bytes + contagem de triângulos), 3MF (ZIP magic PK). OBJ e COLLADA são baseados em texto e são detectados a partir da extensão do arquivo ou pela classe de opções que você passa.

Dicas

• OBJ suporta tanto importação quanto exportação: ao salvar como OBJ, o .mtl arquivo de material é escrito automaticamente ao lado do .obj arquivo.
• Use GLB para entrega web: o formato binário autônomo evita problemas de CORS com .bin sidecars e carrega mais rápido em renderizadores WebGL.
• Passe opções específicas de formato: genérico scene.open(path) funciona para a maioria dos formatos, mas passar a classe de opções do carregador habilita comportamentos específicos de formato, como carregamento de material OBJ ou normalização de coordenadas STL.
• xmldom é necessário para COLLADA: ele é instalado automaticamente. Não o adicione ao peerDependencies ou tente removê-lo; o leitor COLLADA o chama diretamente.

Problemas Comuns

Veja Também

• Recursos e Funcionalidades: grafo de cena, malha, materiais, animação e APIs de matemática.
• Grafo de Cena: construção e travessia da árvore de nós.
• Como Construir um Mesh 3D Programaticamente