Menukar Antara Format 3D dalam TypeScript dengan Aspose.3D FOSS

Pemaju Node.js yang bekerja dengan kandungan 3D kerap perlu menukar antara format: alat reka bentuk mengeksport OBJ, penyaji web menjangka GLB, pencetak 3D memerlukan STL, dan saluran pengilangan menggunakan 3MF. Mengendalikan penukaran ini dengan API tunggal yang konsisten mengurangkan bilangan alat luaran dalam saluran kerja dan mengekalkan logik penukaran di dalam kod aplikasi di mana ia boleh diuji dan diuruskan versi.

The @aspose/3d paket (v24.12.0, lesen MIT) menyediakan API TypeScript-pertama untuk membaca dan menulis semua format 3D utama dalam Node.js. Panduan ini melangkah melalui aliran kerja penukaran yang paling umum.

Pemasangan

npm install @aspose/3d

Keperluan: Node.js 18, 20, atau 22; TypeScript 5.0 atau lebih baru. Satu-satunya kebergantungan masa jalan ialah xmldom.

Format yang Disokong

Jadual di bawah menyenaraikan format yang dibincangkan dalam panduan ini serta sokongan baca/tulis mereka.

Nota: OBJ hanya import (canExport: false). Untuk menukar kandungan OBJ ke format lain, muatkan ia dengan scene.open() dan simpan ke format eksport yang disokong seperti glTF, STL, atau 3MF.

OBJ ke GLB (Penghantaran Web)

Menukar OBJ ke glTF binari (GLB) adalah aliran kerja web yang paling umum. GLB ialah pek binari berdiri sendiri: tekstur, geometri, dan metadata dalam satu fail, yang menjadikannya cekap untuk penghantaran HTTP dan pemuatan langsung oleh Three.js, Babylon.js, dan 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');

Format output diandaikan daripada sambungan fail. Gunakan .glb untuk GLB binari atau .gltf untuk JSON berasingan + .bin susun atur.

OBJ ke STL: Menyediakan Model untuk Percetakan 3D

STL ialah lingua franca pencetakan 3D FDM dan SLA. Penylicer seperti PrusaSlicer, Bambu Studio, dan Chitubox semua menerima STL. Menukar dari OBJ ke STL adalah mudah kerana kedua-dua format menyimpan mesh segitiga.

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 tidak menyimpan warna, bahan, atau data UV. Jika fail OBJ anda menggunakan kumpulan bahan, maklumat tersebut dibuang semasa eksport. Untuk format cetakan yang mengekalkan warna, pertimbangkan 3MF sebagai gantinya (lihat di bawah).

STL ke glTF: Dari Output Pengimbas atau CAD ke Web

Pengimbas cahaya berstruktur dan pengeksport CAD parametrik biasanya menghasilkan STL. Menukar ke glTF menjadikan geometri dapat diakses dalam penonton berasaskan web dan platform AR tanpa langkah rendering sisi pelayan.

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

Kerana STL tidak membawa maklumat bahan atau tekstur, fail glTF yang terhasil hanya akan mengandungi geometri. Anda boleh melampirkan bahan secara programatik kepada nod adegan selepas dimuatkan jika diperlukan.

3MF to glTF (Manufacturing to Visualization)

Format Pembuatan 3D (3MF) semakin banyak digunakan dalam aliran kerja pembuatan tambahan kerana ia menyimpan warna, bahan, pokok komponen, dan metadata cetakan bersama geometri. Menukar 3MF ke glTF membolehkan visualisasi seterusnya dalam alat web sambil mengekalkan struktur adegan.

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() mengekalkan hierarki komponen dalam scene.rootNode.childNodes, jadi anda boleh memeriksa atau memanipulasi bahagian individu sebelum menyimpan.

Corak Penukaran Pukal

Apabila memproses direktori fail, balut setiap penukaran dalam satu try/catch supaya satu fail rosak tidak menghentikan keseluruhan kumpulan.

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

Corak di atas membaca setiap sambungan fail yang disokong daripada direktori input, menukar kepada GLB, dan mencatat sebarang kegagalan tanpa menghentikan gelung. Array yang dikembalikan ConversionResult objek boleh digunakan untuk pelaporan atau logik percubaan semula.

Kesimpulan

@aspose/3d meliputi seluruh keperluan penukaran format dalam aplikasi Node.js TypeScript dengan API dua langkah yang konsisten: scene.open() untuk memuatkan, scene.save() untuk menulis. Kekangan utama yang perlu diingat ialah kelas import dan eksport FBX wujud tetapi pengesanan automatik format belum disambungkan, jadi fail FBX tidak dapat dimuatkan melalui scene.open().

Untuk maklumat lebih lanjut mengenai Scene, Node, dan Mesh kelas yang digunakan dalam contoh ini, lihat halaman rujukan kelas dalam dokumentasi ini.