Conversión entre formatos 3D en TypeScript con Aspose.3D FOSS

Los desarrolladores de Node.js que trabajan con contenido 3D a menudo necesitan convertir entre formatos: una herramienta de diseño exporta OBJ, un renderizador web espera GLB, una impresora 3D requiere STL y una cadena de fabricación usa 3MF. Gestionar estas conversiones con una API única y coherente reduce la cantidad de herramientas externas en una canalización y mantiene la lógica de conversión dentro del código de la aplicación, donde puede ser probada y versionada.

El @aspose/3d El paquete (v24.12.0, licencia MIT) proporciona una API centrada en TypeScript para leer y escribir todos los principales formatos 3D en Node.js. Esta guía recorre los flujos de trabajo de conversión más comunes.

Instalación

npm install @aspose/3d

Requisitos: Node.js 18, 20 o 22; TypeScript 5.0 o posterior. La única dependencia en tiempo de ejecución es xmldom.

Formatos compatibles

La tabla a continuación enumera los formatos cubiertos en esta guía y su soporte de lectura/escritura.

Nota: OBJ es solo de importación (canExport: false). Para convertir el contenido OBJ a otro formato, cárgalo con scene.open() y guárdalo en un formato de exportación compatible como glTF, STL o 3MF.

OBJ a GLB (Entrega web)

Convertir OBJ a glTF binario (GLB) es el flujo de trabajo web más común. GLB es un paquete binario autocontenido: texturas, geometría y metadatos en un solo archivo, lo que lo hace eficiente para la entrega HTTP y la carga directa por Three.js, Babylon.js y 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');

El formato de salida se infiere de la extensión del archivo. Usa .glb para GLB binario o .gltf para el JSON separado + .bin estructura.

OBJ a STL: Preparando un modelo para impresión 3D

STL es la lingua franca de la impresión 3D FDM y SLA. Los slicers como PrusaSlicer, Bambu Studio y Chitubox aceptan STL. Convertir de OBJ a STL es sencillo porque ambos formatos almacenan mallas 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 no almacena color, material ni datos UV. Si su archivo OBJ usa grupos de material, esa información se descarta durante la exportación. Para formatos de impresión que preservan el color, considere 3MF en su lugar (ver más abajo).

STL a glTF: De la salida de escáner o CAD a la web

Los escáneres de luz estructurada y los exportadores CAD paramétricos suelen generar STL. Convertir a glTF hace que la geometría sea accesible en visores basados en la web y plataformas de AR sin un paso de renderizado del lado del 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');

Debido a que STL no lleva información de material ni de textura, el archivo glTF resultante contendrá solo geometría. Puedes adjuntar materiales programáticamente a los nodos de la escena después de cargarlo si es necesario.

3MF to glTF (Manufacturing to Visualization)

El Formato de Fabricación 3D (3MF) se utiliza cada vez más en flujos de trabajo de fabricación aditiva porque almacena color, materiales, árboles de componentes y metadatos de impresión junto con la geometría. Convertir 3MF a glTF permite la visualización posterior en herramientas web mientras se preserva la estructura de la escena.

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 la jerarquía de componentes en scene.rootNode.childNodes, por lo que puedes inspeccionar o manipular partes individuales antes de guardar.

Patrón de Conversión por Lotes

Al procesar un directorio de archivos, envuelve cada conversión en un try/catch para que un solo archivo corrupto no aborta todo el 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');

El patrón anterior lee cada extensión de archivo compatible de un directorio de entrada, convierte a GLB y registra cualquier error sin detener el bucle. La matriz devuelta de ConversionResult objetos puede usarse para informes o lógica de reintento.

Conclusión

@aspose/3d cubre todo el espectro de necesidades de conversión de formatos en una aplicación Node.js TypeScript con una API de dos pasos consistente: scene.open() para cargar, scene.save() para escribir. La restricción clave a recordar es que existen clases de importador y exportador FBX, pero la detección automática de formatos aún no está implementada, por lo que los archivos FBX no pueden cargarse a través de scene.open().

Para más detalle sobre el Scene, Node, y Mesh clases usadas en estos ejemplos, consulta las páginas de referencia de clases en esta documentación.