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. Gerenciar essas conversões com uma API única e 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 voltada para TypeScript para leitura e gravação de todos os principais formatos 3D no Node.js. Este guia percorre os fluxos de trabalho 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 Suportados

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

Nota: OBJ é apenas de importação (canExport: false). Para converter o conteúdo OBJ para outro formato, carregue-o com scene.open() e salve em um formato de exportação 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: Preparando um Modelo 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 seu arquivo OBJ usa grupos de material, essas informações são descartadas durante a exportação. Para formatos de impressão que preservam cores, considere 3MF (veja abaixo).

STL para glTF: De Saída de Scanner ou 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 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 3D Manufacturing Format (3MF) está sendo cada vez mais usado em fluxos de trabalho de fabricação 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, preservando 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.

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 objetos pode ser usado para relatórios ou lógica de reintento.

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.