Konverzia medzi 3D formátmi v TypeScript s Aspose.3D FOSS

Vývojári Node.js pracujúci s 3D obsahom často potrebujú konvertovať medzi formátmi: nástroj na návrh exportuje OBJ, webový renderér očakáva GLB, 3D tlačiareň vyžaduje STL a výrobný reťazec používa 3MF. Spracovanie týchto konverzií pomocou jedného, konzistentného API znižuje počet externých nástrojov v reťazci a udržiava logiku konverzie v kóde aplikácie, kde môže byť testovaná a verzovaná.

The @aspose/3d balík (v24.12.0, licencia MIT) poskytuje API orientované na TypeScript pre čítanie a zápis všetkých hlavných 3D formátov v Node.js. Tento sprievodca prechádza najčastejšími pracovnými postupmi konverzie.

Inštalácia

npm install @aspose/3d

Požiadavky: Node.js 18, 20 alebo 22; TypeScript 5.0 alebo novší. Jediná runtime závislosť je xmldom.

Podporované formáty

Nižšie uvedená tabuľka uvádza formáty zahrnuté v tomto sprievodcovi a ich podporu čítania/zápisu.

OBJ podporuje import aj export. Načítajte pomocou scene.open() a uložte pomocou scene.save('output.obj'), alebo konvertovať do akéhokoľvek iného podporovaného formátu, ako je glTF, STL alebo 3MF.

OBJ na GLB (Webové doručenie)

Konverzia OBJ na binárny glTF (GLB) je najbežnejší webový pracovný postup. GLB je samostatný binárny balík: textúry, geometria a metadáta v jednom súbore, čo ho robí efektívnym pre doručovanie cez HTTP a priame načítanie v Three.js, Babylon.js a 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');

Výstupný formát sa odvodzuje z prípony súboru. Použite .glb pre binárny GLB alebo .gltf pre samostatný JSON + .bin rozloženie.

OBJ na STL (Príprava pre 3D tlač)

STL je lingua franca FDM a SLA 3D tlače. Slicery ako PrusaSlicer, Bambu Studio a Chitubox všetky akceptujú STL. Konverzia z OBJ na STL je jednoduchá, pretože oba formáty ukladajú trojuholníkové siete.

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 neukladá farbu, materiál ani UV dáta. Ak váš OBJ súbor používa skupiny materiálov, tieto informácie sa pri exporte zahodia. Pre formáty tlače zachovávajúce farbu zvážte namiesto toho 3MF (viď nižšie).

STL na glTF (Scanner a CAD na Web)

Štruktúrované svetelné skenery a parametrické CAD exportéry bežne výstupujú STL. Konverzia na glTF sprístupní geometriu v webových prehliadačoch a AR platformách bez kroku serverového renderovania.

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

Keďže STL neobsahuje informácie o materiáloch alebo textúrach, výsledný glTF súbor bude obsahovať iba geometriu. Po načítaní môžete programovo pripojiť materiály k uzlom scény, ak je to potrebné.

3MF to glTF (Manufacturing to Visualization)

Formát 3D Manufacturing (3MF) sa čoraz častejšie používa v pracovných postupoch aditívnej výroby, pretože ukladá farbu, materiály, strom komponentov a metadáta tlače spolu s geometriou. Konverzia 3MF na glTF umožňuje následnú vizualizáciu vo webových nástrojoch pri zachovaní štruktúry scény.

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() zachováva hierarchiu komponentov v scene.rootNode.childNodes, takže môžete skontrolovať alebo manipulovať s jednotlivými časťami pred uložením.

Vzor dávkovej konverzie

Pri spracovávaní adresára súborov zabaľte každú konverziu do try/catch aby jeden poškodený súbor neukončil celý 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');

Vzor vyššie číta každú podporovanú príponu súboru z vstupného adresára, konvertuje do GLB a zaznamenáva akékoľvek zlyhania bez zastavenia slučky. Vrátené pole ConversionResult objektov môže byť použité na reportovanie alebo logiku opakovaného pokusu.

Záver

@aspose/3d pokryje celý rozsah potrieb konverzie formátov v aplikácii Node.js TypeScript s konzistentným dvojkrokovým API: scene.open() na načítanie, scene.save() na zápis. Kľúčové obmedzenie, ktoré treba mať na pamäti, je, že triedy importéra a exportéra FBX existujú, ale automatické rozpoznávanie formátu ešte nie je prepojené, takže FBX súbory nie je možné načítať cez scene.open().

Pre viac podrobností o Scene, Node, a Mesh triedy použité v týchto príkladoch, pozrite si stránky referencie tried v tejto dokumentácii.