המרה בין פורמטים תלת‑ממדיים ב‑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 תומך הן בייבוא והן ביצוא. טען עם 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 מאפשרת לגיאומטריה להיות נגישה במציגים מבוססי רשת ופלטפורמות 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 מחלקות המשמשות בדוגמאות אלו, ראה את דפי ההתייחסות למחלקות בתיעוד זה.