Převod mezi 3D formáty v TypeScriptu s Aspose.3D FOSS

Vývojáři Node.js pracující s 3D obsahem často potřebují převádět mezi formáty: nástroj pro návrh exportuje OBJ, webový renderér očekává GLB, 3D tiskárna vyžaduje STL a výrobní pipeline používá 3MF. Zpracování těchto převodů pomocí jediné, konzistentní API snižuje počet externích nástrojů v pipeline a udržuje logiku převodu uvnitř aplikačního kódu, kde může být testována a verzována.

Ten @aspose/3d balíček (v24.12.0, licence MIT) poskytuje API zaměřené na TypeScript pro čtení a zápis všech hlavních 3D formátů v Node.js. Tento průvodce provádí nejčastějšími konverzními pracovními postupy.

Instalace

npm install @aspose/3d

Požadavky: Node.js 18, 20 nebo 22; TypeScript 5.0 nebo novější. Jediná runtime závislost je xmldom.

Podporované formáty

Tabulka níže uvádí formáty zahrnuté v tomto průvodci a jejich podporu čtení/zápisu.

OBJ podporuje jak import, tak export. Načtěte pomocí scene.open() a uložte pomocí scene.save('output.obj'), nebo převést do jakéhokoli jiného podporovaného formátu, jako je glTF, STL nebo 3MF.

OBJ na GLB (Webové doručení)

Převod OBJ na binární glTF (GLB) je nejčastější webový pracovní postup. GLB je samostatný binární balíček: textury, geometrie a metadata v jediném souboru, což jej činí efektivním pro doručování přes HTTP a přímé načítání 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 je odvozen z přípony souboru. Použijte .glb pro binární GLB nebo .gltf pro samostatný JSON + .bin rozvržení.

OBJ na STL (příprava pro 3D tisk)

STL je lingua franca FDM a SLA 3D tisku. Slicery jako PrusaSlicer, Bambu Studio a Chitubox všechny přijímají STL. Převod z OBJ na STL je jednoduchý, protože oba formáty ukládají trojúhelníkové sítě.

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 neukládá barvu, materiál ani UV data. Pokud váš OBJ soubor používá skupiny materiálů, tyto informace jsou při exportu zahozeny. Pro formáty tisku zachovávající barvy zvažte místo toho 3MF (viz níže).

STL na glTF (skener a CAD na web)

Skenery se strukturovaným světlem a parametrické CAD exportéry běžně vytvářejí STL. Převod na glTF zpřístupní geometrii ve webových prohlížečích a AR platformách bez kroku serverového renderování.

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

Protože STL neobsahuje žádné informace o materiálu nebo texturách, výsledný glTF soubor bude obsahovat pouze geometrii. V případě potřeby můžete po načtení programově připojit materiály k uzlům scény.

3MF to glTF (Manufacturing to Visualization)

Formát 3D Manufacturing (3MF) se stále častěji používá v pracovních postupech aditivní výroby, protože ukládá barvu, materiály, strom komponent a metadata tisku spolu s geometrií. Převod 3MF na glTF umožňuje následnou vizualizaci ve webových nástrojích při zachování struktury 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ává hierarchii komponent v scene.rootNode.childNodes, takže můžete zkontrolovat nebo manipulovat s jednotlivými částmi před uložením.

Vzor hromadného převodu

Při zpracování adresáře souborů zabalte každou konverzi do try/catch aby jediný poškozený soubor neukončil celý dávkový proces.

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

Výše uvedený vzor načítá každou podporovanou příponu souboru ze vstupního adresáře, převádí do GLB a zaznamenává jakékoli selhání, aniž by zastavil smyčku. Vrácené pole ConversionResult objektů lze použít pro reportování nebo logiku opakování.

Závěr

@aspose/3d pokrývá celý rozsah potřeb konverze formátů v aplikaci Node.js TypeScript s konzistentním dvoukrokovým API: scene.open() pro načtení, scene.save() pro zápis. Klíčové omezení, které je třeba si zapamatovat, je, že třídy importéru a exportéru FBX existují, ale automatické rozpoznání formátu ještě není napojeno, takže soubory FBX nelze načíst pomocí scene.open().

Pro podrobnější informace o Scene, Node, Mesh třídách použitých v těchto příkladech, viz stránky referenčních tříd v této dokumentaci.