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

Node.js‑utviklere som jobber med 3D‑innhold må ofte konvertere mellom formater: et designverktøy eksporterer OBJ, en nett‑renderer forventer GLB, en 3D‑printer krever STL, og en produksjons‑pipeline bruker 3MF. Å håndtere disse konverteringene med ett enkelt, konsistent API reduserer antall eksterne verktøy i en pipeline og holder konverteringslogikken inne i applikasjonskoden hvor den kan testes og versjoneres.

Den @aspose/3d pakken (v24.12.0, MIT-lisens) gir et TypeScript‑først API for lesing og skriving av alle større 3D‑formater i Node.js. Denne guiden går gjennom de vanligste konverteringsarbeidsflytene.

Installasjon

npm install @aspose/3d

Krav: Node.js 18, 20 eller 22; TypeScript 5.0 eller nyere. Den eneste kjøretidsavhengigheten er xmldom.

Støttede formater

Tabellen nedenfor viser formatene som dekkes i denne guiden og deres lese-/skrive‑støtte.

OBJ støtter både import og eksport. Last inn med scene.open() og lagre med scene.save('output.obj'), eller konverter til et annet støttet format som glTF, STL eller 3MF.

OBJ til GLB (Web‑levering)

Å konvertere OBJ til binær glTF (GLB) er den mest vanlige web‑arbeidsflyten. GLB er en selvstendig binær pakke: teksturer, geometri og metadata i én fil, noe som gjør den effektiv for HTTP‑levering og direkte lasting av 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');

Utdataformatet blir inferert fra filendelsen. Bruk .glb for binær GLB eller .gltf for den separate JSON + .bin oppsett.

OBJ til STL (Forberedelse for 3D‑utskrift)

STL er lingua franca for FDM‑ og SLA‑3D‑utskrift. Slicere som PrusaSlicer, Bambu Studio og Chitubox godtar alle STL. Å konvertere fra OBJ til STL er enkelt fordi begge formatene lagrer trekantnett.

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 lagrer ikke farge, materiale eller UV‑data. Hvis OBJ‑filen din bruker materialgrupper, blir den informasjonen fjernet ved eksport. For fargebevarende utskriftsformater, vurder 3MF i stedet (se nedenfor).

STL til glTF (Skanner og CAD til Web)

Strukturlys‑skannere og parametriske CAD‑eksportører produserer ofte STL. Å konvertere til glTF gjør geometrien tilgjengelig i nettbaserte visere og AR‑plattformer uten et server‑side render‑steg.

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 inneholder materiale‑ eller teksturinformasjon, vil den resulterende glTF‑filen kun inneholde geometri. Du kan programmessig legge til materialer på scenenoder etter lasting om nødvendig.

3MF to glTF (Manufacturing to Visualization)

3D Manufacturing Format (3MF) blir i økende grad brukt i additive produksjonsarbeidsflyter fordi den lagrer farge, materialer, komponenttrær og utskriftsmetadata sammen med geometrien. Å konvertere 3MF til glTF gjør det mulig med etterfølgende visualisering i nettverktøy samtidig som 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, slik at du kan inspisere eller manipulere individuelle deler før lagring.

Mønster for batchkonvertering

Når du behandler en katalog med filer, pakk hver konvertering inn i en try/catch slik at en enkelt korrupt fil ikke avbryter 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ønsteret ovenfor leser hver støttede filtype fra en inndatakatalog, konverterer til GLB, og logger eventuelle feil uten å stoppe løkken. Den returnerte matrisen av ConversionResult objekter kan brukes til rapportering eller gjenforsøklogikk.

Konklusjon

@aspose/3d dekker hele spekteret av formatkonverteringsbehov i en Node.js TypeScript-applikasjon med et konsistent to-trinns API: scene.open() å laste, scene.save() å skrive. Den viktigste begrensningen å huske er at FBX-importør- og eksportørklasser finnes, men automatisk formatgjenkjenning er ennå ikke implementert, så FBX-filer kan ikke lastes via scene.open().

For mer detalj om Scene, Node, og Mesh klasser som brukes i disse eksemplene, se klassereferansesidene i denne dokumentasjonen.