Aspose.3D FOSS
TypeScript
Panduan Penyelesaian Masalah

Panduan Penyelesaian Masalah

Halaman ini merangkumi ralat paling umum yang ditemui semasa menggunakan @aspose/3d dalam projek TypeScript dan Node.js, dengan penjelasan punca utama dan pembaikan yang disahkan.

Ralat Resolusi Modul

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

Punca utama: Strategi resolusi modul TypeScript tidak menyokong eksport sub‑laluan gaya Node.js (exports dalam package.json) melainkan moduleResolution ditetapkan kepada node atau node16.

Pembaikan: Tetapkan moduleResolution kepada "node" dalam anda tsconfig.json:

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

Jika anda menggunakan TypeScript 5.x dengan "module": "node16" atau "module": "nodenext", gunakan "moduleResolution": "node16" untuk sepadan.

SyntaxError: Cannot use import statement in a module

Punca utama: JavaScript yang telah disusun sedang dijalankan dengan require() semantik tetapi output mengandungi modul ES import sintaks; ini berlaku apabila module ditetapkan kepada es2020 atau esnext tetapi runtime Node.js mengharapkan CommonJS.

Betulkan: Gunakan "module": "commonjs" di tsconfig.json dan jalankan yang telah dikompilasi .js fail dengan node secara langsung:

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

Kemudian kompil dan jalankan:

npx tsc
node dist/main.js

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

Punca utama: Pakej tidak dipasang, atau node_modules tidak terkini.

Betulkan:

npm install @aspose/3d

Sahkan pemasangan:

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

Adegan Kosong Selepas Memuat

Adegan dimuatkan tetapi rootNode.childNodes kosong

Punca utama (1): Format fail meletakkan semua geometri secara langsung pada rootNode.entity berbanding sebagai nod anak. Ini biasa dengan fail STL satu-mesh.

Diagnosis:

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

Pembetulan:Menelusuri bermula dari scene.rootNode sendiri, bukan hanya anak‑anaknya:

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

Punca utama (2): Laluan fail salah atau fail berukuran sifar bait. Pastikan fail wujud dan tidak kosong sebelum dipanggil 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}`);

Senarai bahan kosong selepas pemuatan OBJ

Punca utama: Pemuat bahan dilumpuhkan secara lalai dalam ObjLoadOptions. Perpustakaan memuatkan geometri tanpa membaca .mtl fail sidecar.

Pembetulan: Tetapkan 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);

Pastikan juga .mtl fail berada dalam direktori yang sama dengan .obj fail, kerana perpustakaan menyelesaikannya secara relatif kepada .obj laluan.

Ralat Format dan I/O

openFromBuffer menimbulkan ralat format tidak dikenali

Punca utama: Kandungan penimbal bukan dalam format binari yang dapat dikenali, atau penimbal rosak (terpotong, pengekodan salah, atau base64 bukannya bait mentah).

Diagnosis:

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

Pembetulan: Untuk format berasaskan teks (OBJ, COLLADA), hantarkan kelas pilihan yang sesuai untuk memberi petunjuk format:

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

Output GLB dibuka sebagai JSON dalam penonton 3D

Punca utama: GltfSaveOptions.binaryMode menetapkan lalai kepada false, menghasilkan .gltf output JSON walaupun nama fail output ialah .glb.

Pembetulan: Tetapkan secara eksplisit binaryMode = true:

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

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

Output STL tidak mempunyai data warna atau bahan dalam slicer

Punca utama: Format STL tidak menyokong bahan atau warna dalam spesifikasi standardnya. Penylicer yang menyokong warna menggunakan sambungan proprietari yang tidak disokong oleh @aspose/3d.

Pembetulan: Eksport ke 3MF sebagai gantinya, yang menyokong metadata warna dan bahan:

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

Ralat Kompilasi TypeScript

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

Punca utama: Entity adalah kelas asas; Mesh adalah jenis konkrit dengan sifat geometri. Anda memerlukan satu instanceof penjaga sebelum mengakses ahli khusus mesh.

Pembetulan:

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'

Punca utama: getChildNode() mengembalikan Node | null. Mod ketat TypeScript memerlukan anda mengendalikan kes null.

Betulkan:

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

Cannot find name 'GltfSaveOptions'

Punca utama: GltfSaveOptions berada dalam modul sub-laluan @aspose/3d/formats/gltf, bukan akar pakej.

Betulkan: Import dari sub-laluan:

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

Isu Memori dan Prestasi

Proses kehabisan memori dengan fail FBX yang besar

Punca utama: Fail FBX yang sangat besar (>200 MB) menggunakan timbunan yang signifikan. Heap lalai Node.js adalah ~1.5 GB pada sistem 64-bit tetapi mungkin tidak mencukupi untuk fail berbilang-skenario.

Betulkan: Tingkatkan saiz heap Node.js:

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

Juga proses fail secara berurutan dan bukannya selari apabila memori terhad:

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
}

Lihat Juga

 Bahasa Melayu