Aspose.3D FOSS
TypeScript
Panduan Pemecahan Masalah

Panduan Pemecahan Masalah

Halaman ini mencakup kesalahan paling umum yang ditemui saat menggunakan @aspose/3d di proyek TypeScript dan Node.js, dengan penjelasan penyebab utama dan perbaikan yang terverifikasi.

Kesalahan Resolusi Modul

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

Penyebab utama: Strategi resolusi modul TypeScript tidak mendukung ekspor sub‑path gaya Node.js (exports di package.json) kecuali moduleResolution diatur ke node atau node16.

Perbaikan: Atur moduleResolution ke "node" di dalam 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 mencocokkan.

SyntaxError: Cannot use import statement in a module

Penyebab utama: JavaScript yang telah dikompilasi dijalankan dengan require() semantik tetapi outputnya berisi ES module import sintaks; ini terjadi ketika module diatur ke es2020 atau esnext tetapi runtime Node.js mengharapkan CommonJS.

Perbaiki: Gunakan "module": "commonjs" di tsconfig.json dan jalankan yang telah dikompilasi .js berkas dengan node langsung:

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

Kemudian kompilasi dan jalankan:

npx tsc
node dist/main.js

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

Penyebab utama: Paket tidak terpasang, atau node_modules sudah usang.

Perbaiki:

npm install @aspose/3d

Verifikasi instalasi:

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

Adegan Kosong Setelah Memuat

Adegan dimuat tetapi rootNode.childNodes kosong

Penyebab utama (1): Format file menempatkan semua geometri langsung pada rootNode.entity daripada sebagai node anak. Ini umum pada file 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}`);

Perbaikan: Jelajahi mulai dari scene.rootNode : diri 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);

: Penyebab utama (2): Jalur file salah atau file berukuran nol byte. Periksa bahwa file ada dan tidak kosong sebelum memanggil 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}`);

Daftar material kosong setelah pemuatan OBJ

: Penyebab utama: Pemuatan material dinonaktifkan secara default di ObjLoadOptions. Perpustakaan memuat geometri tanpa membaca .mtl file sidecar.

: Perbaikan: Atur 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);

Juga pastikan .mtl file berada di direktori yang sama dengan .obj file, karena perpustakaan menyelesaikannya relatif terhadap .obj jalur.

Kesalahan Format dan I/O

openFromBuffer menghasilkan kesalahan format tidak dikenali

Penyebab utama: Konten buffer bukan format biner yang dapat dikenali, atau buffer rusak (terpotong, enkoding salah, atau base64 alih-alih byte 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

Perbaikan: Untuk format berbasis teks (OBJ, COLLADA), berikan kelas opsi yang sesuai untuk memberi petunjuk format:

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

GLB keluaran terbuka sebagai JSON di penampil 3D

Penyebab utama: GltfSaveOptions.binaryMode secara default ke false, menghasilkan .gltf output JSON bahkan ketika nama file output adalah .glb.

Perbaikan: Atur 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 memiliki data warna atau material di slicer

Penyebab utama: Format STL tidak mendukung material atau warna dalam spesifikasi standarnya. Slicer yang mendukung warna menggunakan ekstensi proprietari yang tidak didukung oleh @aspose/3d.

Perbaikan: Ekspor ke 3MF sebagai gantinya, yang mendukung metadata warna dan material:

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

Kesalahan Kompilasi TypeScript

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

Penyebab utama: Entity adalah kelas dasar; Mesh adalah tipe konkret dengan properti geometri. Anda memerlukan sebuah instanceof guard sebelum mengakses anggota khusus mesh.

Perbaikan:

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'

Penyebab utama: getChildNode() mengembalikan Node | null. Mode ketat TypeScript mengharuskan Anda menangani kasus null.

Perbaiki:

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

Cannot find name 'GltfSaveOptions'

Penyebab utama: GltfSaveOptions ada di modul sub-path @aspose/3d/formats/gltf, bukan root paket.

Perbaiki: Impor dari sub-path:

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

Masalah Memori dan Kinerja

Proses kehabisan memori dengan file FBX besar

Penyebab utama: File FBX yang sangat besar (>200 MB) mengalokasikan heap yang signifikan. Heap default Node.js sekitar ~1.5 GB pada sistem 64-bit tetapi mungkin tidak cukup untuk file multi-scene.

Perbaiki: Tingkatkan ukuran heap Node.js:

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

Juga proses file secara berurutan alih-alih paralel ketika memori terbatas:

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 Indonesia