איך לייצא סצנות תלת‑ממד ל‑glTF/GLB ב‑TypeScript

Aspose.3D FOSS תומך ב‑glTF 2.0 הן כפורמט ייבוא והן כפורמט יצוא. אותו אובייקט Scene ניתן למלא מקובץ OBJ, FBX, STL, או קובץ מקור אחר ולאחר מכן לכתוב ל‑.gltf (JSON + בינארי חיצוני) או ל‑.glb (מכולה בינארית יחידה) על‑ידי הגדרת דגל אחד ב‑GltfSaveOptions.

מדריך שלב אחר שלב

שלב 1: התקן @aspose/3d

npm install @aspose/3d

אשר ש‑Node.js 18 או גרסה מאוחרת יותר פעילה:

node --version   # must be >= 16.0.0

שלב 2: ייבא Scene, GltfSaveOptions, ו‑GltfFormat

import { Scene } from '@aspose/3d';
import { GltfSaveOptions, GltfFormat } from '@aspose/3d/formats/gltf';

GltfFormat הוא מתאר הפורמט שמועבר לscene.save(). GltfSaveOptions נושא את כל תצורת הייצוא.

אם אתה גם טוען קובץ מקור (למשל, OBJ), ייבא את אפשרויות הטעינה המתאימות:

import { ObjLoadOptions } from '@aspose/3d/formats/obj';

שלב 3: בנייה או טעינת סצנה

אפשרות A: טעינה מקובץ קיים (OBJ → GLB המרה):

import { Scene } from '@aspose/3d';
import { ObjLoadOptions } from '@aspose/3d/formats/obj';
import { GltfSaveOptions, GltfFormat } from '@aspose/3d/formats/gltf';

const scene = new Scene();
scene.open('model.obj', new ObjLoadOptions());

אפשרות B: בנה סצנה מינימלית באופן תכנותי:

import { Scene, Node, Mesh } from '@aspose/3d';
import { GltfSaveOptions, GltfFormat } from '@aspose/3d/formats/gltf';

const scene = new Scene();
const childNode = new Node('cube');
scene.rootNode.addChildNode(childNode);
// Attach geometry to childNode as needed

שלב 4: הגדר GltfSaveOptions

GltfSaveOptions שולט בפורמט הפלט ובפרטי הקידוד.

const saveOpts = new GltfSaveOptions();

// Set to true for a single binary .glb file
// Set to false (default) for JSON .gltf + separate .bin
saveOpts.binaryMode = true;

אפשרויות נוספות שניתן להגדיר:

מאפיין	סוג	ברירת מחדל	השפעה
`binaryMode`	`boolean`	`false`	`true` → GLB, `false` → glTF JSON
`flipTexCoordV`	`boolean`	`true`	הפוך את ציר ה‑UV האנכי לתאימות למנוע

שלב 5: שמור באמצעות scene.save()

העבר את נתיב הפלט, את המתאר GltfFormat, ואת האפשרויות המוגדרות:

import { Scene } from '@aspose/3d';
import { ObjLoadOptions } from '@aspose/3d/formats/obj';
import { GltfSaveOptions, GltfFormat } from '@aspose/3d/formats/gltf';

const scene = new Scene();
scene.open('model.obj', new ObjLoadOptions());

const saveOpts = new GltfSaveOptions();
saveOpts.binaryMode = true;   // produce .glb

scene.save('output.glb', GltfFormat.getInstance(), saveOpts);
console.log('Converted to GLB successfully');

כדי לייצר קובץ JSON .gltf במקום זאת:

saveOpts.binaryMode = false;
scene.save('output.gltf', GltfFormat.getInstance(), saveOpts);
console.log('Exported to glTF JSON successfully');

שלב 6: אמת את קובץ הפלט

בדוק שהקובץ הפלט קיים ושגודלו אינו אפס:

import * as fs from 'fs';

const outputPath = 'output.glb';
const stats = fs.statSync(outputPath);
console.log(`Output file size: ${stats.size} bytes`);

if (stats.size === 0) {
    throw new Error('Export produced an empty file: check scene content');
}

לאימות נסיעה הלוך ושוב, טען מחדש את קובץ ה‑GLB ובדוק את מספר הצמתים:

import { Scene } from '@aspose/3d';
import { GltfLoadOptions } from '@aspose/3d/formats/gltf';

const verify = new Scene();
verify.open('output.glb', new GltfLoadOptions());

let nodeCount = 0;
function countNodes(node: any): void {
    nodeCount++;
    for (const child of node.childNodes) countNodes(child);
}
countNodes(verify.rootNode);

console.log(`Round-trip verification: ${nodeCount} node(s) in output`);

בעיות נפוצות ותיקונים

קובץ חומר OBJ לא נמצא לאחר הייצוא
כאשר שומרים ל‑OBJ דרך scene.save('output.obj'), קובץ החומר .mtl נכתב לצד קובץ .obj באופן אוטומטי. ודאו שהספרייה הפלטית ניתנת לכתיבה וששני הקבצים נשמרים יחד.

פלט .glb קטן מהצפוי / רשתות חסרות
אם הסצנה הטעונה מכילה צמתים ללא ישויות (למשל, קבוצות ריקות מקובץ OBJ), ה‑GLB לא יכלול את הגאומטריה של הצמתים האלה. ודא שקובץ הקלט שלך מכיל נתוני פוליגון אמיתיים באמצעות mesh.controlPoints.length > 0 לפני השמירה.

לא ניתן למצוא מודול ‘@aspose/3d/formats/gltf’ ודא שאתה משתמש ב-Node.js 18+ וש-@aspose/3d מותקן באותו node_modules של נקודת הכניסה שלך. הפעל npm ls @aspose/3d כדי לאשר שהגרסה היא 24.12.0 או מאוחרת יותר.

GltfFormat.getInstance() מחזיר undefined
זה מצביע על חוסר התאמה בגרסה בין חבילת @aspose/3d הראשית לגרסה ישנה במטמון. מחק את node_modules ו‑package-lock.json, ואז הפעל שוב את npm install.

המרקמים חסרים בקובץ ה‑GLB המפלט
ודא ש-binaryMode = true מוגדר לייצר GLB עצמאי. עבור פלט JSON של glTF, קבצי תמונת המרקמים חייבים להיות נוכחים לצד קובץ הפלט מכיוון שהם מצוינים בנתיב יחסי.

שגיאת סוג: ארגומנט מסוג ‘GltfSaveOptions’ אינו ניתן להצבה
ודא ששני Scene ו-GltfSaveOptions מיובאים מאותו מופע חבילה מותקנת. התקנות משולבות (גלובליות + מקומיות) יכולות לגרום לחוסר התאמה בממשק.

שאלות נפוצות (FAQ)

מה ההבדל בין glTF ל‑GLB?
glTF 2.0 JSON (.gltf) מאחסן את גרף הסצנה כקובץ JSON קריא לבני אדם עם מאגרי .bin נפרדים וקבצי תמונה. GLB (.glb) אורז את הכל במכולה בינארית אחת. הגדר binaryMode = true עבור GLB, false עבור JSON glTF.

האם אני יכול לייצא סצנה שנבנתה לחלוטין בקוד (ללא קובץ מקור)?
כן. צור Scene, הוסף אובייקטים Node, חבר Mesh או ישויות אחרות, ואז קרא scene.save(). הסצנה אינה צריכה לנבוע מקובץ טעון.

האם ייצוא glTF חסר אובדן?
לגיאומטריה ולטרנספורמציות, כן. חומרים ממופים לתכונות החומר של glTF PBR כאשר אפשר. הרחבות חומרים קנייניות של FBX עשויות שלא לחזור בצורה מושלמת.

האם אני יכול לייצא ל‑STL או 3MF במקום? כן. התבנית זהה; ייבא את *SaveOptions ו‑*Format.getInstance() של הפורמט המתאים:

import { StlSaveOptions, StlFormat } from '@aspose/3d/formats/stl';
const opts = new StlSaveOptions();
scene.save('output.stl', StlFormat.getInstance(), opts);

האם scene.save() פועל באופן אסינכרוני?
לא. scene.save() הוא סינכרוני. עטוף אותו בחוט עובד אם אתה צריך למנוע חסימת לולאת האירועים במהלך ייצוא גדול.

אילו גרסאות של Node.js נתמכות? Node.js 18, 20, ו‑22+. Node.js 16 וקודמות לה אינן נתמכות.