Konvertieren zwischen 3D-Formaten in TypeScript mit Aspose.3D FOSS

Node.js-Entwickler, die mit 3D-Inhalten arbeiten, müssen häufig zwischen Formaten konvertieren: Ein Design‑Tool exportiert OBJ, ein Web‑Renderer erwartet GLB, ein 3D‑Drucker benötigt STL und eine Fertigungspipeline verwendet 3MF. Die Durchführung dieser Konvertierungen mit einer einzigen, konsistenten API reduziert die Anzahl externer Werkzeuge in einer Pipeline und hält die Konvertierungslogik im Anwendungscode, wo sie getestet und versioniert werden kann.

Der @aspose/3d Das Paket (v24.12.0, MIT-Lizenz) bietet eine TypeScript‑first API zum Lesen und Schreiben aller gängigen 3D‑Formate in Node.js. Dieser Leitfaden führt durch die häufigsten Konvertierungs‑Workflows.

Installation

npm install @aspose/3d

Voraussetzungen: Node.js 18, 20 oder 22; TypeScript 5.0 oder neuer. Die einzige Laufzeitabhängigkeit ist xmldom.

Unterstützte Formate

Die nachstehende Tabelle listet die in diesem Handbuch behandelten Formate und deren Lese‑/Schreibunterstützung auf.

OBJ unterstützt sowohl Import als auch Export. Laden mit scene.open() und speichern mit scene.save('output.obj'), oder in ein anderes unterstütztes Format konvertieren, z. B. glTF, STL oder 3MF.

OBJ zu GLB (Web‑Bereitstellung)

Die Konvertierung von OBJ zu binärem glTF (GLB) ist der gängigste Web‑Workflow. GLB ist ein eigenständiges Binärpaket: Texturen, Geometrie und Metadaten in einer einzigen Datei, was es für die HTTP‑Auslieferung und das direkte Laden durch Three.js, Babylon.js und model‑viewer effizient macht.

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

Das Ausgabeformat wird anhand der Dateierweiterung ermittelt. Verwenden Sie .glb für binäres GLB oder .gltf für das separate JSON + .bin Layout.

OBJ zu STL (Vorbereitung für 3D‑Druck)

STL ist die Lingua Franca des FDM‑ und SLA‑3D‑Drucks. Slicer wie PrusaSlicer, Bambu Studio und Chitubox akzeptieren STL. Die Konvertierung von OBJ zu STL ist unkompliziert, da beide Formate Dreiecks‑Meshes speichern.

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 speichert keine Farb‑, Material‑ oder UV‑Daten. Wenn Ihre OBJ‑Datei Materialgruppen verwendet, gehen diese Informationen beim Export verloren. Für farbtreue Druckformate sollten Sie stattdessen 3MF in Betracht ziehen (siehe unten).

STL zu glTF (Scanner‑ und CAD‑zu‑Web)

Strukturlicht‑Scanner und parametrische CAD‑Exporter geben häufig STL aus. Die Konvertierung zu glTF macht die Geometrie in webbasierten Viewern und AR‑Plattformen ohne einen serverseitigen Rendering‑Schritt zugänglich.

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

Da STL keine Material‑ oder Texturinformationen enthält, wird die resultierende glTF‑Datei nur Geometrie enthalten. Bei Bedarf können Sie nach dem Laden Materialien programmgesteuert an Szenenknoten anhängen.

3MF to glTF (Manufacturing to Visualization)

Das 3D Manufacturing Format (3MF) wird in additiven Fertigungs‑Workflows immer häufiger eingesetzt, weil es Farbe, Materialien, Komponentenbäume und Druck‑Metadaten zusammen mit der Geometrie speichert. Die Konvertierung von 3MF zu glTF ermöglicht die nachgelagerte Visualisierung in Web‑Tools, wobei die Szenenstruktur erhalten bleibt.

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() erhält die Komponentenhierarchie in scene.rootNode.childNodes, sodass Sie einzelne Teile vor dem Speichern prüfen oder manipulieren können.

Muster für Batch‑Konvertierung

Beim Verarbeiten eines Verzeichnisses mit Dateien, wickeln Sie jede Konvertierung in ein try/catch damit eine einzelne beschädigte Datei nicht den gesamten Batch abbricht.

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

Das obige Muster liest jede unterstützte Dateierweiterung aus einem Eingabeverzeichnis, konvertiert sie zu GLB und protokolliert etwaige Fehler, ohne die Schleife zu stoppen. Das zurückgegebene Array von ConversionResult Objekten kann für Berichte oder Wiederholungslogik verwendet werden.

Fazit

@aspose/3d deckt den gesamten Bereich der Formatkonvertierungsanforderungen in einer Node.js TypeScript‑Anwendung mit einer konsistenten Zwei‑Schritt‑API ab: scene.open() zum Laden, scene.save() zum Schreiben. Die wichtigste Einschränkung, die zu beachten ist, besteht darin, dass FBX‑Import‑ und Export‑Klassen vorhanden sind, die automatische Format­erkennung jedoch noch nicht implementiert ist, sodass FBX‑Dateien nicht über scene.open().

Für weitere Details zu dem Scene, Node, und Mesh Klassen, die in diesen Beispielen verwendet werden, siehe die Klassereferenzseiten in dieser Dokumentation.