Aspose.3D Lliure i de Codi Obert
TypeScript
Guies de resolució de problemes

Guies de resolució de problemes

Aquesta pàgina cobreix els errors més comuns que es troben en utilitzar @aspose/3d en projectes TypeScript i Node.js, amb explicacions de la causa arrel i solucions verificades.

Errors de resolució de mòduls

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

Causa arrel: L’estratègia de resolució de mòduls de TypeScript no admet exportacions de subcamins al estil Node.js (exports a package.json) a menys que moduleResolution estigui establert a node o node16.

Solució: Configura moduleResolution a "node" al teu tsconfig.json:

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

Si estàs utilitzant TypeScript 5.x amb "module": "node16" o "module": "nodenext", utilitza "moduleResolution": "node16" per coincidir.

SyntaxError: Cannot use import statement in a module

Causa arrel: El JavaScript compilat s’està executant amb require() semàntica però la sortida conté un mòdul ES import sintaxi; això passa quan module està configurat a es2020 o esnext però el temps d’execució de Node.js espera CommonJS.

Correcció: Utilitza "module": "commonjs" a tsconfig.json i executa el compilat .js fitxers amb node directament:

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

Aleshores compila i executa:

npx tsc
node dist/main.js

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

Causa arrel: El paquet no està instal·lat, o node_modules està obsolet.

Correcció:

npm install @aspose/3d

Verifica la instal·lació:

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

Escena buida després de la càrrega

L’escena es carrega però rootNode.childNodes està buida

Causa arrel (1): El format de fitxer col·loca tota la geometria directament a rootNode.entity en comptes de com a nodes fills. Això és comú amb fitxers STL d’una sola malla.

Diagnòstic:

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

Solució: Recorre a partir de scene.rootNode ell mateix, no només els seus fills:

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 arrel (2): El camí del fitxer és incorrecte o el fitxer té zero bytes. Comproveu que el fitxer existeix i no està buit abans de cridar 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}`);

La llista de materials està buida després de carregar l’OBJ

Causa arrel: La càrrega de material està desactivada per defecte a ObjLoadOptions. La biblioteca carrega la geometria sense llegir el .mtl fitxer sidecar.

Solució: Estableix 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);

Assegureu-vos també que el .mtl fitxer es troba al mateix directori que el .obj fitxer, ja que la biblioteca el resol de manera relativa al .obj camí.

Errors de format i d’E/S

openFromBuffer llança un error de format no reconegut

Causa arrel: El contingut del buffer no és un format binari reconeixible, o el buffer està corrupte (truncat, codificació incorrecta, o base64 en comptes de bytes crus).

Diagnòstic:

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

Solució: Per a formats basats en text (OBJ, COLLADA), passeu la classe d’opcions adequada per indicar el format:

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

El GLB de sortida s’obre com a JSON en visualitzadors 3D

Causa arrel: GltfSaveOptions.binaryMode per defecte és false, produint .gltf sortida JSON fins i tot quan el nom del fitxer de sortida és .glb.

Solució: Establiu explícitament binaryMode = true:

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

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

La sortida STL no conté dades de color ni de material al tallador

Causa arrel: El format STL no admet materials ni color en la seva especificació estàndard. Els laminadors amb capacitat de color utilitzen extensions propietàries que no són compatibles amb @aspose/3d.

Solució: Exporta a 3MF en canvi, que admet metadades de color i material:

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

Errors de compilació de TypeScript

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

Causa arrel: Entity és la classe base; Mesh és el tipus concret amb propietats de geometria. Necessites un instanceof comprovació abans d’accedir als membres específics de la malla.

Solució:

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 arrel: getChildNode() retorna Node | null. El mode estricte de TypeScript requereix que gestionis el cas de null.

Correcció:

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 arrel: GltfSaveOptions és al mòdul de subcamí @aspose/3d/formats/gltf, no a l’arrel del paquet.

Correcció: Importa des del subcamí:

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

Problemes de memòria i rendiment

El procés s’esgota de memòria amb fitxers FBX grans

Causa arrel: Fitxers FBX molt grans (>200 MB) assignen una memòria cau significativa. La memòria cau per defecte de Node.js és d’uns ~1,5 GB en sistemes de 64 bits, però pot no ser suficient per a fitxers amb múltiples escenes.

Correcció: Augmenta la mida de la memòria cau de Node.js:

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

Processa també els fitxers de manera seqüencial en lloc de paral·lela quan la memòria és limitada:

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
}

Vegeu també

 Català