تبدیل بین فرمت‌های 3D در TypeScript با Aspose.3D FOSS

توسعه‌دهندگان Node.js که با محتوای 3D کار می‌کنند، اغلب نیاز به تبدیل بین فرمت‌ها دارند: یک ابزار طراحی OBJ را صادر می‌کند، یک رندرکننده وب به GLB نیاز دارد، یک چاپگر 3D به STL نیاز دارد و یک خط تولید از 3MF استفاده می‌کند. مدیریت این تبدیل‌ها با یک API یکتا و سازگار، تعداد ابزارهای خارجی در خط لوله را کاهش می‌دهد و منطق تبدیل را درون کد برنامه نگه می‌دارد، جایی که می‌تواند تست و نسخه‌بندی شود.

این @aspose/3d بسته (v24.12.0، مجوز MIT) یک API مبتنی بر TypeScript برای خواندن و نوشتن تمام فرمت‌های اصلی سه‌بعدی در Node.js فراهم می‌کند. این راهنما جریان‌های کاری رایج تبدیل را قدم به قدم توضیح می‌دهد.

نصب

npm install @aspose/3d

پیش‌نیازها: Node.js 18، 20 یا 22؛ TypeScript 5.0 یا بالاتر. تنها وابستگی زمان اجرا xmldom.

فرمت‌های پشتیبانی‌شده

جدول زیر فرمت‌های پوشش داده شده در این راهنما و پشتیبانی خواندن/نوشتن آن‌ها را فهرست می‌کند.

OBJ هر دو واردات و صادرات را پشتیبانی می‌کند. بارگذاری با scene.open() و ذخیره با scene.save('output.obj'), یا به هر قالب پشتیبانی‌شده دیگری مانند glTF، STL یا 3MF تبدیل کنید.

OBJ به GLB (تحویل وب)

تبدیل OBJ به glTF باینری (GLB) رایج‌ترین جریان کاری وب است. GLB یک بسته باینری خودکفا است: بافت‌ها، هندسه و متادیتا در یک فایل واحد، که آن را برای تحویل HTTP و بارگذاری مستقیم توسط Three.js، Babylon.js و 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');

قالب خروجی از پسوند فایل استنتاج می‌شود. استفاده کنید .glb برای GLB باینری یا .gltf برای JSON جداگانه + .bin layout.

OBJ به STL (آماده‌سازی برای چاپ 3D)

STL زبان مشترک چاپ 3D FDM و SLA است. اسلایسرهایی مانند PrusaSlicer، Bambu Studio و Chitubox همگی STL را می‌پذیرند. تبدیل از OBJ به STL ساده است زیرا هر دو فرمت مش‌های مثلثی را ذخیره می‌کنند.

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 رنگ، ماده یا داده‌های UV را ذخیره نمی‌کند. اگر فایل OBJ شما از گروه‌های ماده استفاده می‌کند، این اطلاعات در زمان صادرات حذف می‌شود. برای فرمت‌های چاپی که رنگ را حفظ می‌کنند، به جای آن 3MF را در نظر بگیرید (به زیر مراجعه کنید).

STL به glTF (اسکنر و CAD به وب)

اسکنرهای نور ساختاریافته و صادرکنندگان CAD پارامتریک معمولاً STL تولید می‌کنند. تبدیل به glTF باعث می‌شود هندسه در نمایشگرهای وب‌محور و پلتفرم‌های AR بدون نیاز به مرحله رندر سمت سرور در دسترس باشد.

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

از آنجا که STL هیچ اطلاعات ماده یا بافتی حمل نمی‌کند، فایل glTF حاصل فقط شامل هندسه خواهد بود. در صورت نیاز می‌توانید پس از بارگذاری، به گره‌های صحنه به‌صورت برنامه‌نویسی مواد را اضافه کنید.

3MF to glTF (Manufacturing to Visualization)

فرمت تولید سه‌بعدی (3MF) به‌طور فزاینده‌ای در جریان‌های کاری ساخت افزودنی استفاده می‌شود زیرا رنگ، مواد، درخت‌های مؤلفه و متادیتای چاپ را همراه با هندسه ذخیره می‌کند. تبدیل 3MF به glTF امکان تجسم پس‌دستی در ابزارهای وب را فراهم می‌کند در حالی که ساختار صحنه حفظ می‌شود.

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() سلسله‌مراتبی مؤلفه‌ها را در scene.rootNode.childNodes, بنابراین می‌توانید قبل از ذخیره‌سازی، بخش‌های فردی را بررسی یا دستکاری کنید.

الگوی تبدیل دسته‌ای

هنگام پردازش یک پوشه از فایل‌ها، هر تبدیل را در یک try/catch به‌طوری‌که یک فایل خراب، کل دسته را متوقف نکند.

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

الگوی بالا هر پسوند فایل پشتیبانی‌شده را از یک پوشه ورودی می‌خواند، به GLB تبدیل می‌کند و هرگونه خطا را بدون توقف حلقه ثبت می‌کند. آرایهٔ بازگشتی از ConversionResult اشیاء می‌توانند برای گزارش‌گیری یا منطق retry استفاده شوند.

نتیجه‌گیری

@aspose/3d تمام نیازهای تبدیل فرمت را در یک برنامه Node.js TypeScript با یک API دو‑مرحله‌ای ثابت پوشش می‌دهد: scene.open() برای بارگذاری،, scene.save() برای نوشتن. محدودیت کلیدی که باید به خاطر داشته باشید این است که کلاس‌های واردکننده و صادرکننده FBX وجود دارند اما تشخیص خودکار فرمت هنوز پیاده‌سازی نشده است، بنابراین فایل‌های FBX نمی‌توانند از طریق scene.open().

برای جزئیات بیشتر دربارهٔ Scene, Node,، و Mesh کلاس‌های استفاده‌شده در این مثال‌ها، صفحه‌های مرجع کلاس‌ها را در این مستندات ببینید.