המרה בין פורמטים תלת‑ממדיים ב‑TypeScript עם Aspose.3D FOSS

מפתחים ב‑Node.js העובדים עם תוכן תלת‑ממדי צריכים לעתים קרובות להמיר בין פורמטים: כלי עיצוב מייצא OBJ, מנגן אינטרנט מצפה ל‑GLB, מדפסת תלת‑ממד דורשת 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 הוא ייבוא בלבד (canExport: false). כדי להמיר תוכן OBJ לפורמט אחר, טען אותו עם scene.open() ולשמור לפורמט ייצוא נתמך כגון 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 מאפשרת גישה לגאומטריה במציגים מבוססי רשת ופלטפורמות 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 מאפשרת הדמיה במערכות אינטרנטיות במ downstream תוך שמירה על מבנה הסצנה.

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 עם API דו-שלבי עקבי: scene.open() לטעון, scene.save() לכתוב. המגבלה המרכזית לזכור היא שקיימות מחלקות מייבא ויצוא של FBX אך זיהוי אוטומטי של פורמט עדיין לא מחובר, ולכן קבצי FBX אינם ניתנים לטעינה דרך scene.open().

לעוד פרטים על ה- Scene, Node, ו- Mesh מחלקות המשמשות בדוגמאות אלו, ראה את דפי ההתייחסות למחלקות בתיעוד זה.