Convertendo entre formatos 3D em TypeScript com Aspose.3D FOSS

Desenvolvedores Node.js que trabalham com conteúdo 3D frequentemente precisam converter entre formatos: uma ferramenta de design exporta OBJ, um renderizador web espera GLB, uma impressora 3D requer STL e uma cadeia de produção utiliza 3MF. Manipular essas conversões com uma única API consistente reduz o número de ferramentas externas em um pipeline e mantém a lógica de conversão dentro do código da aplicação, onde pode ser testada e versionada.

O @aspose/3d O pacote (v24.12.0, licença MIT) fornece uma API TypeScript-first para leitura e gravação de todos os principais formatos 3D no Node.js. Este guia percorre os fluxos de conversão mais comuns.

Instalação

npm install @aspose/3d

Requisitos: Node.js 18, 20 ou 22; TypeScript 5.0 ou superior. A única dependência em tempo de execução é xmldom.

Formatos Compatíveis

A tabela abaixo lista os formatos abordados neste guia e seu suporte de leitura/gravação.

OBJ suporta tanto importação quanto exportação. Carregue com scene.open() e salve com scene.save('output.obj'), ou converta para qualquer outro formato suportado, como glTF, STL ou 3MF.

OBJ para GLB (Entrega Web)

Converter OBJ para glTF binário (GLB) é o fluxo de trabalho web mais comum. GLB é um pacote binário autônomo: texturas, geometria e metadados em um único arquivo, o que o torna eficiente para entrega via HTTP e carregamento direto por Three.js, Babylon.js e model-viewer.

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

function convertObjToGlb(inputPath: string, outputPath: string): void {
  const scene = new Scene();
  scene.open(inputPath);
  scene.save(outputPath);  // extension '.glb' selects binary GLB format
  console.log(`Converted ${inputPath} -> ${outputPath}`);
}

convertObjToGlb('model.obj', 'model.glb');

O formato de saída é inferido a partir da extensão do arquivo. Use .glb para GLB binário ou .gltf para o JSON separado + .bin layout.

OBJ para STL (Preparação para Impressão 3D)

STL é a língua franca da impressão 3D FDM e SLA. Fatiadores como PrusaSlicer, Bambu Studio e Chitubox aceitam STL. Converter de OBJ para STL é simples porque ambos os formatos armazenam malhas de triângulos.

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

function convertObjToStl(inputPath: string, outputPath: string): void {
  const scene = new Scene();
  scene.open(inputPath);
  scene.save(outputPath);  // extension '.stl' selects STL format
  console.log(`STL written to ${outputPath}`);
}

convertObjToStl('part.obj', 'part.stl');

STL não armazena cor, material ou dados UV. Se o seu arquivo OBJ usar grupos de material, essas informações são descartadas durante a exportação. Para formatos de impressão que preservam cores, considere 3MF em vez disso (veja abaixo).

STL para glTF (Scanner e CAD para Web)

Scanners de luz estruturada e exportadores CAD paramétricos normalmente geram STL. Converter para glTF torna a geometria acessível em visualizadores baseados na web e plataformas de AR sem a necessidade de uma etapa de renderização no servidor.

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

function convertStlToGltf(inputPath: string, outputPath: string): void {
  const scene = new Scene();
  scene.open(inputPath);
  // extension '.gltf' saves as JSON + .bin sidecar
  scene.save(outputPath);
  console.log(`glTF written to ${outputPath}`);
}

convertStlToGltf('scan_output.stl', 'scan_output.gltf');

Como o STL não contém informações de material ou textura, o arquivo glTF resultante conterá apenas a geometria. Você pode anexar materiais programaticamente aos nós da cena após o carregamento, se necessário.

3MF to glTF (Manufacturing to Visualization)

O Formato 3D de Fabricação (3MF) está sendo cada vez mais usado em fluxos de trabalho de manufatura aditiva porque armazena cor, materiais, árvores de componentes e metadados de impressão junto com a geometria. Converter 3MF para glTF permite visualização downstream em ferramentas web enquanto preserva a estrutura da cena.

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

function convert3mfToGlb(inputPath: string, outputPath: string): void {
  const scene = new Scene();
  scene.open(inputPath);
  scene.save(outputPath);  // extension '.glb' selects binary GLB format
  console.log(`3MF -> GLB: ${outputPath}`);
}

convert3mfToGlb('assembly.3mf', 'assembly.glb');

3MF files often contain multi-component assemblies. The scene graph produced by scene.open() preserva a hierarquia de componentes em scene.rootNode.childNodes, para que você possa inspecionar ou manipular partes individuais antes de salvar.

Padrão de Conversão em Lote

Ao processar um diretório de arquivos, envolva cada conversão em um try/catch para que um único arquivo corrompido não interrompa todo o lote.

import { Scene } from '@aspose/3d';
import { readdirSync } from 'fs';
import { join, basename, extname } from 'path';

interface ConversionResult {
  input: string;
  output: string;
  success: boolean;
  error?: string;
}

function batchConvertToGlb(
  inputDir: string,
  outputDir: string,
  extensions: string[] = ['.obj', '.stl', '.3mf', '.dae']  // .fbx excluded: format auto-detection not wired
): ConversionResult[] {
  const results: ConversionResult[] = [];

  const files = readdirSync(inputDir).filter((f) =>
    extensions.includes(extname(f).toLowerCase())
  );

  for (const file of files) {
    const inputPath = join(inputDir, file);
    const outputPath = join(outputDir, basename(file, extname(file)) + '.glb');

    try {
      const scene = new Scene();
      scene.open(inputPath);
      scene.save(outputPath);  // extension '.glb' infers GLB format
      results.push({ input: inputPath, output: outputPath, success: true });
    } catch (err) {
      const message = err instanceof Error ? err.message : String(err);
      results.push({ input: inputPath, output: outputPath, success: false, error: message });
      console.error(`Failed to convert ${file}: ${message}`);
    }
  }

  const succeeded = results.filter((r) => r.success).length;
  console.log(`Batch complete: ${succeeded}/${results.length} files converted.`);
  return results;
}

// Usage
batchConvertToGlb('./input', './output');

O padrão acima lê cada extensão de arquivo suportada de um diretório de entrada, converte para GLB e registra quaisquer falhas sem interromper o loop. O array retornado de ConversionResult os objetos podem ser usados para relatórios ou lógica de repetição.

Conclusão

@aspose/3d cobre toda a gama de necessidades de conversão de formatos em uma aplicação Node.js TypeScript com uma API de dois passos consistente: scene.open() para carregar, scene.save() para gravar. A principal restrição a lembrar é que as classes de importação e exportação FBX existem, mas a detecção automática de formato ainda não está implementada, portanto arquivos FBX não podem ser carregados via scene.open().

Para mais detalhes sobre o Scene, Node, e Mesh classes usadas nestes exemplos, consulte as páginas de referência de classes nesta documentação.