Aspose.3D FOSS
TypeScript
Οδηγοί Επίλυσης Προβλημάτων

Οδηγοί Επίλυσης Προβλημάτων

Αυτή η σελίδα καλύπτει τα πιο κοινά σφάλματα που προκύπτουν κατά τη χρήση του @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 module import· αυτό συμβαίνει όταν 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. Η βιβλιοθήκη φορτώνει τη γεωμετρία χωρίς να διαβάσει το αρχείο sidecar .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

openFromBuffer προκαλεί σφάλμα μη αναγνωρισμένης μορφής

Αιτία: Το περιεχόμενο του buffer δεν είναι αναγνωρίσιμη δυαδική μορφή ή το buffer είναι κατεστραμμένο (κομμένο, λανθασμένη κωδικοποίηση ή base64 αντί για ακατέργαστα byte).

Διάγνωση:

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

Root cause: Η μορφή STL δεν υποστηρίζει υλικά ή χρώμα στην τυπική της προδιαγραφή. Οι slicers που υποστηρίζουν χρώμα χρησιμοποιούν ιδιόκτητες επεκτάσεις που δεν υποστηρίζονται από @aspose/3d.

Διόρθωση: Εξαγωγή σε 3MF αντί αυτού, που υποστηρίζει χρώμα και μεταδεδομένα υλικού:

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

Σφάλματα Μεταγλώττισης TypeScript

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

Root cause: 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 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
}

Δείτε επίσης

  • FAQ: γρήγορες απαντήσεις σε κοινές ερωτήσεις
  • Model Loading: μοτίβα φόρτωσης και επιλογές
  • Rendering and Export: επιλογές εξαγωγής και buffer pipelines
  • API Overview: όλες οι κλάσεις και τα modules
 Ελληνικά