Konvertering mellem 3D-formater i TypeScript med Aspose.3D FOSS

Node.js-udviklere, der arbejder med 3D-indhold, har ofte brug for at konvertere mellem formater: et designværktøj eksporterer OBJ, en web‑renderer forventer GLB, en 3D‑printer kræver STL, og en produktionspipeline bruger 3MF. At håndtere disse konverteringer med et enkelt, konsistent API reducerer antallet af eksterne værktøjer i en pipeline og holder konverteringslogikken inde i applikationskoden, hvor den kan testes og versioneres.

Den @aspose/3d pakken (v24.12.0, MIT-licens) leverer et TypeScript‑først API til at læse og skrive alle større 3D-formater i Node.js. Denne guide gennemgår de mest almindelige konverteringsarbejdsgange.

Installation

npm install @aspose/3d

Krav: Node.js 18, 20 eller 22; TypeScript 5.0 eller nyere. Den eneste runtime‑afhængighed er xmldom.

Understøttede formater

Tabellen nedenfor viser de formater, der dækkes i denne guide, samt deres læse/skriv‑understøttelse.

OBJ understøtter både import og eksport. Indlæs med scene.open() og gem med scene.save('output.obj'), eller konverter til et andet understøttet format såsom glTF, STL eller 3MF.

OBJ til GLB (Weblevering)

Konvertering af OBJ til binær glTF (GLB) er den mest almindelige web‑arbejdsgang. GLB er en selvstændig binær pakke: teksturer, geometri og metadata i én fil, hvilket gør den effektiv til HTTP‑levering og direkte indlæsning af Three.js, Babylon.js og 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');

Outputformatet udledes fra filendelsen. Brug .glb til binær GLB eller .gltf til den separate JSON + .bin layout.

OBJ til STL (3D‑printforberedelse)

STL er lingua franca inden for FDM‑ og SLA‑3D‑print. Slicere som PrusaSlicer, Bambu Studio og Chitubox accepterer alle STL. Konvertering fra OBJ til STL er ligetil, fordi begge formater gemmer trekantmesh.

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 gemmer ikke farve, materiale eller UV‑data. Hvis din OBJ‑fil bruger materialgrupper, fjernes disse oplysninger ved eksport. For farvebevarende udskriftsformater, overvej i stedet 3MF (se nedenfor).

STL til glTF (Scanner og CAD til Web)

Struktureret‑lys‑scannere og parametriske CAD‑eksportører udgiver typisk STL. Konvertering til glTF gør geometrien tilgængelig i web‑baserede visningsprogrammer og AR‑platforme uden et server‑side renderings‑trin.

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 ikke indeholder materiale‑ eller teksturinformation, vil den resulterende glTF‑fil kun indeholde geometri. Du kan ved behov programmatiskt vedhæfte materialer til scenenoder efter indlæsning.

3MF to glTF (Manufacturing to Visualization)

3D Manufacturing Format (3MF) bruges i stigende grad i additive fremstillingsarbejdsgange, fordi den gemmer farve, materialer, komponenttræer og udskrivningsmetadata sammen med geometrien. Konvertering af 3MF til glTF muliggør efterfølgende visualisering i webværktøjer, samtidig med at scenestrukturen bevares.

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() bevarer komponenthierarkiet i scene.rootNode.childNodes, så du kan inspicere eller manipulere individuelle dele før du gemmer.

Massekonverteringsmønster

Når du behandler en mappe med filer, skal du pakke hver konvertering ind i en try/catch så en enkelt korrupt fil ikke afbryder hele batchen.

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

Mønstret ovenfor læser hver understøttet filtype fra en inputmappe, konverterer til GLB og logger eventuelle fejl uden at stoppe løkken. Den returnerede array af ConversionResult objekter kan bruges til rapportering eller genforsøgslogik.

Konklusion

@aspose/3d dækker hele spektret af formatkonverteringsbehov i en Node.js TypeScript-applikation med et konsistent to-trins API: scene.open() til indlæsning, scene.save() til skrivning. Den vigtigste begrænsning at huske er, at FBX-import- og eksportklasser findes, men automatisk formatgenkendelse er endnu ikke implementeret, så FBX-filer kan ikke indlæses via scene.open().

For mere detaljer om Scene, Node, og Mesh klasser, der bruges i disse eksempler, se klassereferencens sider i denne dokumentation.