Conversió entre formats 3D en TypeScript amb Aspose.3D FOSS

Node.js developers working with 3D content frequently need to convert between formats: a design tool exports OBJ, a web renderer expects GLB, a 3D printer requires STL, and a manufacturing pipeline uses 3MF. Handling these conversions with a single, consistent API reduces the number of external tools in a pipeline and keeps conversion logic inside the application code where it can be tested and versioned.

El @aspose/3d El paquet (v24.12.0, llicència MIT) proporciona una API TypeScript-first per llegir i escriure tots els formats 3D principals en Node.js. Aquesta guia fa un recorregut pels fluxos de treball de conversió més comuns.

Instal·lació

npm install @aspose/3d

Requisits: Node.js 18, 20 o 22; TypeScript 5.0 o posterior. L’única dependència de temps d’execució és xmldom.

Formats suportats

La taula següent enumera els formats que cobreix aquesta guia i el seu suport de lectura/escriptura.

OBJ dóna suport tant a la importació com a l’exportació. scene.open() i salvar amb scene.save('output.obj'), o convertir a qualsevol altre format suportat com glTF, STL o 3MF.

OBJ a GLB (Enviament per Internet)

La conversió d’OBJ a glTF binari (GLB) és el flux de treball web més comú. GLB és un paquet binar autònom: textures, geometria i metadades en un sol arxiu, que ho fa eficient per a la lliurament HTTP i càrrega directa per Three.js, Babylon. js i 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 format d’expressió s’inverteix a partir de l’estensió del fitxer. Use .glb per a GLB binari o .gltf per al JSON + separat .bin la disposició.

OBJ a STL (3D Printing Prep)

STL és la lingua franca de l’impressió 3D FDM i SLA. Els segadors com PrusaSlicer, Bambu Studio i Chitubox accepten tots el ST L. La conversió d’OBJ a STl és senzilla perquè ambdós formats emmagatzemen malles triangulars.

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 emmagatzemà dades de color, material o UV. Si el teu arxiu OBJ utilitza grups de materials, aquesta informació es perd durant l’exportació. Per a formats d’impressió que preservin els colors, considera 3MF en lloc (veure més avall).

STL a glTF (Scanner i CAD a Web)

Els escàners de llum estructurada i els exportadors CAD paramètrics solen produir STL. La conversió a glTF fa que la geometria sigui accessible en visualitzadors basats en web i plataformes AR sense un pas de renderizació del costat 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');

Com que STL no porta informació de material o textura, el fitxer glTF resultant només contindrà geometria. Pots afegir materials programàticament als nodes d’escena després de carregar-los si és necessari.

3MF to glTF (Manufacturing to Visualization)

El format de fabricació 3D (3MF) s’utilitza cada vegada més en els fluxos de treball d’aditiu, ja que emmagatzemen colors, materials, arbres de components i metadatges d ‘impressió al costat de la geometria. La conversió del 3M F a glTF permet una visualització descendent en eines web mentre es preserva l’estructura de les escenes.

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() conserva la jerarquia de components en scene.rootNode.childNodes, per tal que puguis inspeccionar o manipular parts individuals abans de guardar.

Pauta de conversió per lot

Quan es processa un directori de fitxers, envoltar cada conversió en una try/catch per tal que un sol fitxer corromput no abortés tot el batx.

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ó anterior llegeix cada extensió de fitxer suportada d’un directori d ’entrada, converteix a GLB i registra qualsevol error sense aturar el bucle. La matriu retornada de ConversionResult Els objectes poden ser utilitzats per a la informació o repetició de lògica.

Conclo­rència

@aspose/3d cobreix tota la gamma de necessitats de conversió de formats en una aplicació Node.js TypeScript amb una API consistent de dos passos: scene.open() per a carregar, scene.save() La limitació clau per recordar és que FBX importador i exportadora classes existeixen però format auto-detecció encara no està connectat, de manera que els arxius FBx no es poden carregar via scene.open().

Per a més detalls sobre el Scene, Node, i Mesh classes utilitzades en aquests exemples, vegeu les pàgines de referència a classe d’aquesta documentació.