تحويل بين صيغ 3D في TypeScript باستخدام Aspose.3D FOSS

غالبًا ما يحتاج مطورو Node.js الذين يعملون مع محتوى ثلاثي الأبعاد إلى تحويل الصيغ: أداة التصميم تُصدّر OBJ، ومُعالج الويب يتوقع GLB، وطابعة 3D تتطلب STL، وخط إنتاج التصنيع يستخدم 3MF. معالجة هذه التحويلات باستخدام واجهة برمجة تطبيقات واحدة ومتسقة تقلل عدد الأدوات الخارجية في خط الأنابيب وتبقي منطق التحويل داخل كود التطبيق حيث يمكن اختباره وإصدار إصداراته.

ال @aspose/3d الحزمة (v24.12.0، رخصة MIT) توفر واجهة برمجة تطبيقات TypeScript‑first لقراءة وكتابة جميع صيغ 3D الرئيسية في 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 التخطيط.

OBJ إلى STL (تحضير للطباعة ثلاثية الأبعاد)

STL هو اللغة المشتركة للطباعة ثلاثية الأبعاد بتقنيتي 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 يجعل الهندسة متاحة في عارضات الويب ومنصات الواقع المعزز دون خطوة تصيير على الخادم.

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 الكائنات يمكن استخدامها للتقارير أو منطق إعادة المحاولة.

الخاتمة

@aspose/3d يغطي النطاق الكامل لاحتياجات تحويل الصيغ في تطبيق Node.js TypeScript مع واجهة برمجة تطبيقات ذات خطوتين متسقة: scene.open() للتحميل،, scene.save() للكتابة. القيد الرئيسي الذي يجب تذكره هو أن فئات مستورد ومصدّر FBX موجودة لكن الكشف التلقائي عن الصيغة لم يُربط بعد، لذا لا يمكن تحميل ملفات FBX عبر scene.open().

لمزيد من التفاصيل حول Scene, Node, و Mesh الفئات المستخدمة في هذه الأمثلة، راجع صفحات مرجع الفئات في هذه الوثائق.