Aspose.3D FOSS
TypeScript
Ghiduri de depanare

Ghiduri de depanare

Această pagină acoperă cele mai comune erori întâlnite când se utilizează @aspose/3d în proiecte TypeScript și Node.js, cu explicații ale cauzei principale și remedii verificate.

Erori de rezolvare a modulelor

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

Cauză principală: Strategia de rezolvare a modulelor din TypeScript nu suportă exporturile de sub-căi în stil Node.js (exports în package.json) cu excepția cazului în care moduleResolution este setat la node sau node16.

Remediere: Setează moduleResolution la "node" în tsconfig.json:

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

Dacă utilizați TypeScript 5.x cu "module": "node16" sau "module": "nodenext", folosiți "moduleResolution": "node16" pentru a se potrivi.

SyntaxError: Cannot use import statement in a module

Cauza principală: JavaScript-ul compilat este rulat cu require() semantica, dar ieșirea conține modulul ES import sintaxă; acest lucru se întâmplă când module este setat la es2020 sau esnext dar mediul de execuție Node.js așteaptă CommonJS.

Remediere: Folosește "module": "commonjs" în tsconfig.json și rulează fișierele compilate .js fișiere cu node direct:

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

Apoi compilați și rulați:

npx tsc
node dist/main.js

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

Cauză rădăcină: Pachetul nu este instalat, sau node_modules este învechit.

Remediere:

npm install @aspose/3d

Verificați instalarea:

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

Scenă goală după încărcare

Scena se încarcă, dar rootNode.childNodes este goală

Cauza principală (1): Formatul fișierului plasează toată geometria direct pe rootNode.entity în loc de noduri copil. Acest lucru este comun la fișiere STL cu un singur mesh.

Diagnostic:

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

Remediere: Parcurge începând de la scene.rootNode el însuși, nu doar copiii săi:

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

Cauza principală (2): Calea fișierului este greșită sau fișierul are zero octeți. Verificați că fișierul există și nu este gol înainte de a apela 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}`);

Lista de materiale este goală după încărcarea OBJ

Cauza principală: Încărcarea materialelor este dezactivată în mod implicit în ObjLoadOptions. Biblioteca încarcă geometria fără a citi .mtl fișierul sidecar.

Remediere: Setează 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);

Asigură-te, de asemenea, că .mtl fișierul este în același director cu .obj fișier, deoarece biblioteca îl rezolvă relativ la .obj calea.

Erori de format și I/O

openFromBuffer aruncă o eroare de format nerecunoscut

Cauza rădăcină: Conținutul bufferului nu este un format binar recunoscut sau bufferul este corupt (trunchiat, codare greșită sau base64 în loc de octeți brut).

Diagnostic:

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

Remediere: Pentru formatele bazate pe text (OBJ, COLLADA), transmiteți clasa de opțiuni corespunzătoare pentru a indica formatul:

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

GLB-ul de ieșire se deschide ca JSON în vizualizatoarele 3D

Cauza rădăcină: GltfSaveOptions.binaryMode implicit la false, producând .gltf ieșire JSON chiar și când numele fișierului de ieșire este .glb.

Remediere: Setează explicit binaryMode = true:

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

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

Ieșirea STL nu conține date de culoare sau material în slicer

Cauza rădăcină: Formatul STL nu suportă materiale sau culoare în specificația sa standard. Slicer-urile capabile de culoare folosesc extensii proprietare care nu sunt suportate de @aspose/3d.

Remediere: Exportă în 3MF în schimb, care suportă metadatele de culoare și material:

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

Erori de compilare TypeScript

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

Cauza rădăcină: Entity este clasa de bază; Mesh este tipul concret cu proprietăți geometrice. Ai nevoie de un instanceof verificare înainte de a accesa membrii specifici mesh-ului.

Remediere:

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'

Cauza rădăcină: getChildNode() returnează Node | null. Mod strict al TypeScript necesită să gestionaţi cazul null.

Remediere:

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

Cannot find name 'GltfSaveOptions'

Cauza principală: GltfSaveOptions se află în modulul sub-calei @aspose/3d/formats/gltf, nu în rădăcina pachetului.

Remediere: Importă din sub-cale:

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

Probleme de memorie și performanță

Procesul rămâne fără memorie la fișiere FBX mari

Cauza principală: Fișiere FBX foarte mari (>200 MB) alocă o zonă de memorie semnificativă. Heap‑ul implicit al Node.js este de ~1,5 GB pe sistemele pe 64‑bit, dar s‑ar putea să nu fie suficient pentru fișiere cu mai multe scene.

Remediere: Crește dimensiunea heap‑ului Node.js:

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

De asemenea, procesează fișierele secvențial în loc de paralel când memoria este limitată:

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
}

Vezi și

 Română