إرشادات حل المشاكل

هذه الصفحة تغطي الأخطاء الأكثر شيوعا التي تواجهها عند استخدام @aspose/3d في مشاريع TypeScript و Node.js ، مع تفسير السبب الجذر والتصحيحات المعتمدة.

حل الأخطاء الوحدة

Error: Cannot find module '@aspose/3d/formats/obj'

الجذور السببية: لا يدعم استراتيجية حل الوحدة من TypeScript تصدير الطرق الفرعية على غرار Node.js (exports في package.json(إذا لم يكن moduleResolution تم تعيينها إلى node أو node16.

تصحيح: مجموعة moduleResolution إلى "node" فيك tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "moduleResolution": "node",
    "esModuleInterop": true,
    "strict": true
  }
}

إذا كنت تستخدم TypeScript 5.x مع "module": "node16" أو "module": "nodenext", استخدام "moduleResolution": "node16" إلى المطابقة .

SyntaxError: Cannot use import statement in a module

الجذور السببية: يتم تشغيل JavaScript المنسق مع require() الرمزيات ولكن النتيجة تحتوي على ES وحدة import التخطيط: هذا يحدث عندما module تم تعيينها إلى es2020 أو esnext ولكن الوقت المناسب لـ Node.js ينتظر CommonJS.

تصحيح: الاستخدام "module": "commonjs" في tsconfig.json وَقَالَ الْمُجَاهِدُونَ .js الملفات مع node مباشرة :

{
  "compilerOptions": {
    "module": "commonjs",
    "outDir": "./dist"
  }
}

ثم قم بتجميع وتشغيل:

npx tsc
node dist/main.js

Error: Cannot find module '@aspose/3d'

الجذور السببية: لا يتم تثبيت الحزمة ، أو node_modules هو صلب .

تصحيح:

تحقق من التثبيت :

node -e "const { Scene } = require('@aspose/3d'); console.log('OK', new Scene().constructor.name);"

المشهد الفارغ بعد تحميل

المشهد يضرب ولكن rootNode.childNodes هو فارغ

الجذور السببية (1): تنسيق الملف يضع جميع الهندسة الجيومترية مباشرة على rootNode.entity بدلا من كأعمدة الطفل.هذا شائع مع ملفات STL واحدة.

التشخيص:

import { Scene, Mesh } from '@aspose/3d';

const scene = new Scene();
scene.open('model.stl');

// Check rootNode directly
if (scene.rootNode.entity) {
    console.log(`Root entity: ${scene.rootNode.entity.constructor.name}`);
}
console.log(`Child count: ${scene.rootNode.childNodes.length}`);

تصحيح: يبدأ من خلال scene.rootNode لنفسه، وليس فقط لأبنائه:

function visit(node: any): void {
    if (node.entity instanceof Mesh) {
        const m = node.entity as Mesh;
        console.log(`Mesh: ${m.controlPoints.length} vertices`);
    }
    for (const child of node.childNodes) {
        visit(child);
    }
}
visit(scene.rootNode);

الجذور السببية (2): مسار الملف خاطئ أو المجلد صفر بايت.تحقق من أن الملموس موجود وغير فارغ قبل الاتصال open().

import * as fs from 'fs';

const path = 'model.obj';
if (!fs.existsSync(path)) throw new Error(`File not found: ${path}`);
const stat = fs.statSync(path);
if (stat.size === 0) throw new Error(`File is empty: ${path}`);

قائمة المواد فارغة بعد تحميل OBJ

الجذور السببية: يتم تعطيل تحميل المواد عن طريق الافتراض في ObjLoadOptions.مكتبة تحمله الهندسة بدون قراءة .mtl ملف الجانب .

تصحيح: مجموعة enableMaterials = true:

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

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

كما يضمن أن .mtl الملفات في نفس الدليل كما هو الحال مع .obj المكتبة، كما يحددها مكتبه فيما يتعلق بال .obj الطريق .

أخطاء I/O و Format

openFromBuffer إلقاء خطأ في النموذج غير المعترف به

الجذور السببية: محتوى البوفر ليس تنسيق ثنائي قابل للتعرف ، أو البورفر مكسور (مكسورة ، تشفير خاطئ ، و bas64 بدلا من بايتات خام).

التشخيص:

const buffer = fs.readFileSync('model.glb');
console.log('Buffer size:', buffer.length, 'bytes');
console.log('First 4 bytes (hex):', buffer.slice(0, 4).toString('hex'));
// GLB magic: 676c5446 ("glTF")
// STL binary starts with 80 bytes of header; no fixed magic
// OBJ is text: openFromBuffer may not detect format

تصحيح: بالنسبة للتنسيقات القائمة على النص (OBJ، COLLADA)، انتقل إلى فئة الخيارات المناسبة لإدخال النموذج:

import { ObjLoadOptions } from '@aspose/3d/formats/obj';
scene.openFromBuffer(buffer, new ObjLoadOptions());

يفتح خروجي GLB كJSON في المشاهدين 3D

الجذور السببية: GltfSaveOptions.binaryMode الافتراضات إلى false, إنتاج .gltf JSON الناتج حتى عندما يكون اسم النتيجة فيلماً .glb.

تصحيح:* إعداد واضح binaryMode = true:

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

const opts = new GltfSaveOptions();
opts.binaryMode = true;
scene.save('output.glb', opts);

لا يوجد إخراج STL أي لون أو بيانات مادية في المطاط

الجذور السببية: لا يدعم تنسيق STL المواد أو الألوان في مواصفاته القياسية. يستخدم الستائر القابلة للطي الأزرار التمديدات الخاصة غير مدعومة من قبل @aspose/3d.

تصحيح: تصدير إلى 3MF بدلا من ذلك ، والتي تدعم البيانات الألوان والمواد:

scene.save('output.3mf');

خطأ في النسخ النمطية

Property 'controlPoints' does not exist on type 'Entity'

الجذور السببية: Entity فهي الطبقة الأساسية.; Mesh هو النوع الملموس مع خصائص الهندسة.أنت بحاجة إلى instanceof الحراسة قبل الوصول إلى أعضاء خاصين بالميزانية.

تصحيح:

import { Mesh } from '@aspose/3d';

if (node.entity instanceof Mesh) {
    const mesh = node.entity as Mesh;
    console.log(mesh.controlPoints.length);
}

Type 'null' is not assignable to type 'Node'

الجذور السببية: getChildNode() العودة Node | null.وضع TypeScript صارم يتطلب منك التعامل مع حالة null.

تصحيح:

const child = node.getChildNode('wheel');
if (!child) throw new Error('Node "wheel" not found');
// child is now Node, not null

Cannot find name 'GltfSaveOptions'

الجذور السببية: GltfSaveOptions في الوحدة تحت الطريق @aspose/3d/formats/gltf,وليس الجذور الحزمة.

تصحيح: استيراد من الطريق السفلي:

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

مشكلة الذاكرة والأداء

عملية تخرج من الذاكرة مع ملفات FBX الكبيرة

الجذور السببية: ملفات FBX كبيرة جدا (>200 ميغابايت) تخصيص هامش كبير. Node.js الافتراضي هامة هو ~1.5 غيغابيكتر على أنظمة 64 بت ولكن قد لا تكون كافية لملفات متعددة المشاهد.

تصحيح: زيادة حجم Node.js:

node --max-old-space-size=8192 dist/convert.js

كما يتم معالجة الملفات بشكل متتالي بدلاً من في وقت متوازي عندما تكون الذاكرة محدودة:

for (const file of files) {
    const scene = new Scene();
    scene.open(file);
    scene.save(file.replace('.fbx', '.glb'));
    // scene goes out of scope; GC can reclaim
}

انظر أيضا

• FAQ:الإجابة السريعة على الأسئلة الشائعة
• نموذج الشحن: نموذج الشحن والخيارات
• التصدير والتصدين: خيارات التصدير والأنابيب البوفرة
• API نظرة عامة: جميع الفصول و الوحدات
• Aspose.3D - قاعدة المعرفة للشركات