Mengonversi Antara Format 3D di TypeScript dengan Aspose.3D FOSS

Pengembang Node.js yang bekerja dengan konten 3D sering kali perlu mengonversi antar format: sebuah alat desain mengekspor OBJ, renderer web mengharapkan GLB, printer 3D memerlukan STL, dan alur produksi manufaktur menggunakan 3MF. Menangani konversi ini dengan satu API yang konsisten mengurangi jumlah alat eksternal dalam alur kerja dan menjaga logika konversi di dalam kode aplikasi sehingga dapat diuji dan diberi versi.

The @aspose/3d paket (v24.12.0, lisensi MIT) menyediakan API TypeScript-first untuk membaca dan menulis semua format 3D utama di Node.js. Panduan ini menjelaskan alur kerja konversi yang paling umum.

Instalasi

npm install @aspose/3d

Persyaratan: Node.js 18, 20, atau 22; TypeScript 5.0 atau lebih baru. Satu-satunya dependensi runtime adalah xmldom.

Format yang Didukung

Tabel di bawah ini mencantumkan format yang dibahas dalam panduan ini serta dukungan baca/tulisnya.

OBJ mendukung impor dan ekspor. Muat dengan scene.open() dan simpan dengan scene.save('output.obj'), atau konversi ke format lain yang didukung seperti glTF, STL, atau 3MF.

OBJ ke GLB (Pengiriman Web)

Mengonversi OBJ ke glTF biner (GLB) adalah alur kerja web yang paling umum. GLB adalah bundel biner yang berdiri sendiri: tekstur, geometri, dan metadata dalam satu file, sehingga efisien untuk pengiriman via 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 disimpulkan dari ekstensi file. Gunakan .glb untuk GLB biner atau .gltf untuk JSON terpisah + .bin layout.

OBJ ke STL (Persiapan Pencetakan 3D)

STL adalah bahasa universal untuk pencetakan 3D FDM dan SLA. Slicer seperti PrusaSlicer, Bambu Studio, dan Chitubox semuanya menerima STL. Mengonversi dari OBJ ke STL sangat mudah karena kedua 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 data warna, material, atau UV. Jika file OBJ Anda menggunakan grup material, informasi tersebut akan dihilangkan saat diekspor. Untuk format cetak yang mempertahankan warna, pertimbangkan 3MF sebagai gantinya (lihat di bawah).

STL ke glTF (Pemindai dan CAD ke Web)

Pemindai structured-light dan ekspor CAD parametrik biasanya menghasilkan STL. Mengonversi ke glTF membuat geometri dapat diakses di penampil berbasis web dan platform AR tanpa langkah rendering di sisi 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');

Karena STL tidak membawa informasi material atau tekstur, file glTF yang dihasilkan hanya akan berisi geometri. Anda dapat menambahkan material secara programatik ke node scene setelah dimuat jika diperlukan.

3MF to glTF (Manufacturing to Visualization)

Format Manufaktur 3D (3MF) semakin banyak digunakan dalam alur kerja manufaktur aditif karena menyimpan warna, material, pohon komponen, dan metadata cetak bersama geometri. Mengonversi 3MF ke glTF memungkinkan visualisasi hilir dalam alat web sambil mempertahankan 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() mempertahankan hierarki komponen dalam scene.rootNode.childNodes, sehingga Anda dapat memeriksa atau memanipulasi bagian individual sebelum menyimpan.

Pola Konversi Batch

Saat memproses direktori berkas, bungkus setiap konversi dalam sebuah try/catch sehingga satu berkas yang rusak tidak menghentikan seluruh batch.

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

Pola di atas membaca setiap ekstensi berkas yang didukung dari direktori input, mengonversi ke GLB, dan mencatat setiap kegagalan tanpa menghentikan loop. Array yang dikembalikan ConversionResult objek dapat digunakan untuk pelaporan atau logika retry.

Kesimpulan

@aspose/3d mencakup seluruh kebutuhan konversi format dalam aplikasi Node.js TypeScript dengan API dua langkah yang konsisten: scene.open() untuk memuat, scene.save() untuk menulis. Kendala utama yang perlu diingat adalah bahwa kelas impor dan ekspor FBX ada tetapi deteksi otomatis format belum dihubungkan, sehingga berkas FBX tidak dapat dimuat melalui scene.open().

Untuk detail lebih lanjut tentang Scene, Node, dan Mesh kelas yang digunakan dalam contoh ini, lihat halaman referensi kelas dalam dokumentasi ini.