Konvertera mellan 3D-format i TypeScript med Aspose.3D FOSS

Node.js‑utvecklare som arbetar med 3D‑innehåll behöver ofta konvertera mellan format: ett designverktyg exporterar OBJ, en webb‑renderare förväntar sig GLB, en 3D‑skrivare kräver STL och en tillverkningspipeline använder 3MF. Att hantera dessa konverteringar med ett enda, konsekvent API minskar antalet externa verktyg i en pipeline och håller konverteringslogiken i applikationskoden där den kan testas och versioneras.

Den @aspose/3d paketet (v24.12.0, MIT-licens) tillhandahåller ett TypeScript‑först API för att läsa och skriva alla större 3D-format i Node.js. Denna guide går igenom de vanligaste konverteringsarbetsflödena.

Installation

npm install @aspose/3d

Krav: Node.js 18, 20 eller 22; TypeScript 5.0 eller senare. Den enda körningsberoendet är xmldom.

Stödda format

Tabellen nedan listar de format som behandlas i denna guide samt deras läs‑/skrivstöd.

Obs: OBJ är endast för import (canExport: false). För att konvertera OBJ-innehåll till ett annat format, läs in det med scene.open() och spara till ett stödd exportformat såsom glTF, STL eller 3MF.

OBJ till GLB (Webbleverans)

Att konvertera OBJ till binär glTF (GLB) är det vanligaste webb‑arbetsflödet. GLB är ett självständigt binärt paket: texturer, geometri och metadata i en enda fil, vilket gör det effektivt för HTTP‑leverans och direkt inläsning av Three.js, Babylon.js och 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');

Utdataformatet härleds från filändelsen. Använd .glb för binär GLB eller .gltf för den separata JSON + .bin layout.

OBJ till STL: Förbereda en modell för 3D-utskrift

STL är lingua franca för FDM‑ och SLA‑3D‑utskrift. Skivningsprogram som PrusaSlicer, Bambu Studio och Chitubox accepterar alla STL. Att konvertera från OBJ till STL är enkelt eftersom båda formaten lagrar triangulära meshar.

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 lagrar inte färg, material eller UV‑data. Om din OBJ‑fil använder materialgrupper tas den informationen bort vid export. För färgbevarande utskriftsformat, överväg 3MF istället (se nedan).

STL till glTF: Från skanner‑ eller CAD‑utdata till webben

Strukturerade ljusskannrar och parametriska CAD‑exportörer levererar ofta STL. Att konvertera till glTF gör geometrin tillgänglig i webbaserade visare och AR‑plattformar utan ett server‑baserat renderingssteg.

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

Eftersom STL inte innehåller material- eller texturinformation, kommer den resulterande glTF-filen endast att innehålla geometri. Du kan programatiskt fästa material på scenens noder efter inläsning om så behövs.

3MF to glTF (Manufacturing to Visualization)

3D Manufacturing Format (3MF) används i allt större utsträckning i additiv tillverkningsarbetsflöden eftersom det lagrar färg, material, komponentträd och utskriftsmetadata tillsammans med geometri. Att konvertera 3MF till glTF möjliggör efterföljande visualisering i webbaserade verktyg samtidigt som scenstrukturen bevaras.

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() bevarar komponenthierarkin i scene.rootNode.childNodes, så att du kan inspektera eller manipulera enskilda delar innan du sparar.

Mönster för batchkonvertering

När du bearbetar en katalog med filer, omslut varje konvertering i en try/catch så att en enda korrupt fil inte avbryter hela 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 ovan läser varje stödd filändelse från en inmatningskatalog, konverterar till GLB och loggar eventuella fel utan att stoppa loopen. Den returnerade arrayen av ConversionResult objekt kan användas för rapportering eller återförsökslogik.

Slutsats

@aspose/3d täcker hela spektrumet av formatkonverteringsbehov i en Node.js TypeScript-applikation med ett konsekvent tvåstegs-API: scene.open() för att läsa in, scene.save() för att skriva. Den viktigaste begränsningen att komma ihåg är att FBX-importör- och exportörklasser finns men automatisk formatdetektering ännu inte är implementerad, så FBX-filer kan inte läsas via scene.open().

För mer detaljer om Scene, Node, och Mesh klasser som används i dessa exempel, se klassreferenssidorna i den här dokumentationen.