راهنمای عیب‌یابی

این صفحه رایج‌ترین خطاهایی را که هنگام استفاده مواجه می‌شوید، پوشش می‌دهد @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

دلیل اصلی: جاوااسکریپت کامپایل‌شده با 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 منقضی شده است.

رفع:

npm install @aspose/3d

نصب را تأیید کنید:

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);

دلیل اصلی (۲): مسیر فایل اشتباه است یا فایل صفر بایت است. قبل از فراخوانی بررسی کنید که فایل وجود دارد و خالی نیست 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 مسیر.

خطاهای فرمت و ورودی/خروجی

openFromBuffer یک خطای قالب نامشخص ایجاد می‌کند

دلیل اصلی: محتوای بافر یک قالب باینری قابل شناسایی نیست، یا بافر خراب است (قطعه‌قطعه شده، رمزگذاری نادرست، یا base64 به جای بایت‌های خام).

تشخیص:

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 در نمایشگرهای 3D به‌صورت JSON باز می‌شود

دلیل ریشه‌ای: 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');

خطاهای کامپایل TypeScript

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

دلیل اصلی: Entity کلاس پایه است؛; Mesh نوع مشخص با ویژگی‌های هندسی است. شما به یک instanceof guard قبل از دسترسی به اعضای خاص مش.

رفع:

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 MB) حافظه heap قابل توجهی اختصاص می‌دهند. حافظه پیش‌فرض Node.js حدود ~1.5 GB در سیستم‌های 64‑بیتی است اما ممکن است برای فایل‌های چندصحنه‌ای کافی نباشد.

رفع: افزایش اندازه heap 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: تمام کلاس‌ها و ماژول‌ها