Conversia între formate 3D în TypeScript cu Aspose.3D FOSS

Dezvoltatorii Node.js care lucrează cu conținut 3D au adesea nevoie să convertească între formate: un instrument de design exportă OBJ, un renderer web așteaptă GLB, o imprimantă 3D necesită STL și o linie de producție utilizează 3MF. Gestionarea acestor conversii cu un API unic și coerent reduce numărul de instrumente externe dintr-un pipeline și păstrează logica de conversie în codul aplicației, unde poate fi testată și versionată.

The @aspose/3d pachetul (v24.12.0, licență MIT) oferă un API orientat pe TypeScript pentru citirea și scrierea tuturor principalelor formate 3D în Node.js. Acest ghid parcurge cele mai comune fluxuri de conversie.

Instalare

npm install @aspose/3d

Cerințe: Node.js 18, 20 sau 22; TypeScript 5.0 sau o versiune ulterioară. Singura dependență la runtime este xmldom.

Formate suportate

Tabelul de mai jos enumeră formatele acoperite în acest ghid și suportul lor de citire/scriere.

OBJ acceptă atât importul, cât și exportul. Încarcă cu scene.open() și salvează cu scene.save('output.obj'), sau convertește în orice alt format suportat, cum ar fi glTF, STL sau 3MF.

OBJ la GLB (Livrare Web)

Conversia OBJ în glTF binar (GLB) este cel mai comun flux de lucru web. GLB este un pachet binar auto-conținut: texturi, geometrie și metadate într-un singur fișier, ceea ce îl face eficient pentru livrarea prin HTTP și încărcarea directă de către Three.js, Babylon.js și 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');

Formatul de ieșire este dedus din extensia fișierului. Folosește .glb pentru GLB binar sau .gltf pentru JSON separat + .bin layout.

OBJ la STL (Pregătire pentru imprimare 3D)

STL este lingua franca a imprimării 3D FDM și SLA. Slicer-ele precum PrusaSlicer, Bambu Studio și Chitubox acceptă toate STL. Conversia din OBJ în STL este simplă deoarece ambele formate stochează rețele de triunghiuri.

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 nu stochează informații despre culoare, material sau date UV. Dacă fișierul tău OBJ folosește grupuri de materiale, aceste informații sunt eliminate în timpul exportului. Pentru formate de imprimare care păstrează culoarea, ia în considerare 3MF în schimb (vezi mai jos).

STL la glTF (Scanner și CAD pentru Web)

Scanerele cu lumină structuratată și exportatoarele CAD parametrice generează în mod obișnuit STL. Conversia în glTF face geometria accesibilă în vizualizatoare web și platforme AR fără un pas de randare pe server.

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

Deoarece STL nu conține informații despre material sau texturi, fișierul glTF rezultat va conține doar geometrie. Poți atașa materiale programatic nodurilor scenei după încărcare, dacă este necesar.

3MF to glTF (Manufacturing to Visualization)

Formatul 3D pentru fabricație (3MF) este utilizat din ce în ce mai mult în fluxurile de lucru de fabricație aditivă deoarece stochează culoarea, materialele, arborii de componente și metadatele de imprimare alături de geometrie. Conversia din 3MF în glTF permite vizualizarea ulterioară în instrumente web, păstrând structura scenei.

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() păstrează ierarhia componentelor în scene.rootNode.childNodes, astfel încât poți inspecta sau manipula părțile individuale înainte de salvare.

Model de conversie în lot

Când procesezi un director de fișiere, învelește fiecare conversie într-un try/catch pentru ca un singur fișier corupt să nu întrerupă întregul lot.

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

Modelul de mai sus citește fiecare extensie de fișier acceptată dintr-un director de intrare, convertește în GLB și înregistrează orice eșecuri fără a opri bucla. Matricea returnată de ConversionResult obiecte poate fi utilizată pentru raportare sau logică de reîncercare.

Concluzie

@aspose/3d acoperă întreaga gamă de nevoi de conversie a formatelor într-o aplicație Node.js TypeScript cu un API consistent în două etape: scene.open() pentru încărcare, scene.save() pentru scriere. Constrângerea cheie de reținut este că există clase de import și export FBX, dar detectarea automată a formatului nu este încă implementată, astfel încât fișierele FBX nu pot fi încărcate prin scene.open().

Pentru mai multe detalii despre Scene, Node, și Mesh clase utilizate în aceste exemple, consultați paginile de referință ale claselor din această documentație.