3D-muotojen muuntaminen TypeScriptissä Aspose.3D FOSS:n avulla

Node.js -kehittäjät, jotka työskentelevät 3D-sisällön parissa, tarvitsevat usein muuntaa formaattien välillä: suunnittelutyökalu vie OBJ:n, web-renderöijä odottaa GLB:tä, 3D-tulostin vaatii STL:n ja valmistusputki käyttää 3MF:tä. Näiden muunnosten käsitteleminen yhdellä, yhtenäisellä API:lla vähentää ulkoisten työkalujen määrää putkessa ja pitää muunnoslogiikan sovelluskoodin sisällä, missä se voidaan testata ja versioida.

Se @aspose/3d paketti (v24.12.0, MIT-lisenssi) tarjoaa TypeScript‑ensimmäisen API:n kaikkien tärkeimpien 3D-muotojen lukemiseen ja kirjoittamiseen Node.js:ssä. Tämä opas käy läpi yleisimmät muunnostyötavat.

Asennus

npm install @aspose/3d

Vaatimukset: Node.js 18, 20 tai 22; TypeScript 5.0 tai uudempi. Ainoa ajonaikainen riippuvuus on xmldom.

Tuetut tiedostomuodot

Alla oleva taulukko luettelee oppaassa käsitellyt formaatit ja niiden luku-/kirjoitustuen.

OBJ tukee sekä tuontia että vientiä. Lataa käyttäen scene.open() ja tallenna käyttäen scene.save('output.obj'), tai muunna mihin tahansa muuhun tuettuun formaattiin, kuten glTF, STL, tai 3MF.

OBJ → GLB (Web-toimitus)

OBJ:n muuntaminen binaariksi glTF:ksi (GLB) on yleisin web-työnkulku. GLB on itsenäinen binaarinen paketti: tekstuurit, geometria ja metatiedot yhdessä tiedostossa, mikä tekee siitä tehokkaan HTTP-toimitukseen ja suoraan Three.js:n, Babylon.js:n ja model-viewer:n lataukseen.

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

Tulostusformaatti päätellään tiedostopäätteestä. Käytä .glb binääriselle GLB:lle tai .gltf erilliselle JSON + .bin asettelu.

OBJ → STL (3D-tulostuksen valmistelu)

STL on FDM- ja SLA‑3D-tulostuksen lingua franca. PrusaSlicer, Bambu Studio ja Chitubox -ohjelmat kaikki hyväksyvät STL:n. OBJ:n muuntaminen STL:ksi on suoraviivaista, koska molemmat formaatit tallentavat kolmioverkot.

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 ei tallenna väri‑, materiaali‑ tai UV‑tietoja. Jos OBJ‑tiedostosi käyttää materiaaliryhmiä, nämä tiedot poistetaan viennissä. Väriä säilyttävien tulostusformaattien osalta harkitse sen sijaan 3MF:ää (katso alapuolelta).

STL → glTF (Skanneri- ja CAD‑webiin)

Rakennevalon skannerit ja parametriset CAD‑vientiohjelmat tuottavat yleisesti STL:n. Muuntaminen glTF:ksi tekee geometriasta saatavilla olevan web-pohjaisissa katseluohjelmissa ja AR-alustoilla ilman palvelinpuolen renderöintivaihetta.

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

Koska STL ei sisällä materiaali‑ tai tekstuuritietoja, syntyvä glTF‑tiedosto sisältää vain geometrian. Tarvittaessa voit liittää materiaaleja ohjelmallisesti kohtausnodeihin latauksen jälkeen.

3MF to glTF (Manufacturing to Visualization)

3D Manufacturing Format (3MF) on yhä useammin käytössä lisävalmistusprosessien työnkuluissa, koska se tallentaa värit, materiaalit, komponenttipuut ja tulostusmetatiedot geometrian ohella. 3MF:n muuntaminen glTF:ksi mahdollistaa jatkokehityksen visualisoinnin web-työkaluissa säilyttäen samalla skenen rakenteen.

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() säilyttää komponenttihierarkian kohteessa scene.rootNode.childNodes, joten voit tarkastella tai muokata yksittäisiä osia ennen tallentamista.

Erämuunnoksen malli

Kun käsitellään tiedostokansiota, kääri jokainen muunnos try/catch jotta yksi vioittunut tiedosto ei keskeytä koko erää.

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

Yllä oleva malli lukee kunkin tuetun tiedostopäätteen syötekansiosta, muuntaa GLB-muotoon ja kirjaa mahdolliset epäonnistumiset pysäyttämättä silmukkaa. Palautettu taulukko ConversionResult objekteja voidaan käyttää raportointiin tai uudelleenyrityslogiikkaan.

Yhteenveto

@aspose/3d kattaa koko valikoiman formaattimuunnostarpeita Node.js TypeScript -sovelluksessa, jossa on johdonmukainen kaksivaiheinen API: scene.open() lataamiseen, scene.save() kirjoittamiseen. Keskeinen rajoitus, joka on muistettava, on että FBX-tuonti- ja vientiluokat ovat olemassa, mutta formaatin automaattinen tunnistus ei ole vielä kytketty, joten FBX-tiedostoja ei voida ladata scene.open().

Lisätietoja Scene, Node, ja Mesh esimerkeissä käytetyistä luokista, katso luokkiin viittaavat sivut tässä dokumentaatiossa.