Aspose.3D FOSS
TypeScript
คู่มือการแก้ไขปัญหา

คู่มือการแก้ไขปัญหา

หน้านี้ครอบคลุมข้อผิดพลาดที่พบบ่อยที่สุดที่พบเมื่อใช้ @aspose/3d ในโครงการ TypeScript และ Node.js พร้อมคำอธิบายสาเหตุรากและการแก้ไขที่ตรวจสอบแล้ว.

ข้อผิดพลาดการแก้ไขโมดูล

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

สาเหตุราก: กลยุทธ์การแก้ไขโมดูลของ TypeScript ไม่รองรับการส่งออก sub-path แบบ 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() semantics แต่ผลลัพธ์มีไวยากรณ์ ES module import syntax; สิ่งนี้เกิดขึ้นเมื่อ module ถูกตั้งค่าเป็น es2020 หรือ esnext แต่ runtime ของ 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);

สาเหตุหลัก (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. ไลบรารีโหลดเรขาคณิตโดยไม่อ่าน the .mtl sidecar file.

แก้ไข: ตั้งค่า 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

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 ที่ส่งออกเปิดเป็น 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 ไม่มีข้อมูลสีหรือวัสดุใน slicer

สาเหตุราก: รูปแบบ STL ไม่รองรับวัสดุหรือสีในสเปคมาตรฐานของมัน. slicer ที่รองรับสีใช้ส่วนขยายที่เป็นกรรมสิทธิ์ซึ่งไม่ได้รับการสนับสนุนโดย @aspose/3d.

แก้ไข: ส่งออกเป็น 3MF แทน ซึ่งรองรับเมตาดาต้าสีและวัสดุ:

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

ข้อผิดพลาดการคอมไพล์ TypeScript

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

สาเหตุราก: Entity เป็นคลาสฐาน; Mesh เป็น concrete type ที่มีคุณสมบัติ geometry. คุณต้องมี instanceof guard ก่อนเข้าถึงสมาชิก mesh-specific.

แก้ไข:

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. โหมด strict ของ 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 อยู่ในโมดูล sub-path @aspose/3d/formats/gltf, ไม่ใช่ package root.

แก้ไข: นำเข้าจาก sub-path:

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

ปัญหาเรื่องหน่วยความจำและประสิทธิภาพ

กระบวนการใช้หน่วยความจำหมดเมื่อทำงานกับไฟล์ FBX ขนาดใหญ่

สาเหตุหลัก: ไฟล์ FBX ขนาดใหญ่มาก (>200 MB) ใช้หน่วยความจำ heap อย่างมาก. heap เริ่มต้นของ Node.js มีประมาณ ~1.5 GB บนระบบ 64-bit แต่อาจไม่เพียงพอสำหรับไฟล์ที่มีหลายฉาก.

วิธีแก้ไข: เพิ่มขนาด 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
}

ดูเพิ่มเติม

 ภาษาไทย