טעינת מודלים תלת‑ממדיים
@aspose/3d מספקת שתי שיטות טעינה על ה Scene מחלקה: open() לטעינה באמצעות נתיב קובץ ו openFromBuffer() לנתונים בזיכרון. זיהוי הפורמט מתבצע אוטומטית ממספרי הקסם הבינאריים או מהרחבת הקובץ, ולכן כמעט ולא צריך לציין במפורש את פורמט המקור במפורש.
טעינה ממסלול קובץ
העבר את מחרוזת נתיב הקובץ ל scene.open(). הספרייה מזהה את הפורמט מהרחבת הקובץ ו, עבור פורמטים בינאריים, ממספרי הקסם:
import { Scene } from '@aspose/3d';
const scene = new Scene();
scene.open('model.fbx');
console.log(`Root children: ${scene.rootNode.childNodes.length}`);
console.log(`Animation clips: ${scene.animationClips.length}`);open() מחליפה כל תוכן סצנה קיים. אם אתה צריך לטעון קבצים מרובים, צור נפרדים Scene מופעים.
טעינת OBJ עם חומרים
קבצי OBJ מתייחסים לחומרים דרך קובץ צדדי .mtl קובץ. טעינת חומרים היא מופעלת כברירת מחדל (ObjLoadOptions.enableMaterials = true). העבר ObjLoadOptions כדי לשלוט בזה ובאפשרויות טעינה אחרות:
import { Scene } from '@aspose/3d';
import { ObjLoadOptions } from '@aspose/3d/formats/obj';
const scene = new Scene();
const options = new ObjLoadOptions();
options.enableMaterials = true; // load the .mtl sidecar
options.flipCoordinateSystem = false; // keep original Y-up orientation
options.normalizeNormal = true; // fix degenerate normals
options.scale = 1.0; // unit scale multiplier
scene.open('character.obj', options);
// Inspect materials on the first node
const first = scene.rootNode.childNodes[0];
if (first) {
console.log(`Materials on ${first.name}: ${first.materials.length}`);
}טעינה ממאגר
השתמש ב openFromBuffer() כאשר נתוני הקובץ כבר בזיכרון, למשל משאילתת HTTP, BLOB של מסד נתונים, או חילוץ מארכיון zip. זה מונע כתיבה לדיסק:
import { Scene } from '@aspose/3d';
import { ObjLoadOptions } from '@aspose/3d/formats/obj';
import * as fs from 'fs';
const buffer: Buffer = fs.readFileSync('model.obj');
const scene = new Scene();
const options = new ObjLoadOptions();
options.enableMaterials = true;
scene.openFromBuffer(buffer, options);
console.log(`Loaded ${scene.rootNode.childNodes.length} root nodes`);עבור פורמטים בינאריים (GLB, STL binary, 3MF), הספרייה קוראת את מספרי הקסם מהבופר כדי לזהות את הפורמט אוטומטית, ולכן אתה יכול להעביר undefined כארגומנט של האפשרויות:
import { Scene } from '@aspose/3d';
import * as fs from 'fs';
const glbBuffer: Buffer = fs.readFileSync('model.glb');
const scene = new Scene();
scene.openFromBuffer(glbBuffer); // format auto-detected from GLB magic bytes
טעינה מ-HTTP (Node.js 18+)
הורד נכס מרוחק וטעון אותו מבלי לגעת במערכת הקבצים:
import { Scene } from '@aspose/3d';
async function loadFromUrl(url: string): Promise<Scene> {
const response = await fetch(url);
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const arrayBuffer = await response.arrayBuffer();
const buffer = Buffer.from(arrayBuffer);
const scene = new Scene();
scene.openFromBuffer(buffer);
return scene;
}
const scene = await loadFromUrl('https://example.com/model.glb');
console.log(`Loaded scene: ${scene.rootNode.childNodes.length} root nodes`);בדיקת הסצנה הטעונה
לאחר הטעינה, עבור על גרף הסצנה כדי למנות צמתים ולזהות גאומטריה:
import { Scene, Mesh, Node } from '@aspose/3d';
const scene = new Scene();
scene.open('model.fbx');
function inspect(node: Node, depth: number = 0): void {
const indent = ' '.repeat(depth);
const entityType = node.entity ? node.entity.constructor.name : '(none)';
console.log(`${indent}${node.name} [${entityType}]`);
if (node.entity instanceof Mesh) {
const mesh = node.entity as Mesh;
console.log(`${indent} vertices: ${mesh.controlPoints.length}, polygons: ${mesh.polygonCount}`);
}
for (const child of node.childNodes) {
inspect(child, depth + 1);
}
}
inspect(scene.rootNode);קריאת מטא-נתוני נכס
ה assetInfo המאפיין חושף מטא-נתונים ברמת הקובץ:
import { Scene } from '@aspose/3d';
const scene = new Scene();
scene.open('model.fbx');
const info = scene.assetInfo;
if (info) {
console.log(`Creator: ${info.creator}`);
console.log(`Unit name: ${info.unitName}`);
console.log(`Unit scale: ${info.unitScaleFactor}`);
}לא כל הפורמטים ממלאים assetInfo. FBX ו‑COLLADA כוללים מטא‑נתונים עשירים; OBJ ו‑STL בדרך כלל אינם כוללים כאלה.
הפניות לאפשרויות טעינה ספציפיות לפורמט
| פורמט | מחלקת אפשרויות | נתיב ייבוא | אפשרויות מפתח |
|---|---|---|---|
| OBJ | ObjLoadOptions | @aspose/3d/formats/obj | enableMaterials, flipCoordinateSystem, scale, normalizeNormal |
| glTF / GLB | (לא נדרש) | N/A | זוהה אוטומטית; אין צורך במחלקת אפשרויות |
| STL | StlLoadOptions | @aspose/3d/formats/stl | (אין אפשרויות ניתנות להגדרה בגרסה הנוכחית) |
| FBX | FbxLoadOptions | @aspose/3d/formats/fbx | (אין אפשרויות ניתנות להגדרה בגרסה הנוכחית) |
| COLLADA | ColladaLoadOptions | @aspose/3d/formats/collada | (אין אפשרויות ניתנות להגדרה בגרסה הנוכחית) |
| 3MF | (לא נדרש) | N/A | זוהה אוטומטית |
שגיאות טעינה נפוצות
| תסמין | סיבה | תיקון |
|---|---|---|
Error: Cannot find module '@aspose/3d/formats/obj' | moduleResolution לא הוגדר ל node | הוסף "moduleResolution": "node" ל tsconfig.json |
| רשימת צמתים ריקה לאחר טעינת OBJ | .mtl ה‑sidecar חסר או enableMaterials לא הוגדר | הגדר options.enableMaterials = true וודא .mtl באותו תיקייה |
הסצנה נטענת אך rootNode.childNodes ריקה | הפורמט משתמש ברשת שורש יחידה, לא בצמתים משניים | גישה scene.rootNode.entity ישירות |
openFromBuffer זורק עם STL בינארי | ה‑buffer נחתך באופן שגוי (בייטים נגררים חסרים) | השתמש במלוא readFileSync() הפלט ללא חיתוך |
| מערך קטעי האנימציה ריק לאחר טעינת FBX | קובץ FBX משתמש בהמרות מבושלות, ולא בקטעים | האנימציה מתבצעת לכל פריים; מערך הקליפ יהיה ריק |
ראה גם
- שמירת מודלים תלת‑ממדיים: אפשרויות ייצוא ו
saveToBuffer - גרף סצנה: מעבר ושינוי של היררכיית הצמתים
- סקירת API: כל המחלקות וההצבעות
- תמיכת פורמטים: מטריצה מלאה של קריאה/כתיבה