Aspose.3D FOSS
TypeScript
Guide di risoluzione dei problemi

Guide di risoluzione dei problemi

Questa pagina copre gli errori più comuni riscontrati durante l’uso di @aspose/3d nei progetti TypeScript e Node.js, con spiegazioni delle cause radice e correzioni verificate.

Errori di risoluzione dei moduli

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

Causa radice: La strategia di risoluzione dei moduli di TypeScript non supporta le esportazioni di sotto‑percorso in stile Node.js (exports in package.json) a meno che moduleResolution sia impostato su node o node16.

Correzione: Imposta moduleResolution su "node" nel tuo tsconfig.json:

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

Se stai usando TypeScript 5.x con "module": "node16" o "module": "nodenext", usa "moduleResolution": "node16" per corrispondere.

SyntaxError: Cannot use import statement in a module

Causa principale: Il JavaScript compilato viene eseguito con require() semantica ma l’output contiene ES module import sintassi; questo accade quando module è impostato su es2020 oppure esnext ma il runtime Node.js si aspetta CommonJS.

Correggi: Usa "module": "commonjs" in tsconfig.json e esegui i compilati .js file con node direttamente:

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

Quindi compila ed esegui:

npx tsc
node dist/main.js

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

Causa principale: Il pacchetto non è installato, o node_modules è obsoleto.

Correggi:

npm install @aspose/3d

Verifica l’installazione:

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

Scena Vuota Dopo il Caricamento

La scena si carica ma rootNode.childNodes è vuoto

Causa principale (1): Il formato file posiziona tutta la geometria direttamente su rootNode.entity piuttosto che come nodi figlio. Questo è comune nei file STL a mesh singola.

Diagnosi:

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

Correzione:Scorri a partire da scene.rootNode se stesso, non solo i suoi figli:

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

Causa principale (2): Il percorso del file è errato o il file è di zero byte. Verifica che il file esista e non sia vuoto prima di chiamare 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}`);

L’elenco dei materiali è vuoto dopo il caricamento OBJ

Causa principale: Il caricamento dei materiali è disabilitato per impostazione predefinita in ObjLoadOptions. La libreria carica la geometria senza leggere il .mtl file laterale.

Correzione: Imposta 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);

Assicurati anche che il .mtl file sia nella stessa directory del .obj file, poiché la libreria lo risolve in modo relativo al .obj percorso.

Errori di Formato e I/O

openFromBuffer genera un errore di formato non riconosciuto

Causa principale: Il contenuto del buffer non è in un formato binario riconoscibile, o il buffer è corrotto (troncato, codifica errata o base64 invece di byte grezzi).

Diagnosi:

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

Correzione: Per i formati basati su testo (OBJ, COLLADA), passa la classe di opzioni appropriata per suggerire il formato:

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

Il GLB di output si apre come JSON nei visualizzatori 3D

Causa principale: GltfSaveOptions.binaryMode predefinito a false, producendo .gltf output JSON anche quando il nome file di output è .glb.

Correzione: Imposta esplicitamente binaryMode = true:

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

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

L’output STL non contiene dati di colore o materiale nello slicer

Causa principale: Il formato STL non supporta materiali o colore nella sua specifica standard. I slicer con capacità di colore usano estensioni proprietarie non supportate da @aspose/3d.

Correzione: Esporta invece in 3MF, che supporta metadati di colore e materiale:

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

Errori di compilazione TypeScript

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

Causa principale: Entity è la classe base; Mesh è il tipo concreto con proprietà geometriche. Hai bisogno di un instanceof controllo prima di accedere ai membri specifici della mesh.

Correzione:

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'

Causa principale: getChildNode() restituisce Node | null. La modalità strict di TypeScript richiede di gestire il caso null.

Correggi:

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

Cannot find name 'GltfSaveOptions'

Causa radice: GltfSaveOptions si trova nel modulo sub-path @aspose/3d/formats/gltf, non nella radice del pacchetto.

Correzione: Importa dal sub-path:

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

Problemi di memoria e prestazioni

Il processo esaurisce la memoria con file FBX di grandi dimensioni

Causa principale: I file FBX molto grandi (>200 MB) allocano una heap significativa. L’heap predefinita di Node.js è ~1.5 GB sui sistemi a 64-bit ma potrebbe non essere sufficiente per file multi-scena.

Correzione: Aumenta la dimensione dell’heap di Node.js:

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

Elabora anche i file in modo sequenziale anziché in parallelo quando la memoria è limitata:

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
}

Vedi anche

 Italiano