כיצד לתקן שגיאות מודל תלת‑ממדי ב‑TypeScript

מדריך זה מכסה את השגיאות הנפוצות ביותר בעת השימוש ב@aspose/3d עבור TypeScript ו‑Node.js, עם תיקונים מעשיים לכל אחת.

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

שלב 1: אימות ההתקנה והגרסאות

ודא שאתה משתמש בגרסת Node.js נתמכת (18, 20 או 22) והחבילה מותקנת:

node --version          # Must be v18 or later
npm list @aspose/3d     # Should show the installed version

אם החבילה לא נמצאה, התקן מחדש:

npm install @aspose/3d

שלב 2: תיקון שגיאות פתרון מודול

שגיאה: Cannot find module '@aspose/3d/formats/obj'

היבוא של תתי‑נתיבים דורש ייצוא חבילות של Node.js 12.7+. ב‑TypeScript, הגדר את פתרון המודול הנכון:

// tsconfig.json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "moduleResolution": "node16",
    "strict": true
  }
}

לפרויקטים של ESM, השתמשו ב-"module": "ES2022" וב-"moduleResolution": "bundler".

שלב 3: ניפוי באג של סצנה ריקה לאחר הטעינה

אם scene.rootNode.childNodes ריק אחרי scene.open():

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

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

console.log(`Child nodes: ${scene.rootNode.childNodes.length}`);

סיבות נפוצות:

אפשרויות פורמט שגויות: עבור OBJ, תמיד העבר new ObjLoadOptions(). שימוש באפשרויות כלליות יכול למנוע זיהוי פורמט.
נתיב הקובץ שגוי: הספרייה טוענת בשקט סצנה ריקה אם הקובץ לא נמצא:

import * as fs from 'fs';

const filePath = 'model.obj';
if (!fs.existsSync(filePath)) {
    throw new Error(`File not found: ${filePath}`);
}
const scene = new Scene();
scene.open(filePath, new ObjLoadOptions());

קובץ OBJ משתמש בסיומות שורה לא תקניות: פתח בעורך טקסט וודא שהקובץ תקין.

שלב 4: תיקון בעיות במערכת הקואורדינטות

ייתכן שהמודלים יופיעו מסובבים, משוקפים או במימדים שגויים עקב הבדלים במערכת הקואורדינטות בין הפורמטים.

יד ימין מול יד שמאל, Y-למעלה מול Z-למעלה:

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

const options = new ObjLoadOptions();
options.flipCoordinateSystem = true;  // Swap Y and Z axes

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

בעיות קנה מידה (למשל, STL במילימטרים לעומת glTF במטרים):

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

const options = new ObjLoadOptions();
options.scale = 0.001;  // Convert millimeters to meters

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

שלב 5: טיפול בבעיות זיכרון עם קבצים גדולים

לקבצים הגדולים מ‑100 MB, הגדל את גודל ערימת הזיכרון של Node.js:

node --max-old-space-size=4096 convert.js

או הגדר זאת ב package.json:

{
  "scripts": {
    "convert": "node --max-old-space-size=4096 dist/convert.js"
  }
}

עבד קבצים גדולים אחד אחרי השני במקום במקביל כדי למנוע בעיות זיכרון בשיא.

הפניה לשגיאות נפוצות

שגיאה	סיבה אפשרית	תיקון
`Cannot find module '@aspose/3d/formats/obj'`	תצורת פתרון מודול	הגדר `moduleResolution: node16` ב‑tsconfig
`scene.rootNode.childNodes` ריק	אפשרויות שגויות או קובץ לא נמצא	בדוק את נתיב הקובץ; העבר `*LoadOptions` נכונה
הגיאומטריה מופיעה משתקפת/הפוכה	אי‑התאמה של מערכת הקואורדינטות	הגדר `flipCoordinateSystem = true`
הגיאומטריה מוצגת בקנה מידה שגוי	הבדל יחידות בין פורמטים	הגדר `scale` באפשרויות הטעינה
`ENOMEM` או תהליך נקטע	זיכרון בלתי מספיק לקובץ גדול	הגדל `--max-old-space-size`
שגיאת טיפוס TypeScript ב‑`node.entity`	סוג ישות רחב	השתמש במגן `instanceof Mesh`

שאלות נפוצות

איך אני מדווח על באג ניתוח?

פתח נושא בGitHub repository עם שם הפורמט, קובץ מינימלי שניתן לשחזר, והודעת השגיאה המדויקת.

למה לחלק מהרשתות יש אפס נקודות בקרה?

חלק מקבוצות ה‑OBJ מגדירות רק קואורדינטות מרקם או נורמליות ללא נתוני מיקום. בדוק mesh.controlPoints.length > 0 לפני העיבוד.

הספרייה מתעלמת משגיאות ניתוח בשקט. איך אוכל לאתר אותן?

עטוף את scene.open() בבלוק try/catch. אם הקובץ פגום, הספרייה עשויה לזרוק חריגה או לטעון סצנה חלקית:

try {
    scene.open('model.obj', new ObjLoadOptions());
} catch (err) {
    console.error('Failed to load:', err);
}