Conversione tra formati 3D in TypeScript con Aspose.3D FOSS

Gli sviluppatori Node.js che lavorano con contenuti 3D hanno spesso bisogno di convertire tra formati: uno strumento di progettazione esporta OBJ, un renderer web si aspetta GLB, una stampante 3D richiede STL e una pipeline di produzione utilizza 3MF. Gestire queste conversioni con un’unica API coerente riduce il numero di strumenti esterni in una pipeline e mantiene la logica di conversione all’interno del codice dell’applicazione, dove può essere testata e versionata.

Il @aspose/3d Il pacchetto (v24.12.0, licenza MIT) fornisce un’API incentrata su TypeScript per leggere e scrivere tutti i principali formati 3D in Node.js. Questa guida illustra i flussi di lavoro di conversione più comuni.

Installazione

npm install @aspose/3d

Requisiti: Node.js 18, 20 o 22; TypeScript 5.0 o successivo. L’unica dipendenza a runtime è xmldom.

Formati supportati

La tabella seguente elenca i formati trattati in questa guida e il loro supporto di lettura/scrittura.

OBJ supporta sia l’importazione che l’esportazione. Carica con scene.open() e salva con scene.save('output.obj'), o converti in qualsiasi altro formato supportato come glTF, STL o 3MF.

OBJ a GLB (Consegna Web)

Convertire OBJ in glTF binario (GLB) è il flusso di lavoro web più comune. GLB è un pacchetto binario autonomo: texture, geometria e metadati in un unico file, il che lo rende efficiente per la consegna HTTP e il caricamento diretto da parte di 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');

Il formato di output è dedotto dall’estensione del file. Usa .glb per GLB binario o .gltf per il JSON separato + .bin layout.

OBJ a STL (Preparazione per Stampa 3D)

STL è la lingua franca della stampa 3D FDM e SLA. Slicer come PrusaSlicer, Bambu Studio e Chitubox accettano tutti STL. Convertire da OBJ a STL è semplice perché entrambi i formati memorizzano mesh triangolari.

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 non memorizza colori, materiali o dati UV. Se il tuo file OBJ utilizza gruppi di materiale, tali informazioni vengono eliminate durante l’esportazione. Per formati di stampa che preservano i colori, considera invece 3MF (vedi sotto).

STL a glTF (Scanner e CAD al Web)

Gli scanner a luce strutturata e gli esportatori CAD parametrici producono comunemente STL. Convertire in glTF rende la geometria accessibile nei visualizzatori basati sul web e nelle piattaforme AR senza una fase di rendering lato server.

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

Poiché STL non contiene informazioni su materiali o texture, il file glTF risultante conterrà solo la geometria. È possibile allegare materiali programmaticamente ai nodi della scena dopo il caricamento, se necessario.

3MF to glTF (Manufacturing to Visualization)

Il formato di produzione 3D (3MF) è sempre più utilizzato nei flussi di lavoro di stampa additiva perché memorizza colore, materiali, alberi di componenti e metadati di stampa insieme alla geometria. Convertire 3MF in glTF consente la visualizzazione a valle in strumenti web preservando la struttura della scena.

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 gerarchia dei componenti in scene.rootNode.childNodes, così puoi ispezionare o manipolare le singole parti prima di salvare.

Pattern di Conversione Batch

Durante l’elaborazione di una directory di file, avvolgi ogni conversione in un try/catch in modo che un singolo file corrotto non interrompa l’intero batch.

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

Il modello sopra legge ogni estensione di file supportata da una directory di input, converte in GLB e registra eventuali errori senza interrompere il ciclo. L’array restituito di ConversionResult oggetti può essere utilizzato per la generazione di report o la logica di retry.

Conclusione

@aspose/3d copre l’intera gamma di esigenze di conversione di formati in un’applicazione Node.js TypeScript con un’API a due passaggi coerente: scene.open() per caricare, scene.save() per scrivere. La principale limitazione da ricordare è che le classi di importazione ed esportazione FBX esistono, ma il rilevamento automatico del formato non è ancora implementato, quindi i file FBX non possono essere caricati tramite scene.open().

Per maggiori dettagli sul Scene, Node, e Mesh classi utilizzate in questi esempi, consulta le pagine di riferimento delle classi in questa documentazione.