3D formátumok közötti konvertálás TypeScriptben a Aspose.3D FOSS segítségével

A 3D tartalommal dolgozó Node.js fejlesztőknek gyakran kell formátumok között konvertálni: egy tervezőeszköz OBJ-t exportál, egy webes renderelő GLB-t vár, egy 3D nyomtató STL-t igényel, és egy gyártási folyamat 3MF-et használ. Ezeknek a konverzióknak a kezelését egyetlen, konzisztens API-val csökkenti a külső eszközök számát a folyamatban, és a konverziós logikát az alkalmazáskódban tartja, ahol tesztelhető és verziózható.

A @aspose/3d A csomag (v24.12.0, MIT licenc) TypeScript‑első API-t biztosít a főbb 3D formátumok Node.js‑ben történő olvasásához és írásához. Ez az útmutató végigvezet a leggyakoribb konverziós munkafolyamatokon.

Telepítés

npm install @aspose/3d

Követelmények: Node.js 18, 20 vagy 22; TypeScript 5.0 vagy újabb. Az egyetlen futásidejű függőség a xmldom.

Támogatott formátumok

Az alábbi táblázat felsorolja az útmutatóban szereplő formátumokat és azok olvasási/írási támogatását.

Az OBJ támogatja az importot és az exportot is. Töltsd be a scene.open() és mentsd a scene.save('output.obj'), vagy konvertálj bármely más támogatott formátumba, például glTF, STL vagy 3MF.

OBJ → GLB (Webes szállítás)

Az OBJ bináris glTF‑re (GLB) konvertálása a leggyakoribb webes munkafolyamat. A GLB egy önálló bináris csomag: textúrák, geometria és metaadatok egyetlen fájlban, ami hatékonnyá teszi HTTP‑n keresztüli szállításkor és a Three.js, Babylon.js, valamint a model‑viewer közvetlen betöltésekor.

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

A kimeneti formátum a fájlkiterjesztésből kerül meghatározásra. Használd a .glb bináris GLB-hez vagy .gltf a különálló JSON + .bin elrendezés.

OBJ → STL (3D nyomtatás előkészítése)

Az STL az FDM és SLA 3D nyomtatás közös nyelve. A PrusaSlicer, Bambu Studio és Chitubox szeletelők mind elfogadják az STL-t. Az OBJ‑ról STL‑re konvertálás egyszerű, mivel mindkét formátum háromszög hálókat tárol.

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

Az STL nem tárol színt, anyagot vagy UV adatot. Ha az OBJ fájl anyagcsoportokat használ, ez az információ az exportálás során elveszik. Színmegőrző nyomtatási formátumokhoz inkább a 3MF-et vegye figyelembe (lásd alább).

STL → glTF (Szkenner és CAD a webre)

A struktúrált fényes szkennerek és a paraméteres CAD exporterek gyakran STL-t állítanak elő. A glTF‑re konvertálás lehetővé teszi a geometria elérését webes megjelenítőkben és AR platformokon szerveroldali renderelés nélkül.

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

Mivel az STL nem tartalmaz anyag- vagy textúrainformációt, a keletkező glTF fájl csak geometriát fog tartalmazni. Szükség esetén programozottan anyagokat csatolhat a jelenet csomópontjaihoz a betöltés után.

3MF to glTF (Manufacturing to Visualization)

A 3D Manufacturing Format (3MF) egyre gyakrabban használatos az additív gyártási munkafolyamatokban, mivel a geometria mellett színinformációt, anyagokat, alkatrészfákat és nyomtatási metaadatokat is tárol. A 3MF glTF-re konvertálása lehetővé teszi a későbbi megjelenítést webes eszközökben, miközben megőrzi a jelenet struktúráját.

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() megőrzi az összetevő hierarchiáját a scene.rootNode.childNodes, így ellenőrizhet vagy módosíthat egyes részeket a mentés előtt.

Kötegelt konverzió mintája

Fájlok könyvtárának feldolgozásakor csomagolja minden konverziót egy try/catch így egyetlen sérült fájl sem szakítja meg a teljes köteg feldolgozását.

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

A fenti minta beolvassa a támogatott fájlkiterjesztéseket egy bemeneti könyvtárból, GLB-re konvertál, és naplózza a hibákat anélkül, hogy leállítaná a ciklust. A visszaadott tömb a ConversionResult objektumok jelentéshez vagy újrapróbálási logikához használhatók.

Összegzés

@aspose/3d lefedi a formátumkonverzió teljes skáláját egy Node.js TypeScript alkalmazásban, egységes kéttagú API-val: scene.open() betöltéshez, scene.save() íráshoz. A fő korlátozás, amit szem előtt kell tartani, hogy léteznek FBX importáló és exportáló osztályok, de a formátum automatikus felismerése még nincs beépítve, így az FBX fájlok nem tölthetők be a scene.open().

További részletekért a Scene, Node, és Mesh példákban használt osztályok, lásd az osztályreferencia oldalakat ebben a dokumentációban.