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-/skrive‑understøttelse.

Bemærk: OBJ er kun import (canExport: false). For at konvertere OBJ-indhold til et andet format, indlæs det med scene.open() og gem til et understøttet eksportformat såsom glTF, STL eller 3MF.

OBJ til GLB (Weblevering)

Konvertering af OBJ til binær glTF (GLB) er den mest almindelige web‑workflow. 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 af filendelsen. Brug .glb til binær GLB eller .gltf for den separate JSON + .bin layout.

OBJ til STL: Forberedelse af en model til 3D-print

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 under eksport. For farvebevarende udskriftsformater, overvej i stedet 3MF (se nedenfor).

STL til glTF: Fra scanner‑ eller CAD‑output 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');

Fordi STL ikke indeholder materiale- eller teksturinformation, vil den resulterende glTF-fil kun indeholde geometri. Du kan vedhæfte materialer programmatisk til scenenoder efter indlæsning, hvis det er nødvendigt.

3MF to glTF (Manufacturing to Visualization)

3D Manufacturing Format (3MF) bliver i stigende grad brugt 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.

Massekonvertering

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 filendelse 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 at indlæse, scene.save() til at skrive. Den vigtigste begrænsning at huske er, at FBX-import- og eksportklasser findes, men automatisk formatgenkendelse er endnu ikke implementeret, så FBX-filer ikke kan indlæses via scene.open().

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