Aspose.3D FOSS
TypeScript
Guias de Solução de Problemas

Guias de Solução de Problemas

Esta página cobre os erros mais comuns encontrados ao usar @aspose/3d em projetos TypeScript e Node.js, com explicações das causas raiz e correções verificadas.

Erros de Resolução de Módulo

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

Causa raiz: A estratégia de resolução de módulos do TypeScript não suporta exportações de subcaminho no estilo Node.js (exports em package.json) a menos que moduleResolution esteja definido como node ou node16.

Correção: Defina moduleResolution para "node" no seu tsconfig.json:

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

Se você estiver usando TypeScript 5.x com "module": "node16" ou "module": "nodenext", use "moduleResolution": "node16" para corresponder.

SyntaxError: Cannot use import statement in a module

Causa raiz: O JavaScript compilado está sendo executado com require() semântica, mas a saída contém módulo ES import sintaxe; isso acontece quando module está definido como es2020 ou esnext mas o runtime do Node.js espera CommonJS.

Corrigir: Use "module": "commonjs" em tsconfig.json e execute o compilado .js arquivos com node diretamente:

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

Então compile e execute:

npx tsc
node dist/main.js

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

Causa raiz: O pacote não está instalado, ou node_modules está desatualizado.

Corrigir:

npm install @aspose/3d

Verifique a instalação:

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

Cena Vazia Após Carregamento

A cena carrega, mas rootNode.childNodes está vazia

Causa raiz (1): O formato de arquivo coloca toda a geometria diretamente em rootNode.entity em vez de como nós filhos. Isso é comum em arquivos STL de malha ú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}`);

Correção: Percorra a partir de scene.rootNode ele mesmo, não apenas seus filhos:

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 raiz (2): O caminho do arquivo está errado ou o arquivo tem zero bytes. Verifique se o arquivo existe e não está vazio antes de chamar 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}`);

A lista de materiais está vazia após o carregamento do OBJ

Causa raiz: O carregamento de material está desativado por padrão em ObjLoadOptions. A biblioteca carrega a geometria sem ler o .mtl arquivo sidecar.

Correção: Defina 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);

Também garanta que o .mtl arquivo esteja no mesmo diretório que o .obj arquivo, pois a biblioteca o resolve relativo ao .obj caminho.

Erros de Formato e E/S

openFromBuffer gera um erro de formato não reconhecido

Causa raiz: O conteúdo do buffer não está em um formato binário reconhecível, ou o buffer está corrompido (truncado, codificação errada ou base64 em vez de bytes brutos).

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

Correção: Para formatos baseados em texto (OBJ, COLLADA), passe a classe de opções apropriada para indicar o formato:

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

O GLB de saída abre como JSON em visualizadores 3D

Causa raiz: GltfSaveOptions.binaryMode tem como padrão false, produzindo .gltf saída JSON mesmo quando o nome do arquivo de saída é .glb.

Correção: Defina explicitamente binaryMode = true:

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

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

A saída STL não contém dados de cor ou material no slicer

Causa raiz: O formato STL não suporta materiais ou cor em sua especificação padrão. Fatiadores com capacidade de cor usam extensões proprietárias não suportadas por @aspose/3d.

Correção: Exporte para 3MF em vez disso, que suporta metadados de cor e material:

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

Erros de Compilação do TypeScript

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

Causa raiz: Entity é a classe base; Mesh é o tipo concreto com propriedades de geometria. Você precisa de um instanceof guard antes de acessar membros específicos da malha.

Correção:

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 raiz: getChildNode() retorna Node | null. O modo estrito do TypeScript exige que você trate o caso nulo.

Correção:

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 raiz: GltfSaveOptions está no módulo de subcaminho @aspose/3d/formats/gltf, não na raiz do pacote.

Correção: Importar do subcaminho:

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

Problemas de Memória e Desempenho

O processo fica sem memória ao lidar com arquivos FBX grandes

Causa raiz: Arquivos FBX muito grandes (>200 MB) alocam heap significativo. O heap padrão do Node.js é ~1,5 GB em sistemas de 64 bits, mas pode não ser suficiente para arquivos com múltiplas cenas.

Correção: Aumente o tamanho do heap do Node.js:

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

Também processe os arquivos sequencialmente em vez de paralelamente quando a memória está 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
}

Veja também

 Português