Pretvaranje između 3D formata u TypeScriptu s Aspose.3D FOSS

Node.js programeri koji rade s 3D sadržajem često moraju pretvarati između formata: alat za dizajn izvozi OBJ, web renderere očekuju GLB, 3D pisač zahtijeva STL, a proizvodna linija koristi 3MF. Obrada tih konverzija pomoću jedinstvenog, dosljednog API‑ja smanjuje broj vanjskih alata u pipelineu i zadržava logiku konverzije unutar koda aplikacije gdje se može testirati i verzionirati.

The @aspose/3d paket (v24.12.0, MIT licenca) pruža TypeScript‑prvo API za čitanje i pisanje svih glavnih 3D formata u Node.js. Ovaj vodič prolazi kroz najčešće radne tokove konverzije.

Instalacija

npm install @aspose/3d

Zahtjevi: Node.js 18, 20 ili 22; TypeScript 5.0 ili noviji. Jedina runtime ovisnost je xmldom.

Podržani formati

Tablica ispod navodi formate pokrivene u ovom vodiču i njihovu podršku za čitanje/pisanje.

OBJ podržava i uvoz i izvoz. Učitajte s scene.open() i spremite s scene.save('output.obj'), ili pretvorite u bilo koji drugi podržani format poput glTF, STL ili 3MF.

OBJ u GLB (Web isporuka)

Pretvaranje OBJ u binarni glTF (GLB) najčešći je web radni tok. GLB je samostalni binarni paket: teksture, geometrija i metapodaci u jednoj datoteci, što ga čini učinkovitim za HTTP isporuku i izravno učitavanje u 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');

Izlazni format se zaključuje iz ekstenzije datoteke. Upotrijebite .glb za binarni GLB ili .gltf za odvojeni JSON + .bin raspored.

OBJ u STL (Priprema za 3D ispis)

STL je lingua franca FDM i SLA 3D ispisa. Slicer programi poput PrusaSlicer, Bambu Studio i Chitubox prihvaćaju STL. Pretvaranje iz OBJ u STL je jednostavno jer oba formata pohranjuju trokutne mreže.

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 ne pohranjuje boju, materijal ili UV podatke. Ako vaša OBJ datoteka koristi grupiranje materijala, te informacije se gube pri izvozu. Za formate ispisa koji očuvavaju boju, razmotrite 3MF (vidi dolje).

STL u glTF (Skener i CAD za Web)

Skeneri s strukturiranim svjetlom i parametrijski CAD izvoznici najčešće generiraju STL. Pretvaranje u glTF čini geometriju dostupnom u web‑baziranim preglednicima i AR platformama bez koraka renderiranja na poslužitelju.

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

Budući da STL ne nosi informacije o materijalu ili teksturi, rezultirajuća glTF datoteka će sadržavati samo geometriju. Po potrebi možete programatski dodati materijale čvorovima scene nakon učitavanja.

3MF to glTF (Manufacturing to Visualization)

3D Manufacturing Format (3MF) sve se više koristi u radnim tokovima aditivne proizvodnje jer pohranjuje boju, materijale, hijerarhiju komponenti i metapodatke ispisa uz geometriju. Pretvaranje 3MF u glTF omogućuje downstream vizualizaciju u web alatima uz očuvanje strukture scene.

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() čuva hijerarhiju komponenti u scene.rootNode.childNodes, tako da možete pregledati ili manipulirati pojedinačnim dijelovima prije spremanja.

Uzorak za grupnu konverziju

Pri obradi direktorija datoteka, umotajte svaku konverziju u try/catch tako da jedna oštećena datoteka ne prekine cijelu seriju.

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

Gornji uzorak čita svako podržano ekstenziju datoteke iz ulaznog direktorija, pretvara u GLB i bilježi sve neuspjehe bez zaustavljanja petlje. Vraćeni niz ConversionResult objekata može se koristiti za izvještavanje ili logiku ponovnog pokušaja.

Zaključak

@aspose/3d pokriva cijeli raspon potreba za konverzijom formata u Node.js TypeScript aplikaciji s dosljednim dvo‑korakom API‑ja: scene.open() za učitavanje, scene.save() za pisanje. Ključno ograničenje koje treba zapamtiti je da klase za uvoz i izvoz FBX‑a postoje, ali automatsko otkrivanje formata još nije implementirano, pa se FBX datoteke ne mogu učitati putem scene.open().

Za više detalja o Scene, Node, Mesh klasa korištenih u ovim primjerima, pogledajte stranice referenci klasa u ovoj dokumentaciji.