Aspose.3D FOSS
TypeScript
Guides de dépannage

Guides de dépannage

Cette page couvre les erreurs les plus courantes rencontrées lors de l’utilisation @aspose/3d dans les projets TypeScript et Node.js, avec des explications sur la cause profonde et des correctifs vérifiés.

Erreurs de résolution de modules

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

Cause profonde: La stratégie de résolution des modules de TypeScript ne prend pas en charge les exportations de sous‑chemins de style Node.js (exports dans package.json) à moins que moduleResolution soit défini sur node ou node16.

Correction: Définir moduleResolution sur "node" dans votre tsconfig.json:

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

Si vous utilisez TypeScript 5.x avec "module": "node16" ou "module": "nodenext", utilisez "moduleResolution": "node16" pour correspondre.

SyntaxError: Cannot use import statement in a module

Cause racine: Le JavaScript compilé est exécuté avec require() une sémantique mais la sortie contient un module ES import syntaxe ; cela se produit lorsque module est défini sur es2020 ou esnext mais le runtime Node.js attend CommonJS.

Correction: Utiliser "module": "commonjs" dans tsconfig.json et exécuter le compilé .js fichiers avec node directement :

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

Ensuite, compilez et exécutez :

npx tsc
node dist/main.js

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

Cause première: Le paquet n’est pas installé, ou node_modules est obsolète.

Correction:

npm install @aspose/3d

Vérifiez l’installation :

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

Scène vide après le chargement

La scène se charge mais rootNode.childNodes est vide

Cause racine (1): Le format de fichier place toute la géométrie directement sur rootNode.entity plutôt qu’en tant que nœuds enfants. C’est courant avec les fichiers STL à maillage unique.

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

Correction: Parcourir en commençant par scene.rootNode lui-même, pas seulement ses enfants :

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

Cause racine (2): Le chemin du fichier est incorrect ou le fichier a une taille de zéro octet. Vérifiez que le fichier existe et n’est pas vide avant d’appeler 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 liste des matériaux est vide après le chargement OBJ

Cause première: Le chargement du matériau est désactivé par défaut dans ObjLoadOptions. La bibliothèque charge la géométrie sans lire le .mtl fichier annexe.

Correction: Définir 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);

Assurez également que le .mtl fichier se trouve dans le même répertoire que le .obj fichier, car la bibliothèque le résout relativement au .obj chemin.

Erreurs de format et d’E/S

openFromBuffer génère une erreur de format non reconnu

Cause première: Le contenu du tampon n’est pas un format binaire reconnaissable, ou le tampon est corrompu (tronqué, mauvais encodage, ou base64 au lieu d’octets bruts).

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

Correction: Pour les formats basés sur du texte (OBJ, COLLADA), transmettez la classe d’options appropriée pour indiquer le format :

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

Le GLB de sortie s’ouvre en JSON dans les visionneuses 3D

Cause première: GltfSaveOptions.binaryMode par défaut false, produisant .gltf une sortie JSON même lorsque le nom de fichier de sortie est .glb.

Correction: Définir explicitement binaryMode = true:

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

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

La sortie STL ne contient aucune donnée de couleur ou de matériau dans le slicer

Cause première: Le format STL ne prend pas en charge les matériaux ou la couleur dans sa spécification standard. Les trancheurs capables de gérer la couleur utilisent des extensions propriétaires non prises en charge par @aspose/3d.

Correction: Exportez plutôt en 3MF, qui prend en charge les métadonnées de couleur et de matériau :

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

Erreurs de compilation TypeScript

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

Cause première: Entity est la classe de base ; Mesh est le type concret avec des propriétés géométriques. Vous avez besoin d’un instanceof garde avant d’accéder aux membres spécifiques au maillage.

Correction:

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'

Cause première: getChildNode() renvoie Node | null. Le mode strict de TypeScript vous oblige à gérer le cas null.

Correction:

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

Cannot find name 'GltfSaveOptions'

Cause première: GltfSaveOptions se trouve dans le module du sous‑chemin @aspose/3d/formats/gltf, pas la racine du paquet.

Correction: Importer depuis le sous‑chemin:

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

Problèmes de mémoire et de performances

Le processus manque de mémoire avec de gros fichiers FBX

Cause première: Les fichiers FBX très volumineux (>200 Mo) allouent un tas important. Le tas par défaut de Node.js est d’environ 1,5 Go sur les systèmes 64 bits, mais il peut ne pas être suffisant pour les fichiers multi‑scènes.

Correction: Augmenter la taille du tas Node.js:

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

Traitez également les fichiers séquentiellement plutôt qu’en parallèle lorsque la mémoire est limitée :

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
}

Voir aussi

 Français