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.

Hinweis: OBJ ist nur importierbar (canExport: false). Um OBJ-Inhalte in ein anderes Format zu konvertieren, laden Sie es mit scene.open() und speichern Sie in ein unterstütztes Exportformat wie 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 eines Modells für den 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 Farbe, Materialien 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: Von Scanner‑ oder CAD‑Ausgabe zum 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. Sie können bei Bedarf 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 nachgelagerte Visualisierung in Web‑Tools, während 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() bewahrt die Komponentenhierarchie in scene.rootNode.childNodes, sodass Sie einzelne Teile vor dem Speichern prüfen oder manipulieren können.

Muster für Stapelkonvertierung

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 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 Formatkonvertierungsbedürfnisse 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 Exportklassen existieren, die automatische Formaterkennung 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 Klassennachschlage‑Seiten in dieser Dokumentation.