Aspose.3D FOSS
TypeScript
Guías de solución de problemas

Guías de solución de problemas

Esta página cubre los errores más comunes encontrados al usar @aspose/3d en proyectos TypeScript y Node.js, con explicaciones de la causa raíz y correcciones verificadas.

Errores de resolución de módulos

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

Causa raíz: La estrategia de resolución de módulos de TypeScript no admite exportaciones de subruta al estilo Node.js (exports en package.json) a menos que moduleResolution esté configurado a node o node16.

Solución: Establecer moduleResolution a "node" en su tsconfig.json:

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

Si está usando TypeScript 5.x con "module": "node16" o "module": "nodenext", use "moduleResolution": "node16" para que coincida.

SyntaxError: Cannot use import statement in a module

Causa raíz: El JavaScript compilado se está ejecutando con require() semántica pero la salida contiene ES module import sintaxis; esto ocurre cuando module está configurado a es2020 o esnext pero el tiempo de ejecución de Node.js espera CommonJS.

Arreglar: Usar "module": "commonjs" en tsconfig.json y ejecuta los compilados .js archivos con node directamente:

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

Luego compile y ejecute:

npx tsc
node dist/main.js

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

Causa raíz: El paquete no está instalado, o node_modules está obsoleto.

Arreglar:

npm install @aspose/3d

Verifique la instalación:

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

Escena Vacía Después de Cargar

La escena se carga pero rootNode.childNodes está vacía

Causa raíz (1): El formato de archivo coloca toda la geometría directamente en rootNode.entity en lugar de como nodos hijos. Esto es común con archivos STL de malla única.

Diagnóstico:

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ón: Recorrer comenzando desde scene.rootNode él mismo, no solo sus hijos:

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 raíz (2): La ruta del archivo es incorrecta o el archivo tiene cero bytes. Verifique que el archivo exista y no esté vacío antes de llamar 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 lista de materiales está vacía después de cargar OBJ

Causa raíz: La carga de material está deshabilitada por defecto en ObjLoadOptions. La biblioteca carga la geometría sin leer el .mtl archivo sidecar.

Corrección: Establecer 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);

También asegúrate de que el .mtl archivo esté en el mismo directorio que el .obj archivo, ya que la biblioteca lo resuelve de forma relativa al .obj ruta.

Errores de Formato y E/S

openFromBuffer lanza un error de formato no reconocido

Causa raíz: El contenido del búfer no es un formato binario reconocible, o el búfer está corrupto (truncado, codificación incorrecta, o base64 en lugar de bytes crudos).

Diagnóstico:

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ón: Para formatos basados en texto (OBJ, COLLADA), pase la clase de opciones adecuada para indicar el formato:

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

El GLB de salida se abre como JSON en visores 3D

Causa raíz: GltfSaveOptions.binaryMode por defecto es false, produciendo .gltf salida JSON incluso cuando el nombre del archivo de salida es .glb.

Solución: Establecer explícitamente binaryMode = true:

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

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

La salida STL no tiene datos de color ni de material en el slicer

Causa raíz: El formato STL no admite materiales ni color en su especificación estándar. Los slicers con capacidad de color utilizan extensiones propietarias que no son compatibles con @aspose/3d.

Solución: Exporta a 3MF en su lugar, que admite metadatos de color y material:

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

Errores de compilación de TypeScript

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

Causa raíz: Entity es la clase base; Mesh es el tipo concreto con propiedades de geometría. Necesitas un instanceof guardia antes de acceder a los miembros específicos de la malla.

Solución:

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 raíz: getChildNode() devuelve Node | null. El modo estricto de TypeScript requiere que manejes el caso nulo.

Corregir:

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 raíz: GltfSaveOptions está en el módulo de subruta @aspose/3d/formats/gltf, no en la raíz del paquete.

Corregir: Importa desde la subruta:

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

Problemas de memoria y rendimiento

El proceso se queda sin memoria con archivos FBX grandes

Causa raíz: Los archivos FBX muy grandes (>200 MB) asignan una pila significativa. El heap predeterminado de Node.js es ~1.5 GB en sistemas de 64 bits, pero puede no ser suficiente para archivos con múltiples escenas.

Corregir: Incrementa el tamaño del heap de Node.js:

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

También procesa los archivos de forma secuencial en lugar de paralela cuando la memoria es 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
}

Ver también

 Español