Aspose.3D FOSS
TypeScript
Посібники з усунення несправностей

Посібники з усунення несправностей

Ця сторінка охоплює найпоширеніші помилки, що виникають при використанні @aspose/3d у проектах TypeScript та Node.js, з поясненнями кореневих причин та перевіреними виправленнями.

Помилки розв’язання модулів

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

Коренева причина: Стратегія розв’язання модулів TypeScript не підтримує експорти підшляхів у стилі Node.js (exports у package.json) якщо не moduleResolution встановлено в node або node16.

Виправити: Встановити moduleResolution до "node" у вашому tsconfig.json:

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

Якщо ви використовуєте TypeScript 5.x з "module": "node16" або "module": "nodenext", використовуйте "moduleResolution": "node16" для відповідності.

SyntaxError: Cannot use import statement in a module

Коренева причина: Скомпільований JavaScript виконується з require() семантикою, але вихід містить ES module import синтаксис; це відбувається, коли module встановлено es2020 або esnext але середовище виконання Node.js очікує CommonJS.

Виправити: Використовуйте "module": "commonjs" у tsconfig.json і запустіть скомпільовані .js файли за допомогою node безпосередньо:

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

Потім скомпілюйте та запустіть:

npx tsc
node dist/main.js

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

Коренева причина: Пакет не встановлений, або node_modules застарілий.

Виправити:

npm install @aspose/3d

Перевірте встановлення:

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

Порожня сцена після завантаження

Сцена завантажується, але rootNode.childNodes порожня

Коренева причина (1): Формат файлу розміщує всю геометрію безпосередньо на rootNode.entity замість дочірніх вузлів. Це поширено у single-mesh STL файлах.

Діагноз:

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

Виправлення: Обійти, починаючи з scene.rootNode самого, а не лише його дочірніх елементів:

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

Коренева причина (2): Шлях до файлу неправильний або файл має нульовий розмір. Перевірте, що файл існує і не порожній перед викликом 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}`);

Список матеріалів порожній після завантаження OBJ

Коренева причина: Завантаження матеріалів за замовчуванням вимкнено в ObjLoadOptions. Бібліотека завантажує геометрію без читання .mtl допоміжного файлу.

Виправити: Встановити 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);

Також переконайтеся, що .mtl файл знаходиться в тому ж каталозі, що і .obj файл, оскільки бібліотека розв’язує його відносно .obj шляху.

Помилки формату та вводу/виводу

openFromBuffer викидає помилку невідомого формату

Коренева причина: Вміст буфера не є розпізнаваним бінарним форматом або буфер пошкоджений (усічений, неправильне кодування або base64 замість сирих байтів).

Діагностика:

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

Виправлення: Для текстових форматів (OBJ, COLLADA) передайте відповідний клас параметрів, щоб підказати формат:

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

Вихідний GLB відкривається як JSON у 3D‑переглядачах

Коренева причина: GltfSaveOptions.binaryMode за замовчуванням false, створюючи .gltf JSON‑вивід навіть коли ім’я файлу виводу є .glb.

Виправити: Явно встановити binaryMode = true:

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

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

Вивід STL не містить даних про колір або матеріал у слайсері

Коренева причина: Формат STL не підтримує матеріали або колір у своїй стандартній специфікації. Слайсери, що підтримують колір, використовують пропрієтарні розширення, які не підтримуються by @aspose/3d.

Виправити: Експортуйте у 3MF замість, який підтримує кольори та метадані матеріалів:

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

Помилки компіляції TypeScript

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

Коренева причина: Entity є базовим класом; Mesh є конкретним типом з геометричними властивостями. Вам потрібен instanceof захист перед доступом до членів, специфічних для сітки.

Виправити:

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'

Коренева причина: getChildNode() повертає Node | null. Режим строгого типу TypeScript вимагає, щоб ви обробляли випадок null.

Виправити:

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

Cannot find name 'GltfSaveOptions'

Коренева причина: GltfSaveOptions знаходиться в підшляху модуля @aspose/3d/formats/gltf, а не в корені пакету.

Виправити: Імпорт з підшляху:

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

Проблеми з пам’яттю та продуктивністю

Процес вичерпує пам’ять при роботі з великими файлами FBX

Корінна причина: Дуже великі файли FBX (>200 MB) споживають значний обсяг heap. За замовчуванням heap у Node.js становить ~1.5 GB на 64‑бітних системах, але може бути недостатнім для файлів з кількома сценами.

Виправлення: Збільште розмір heap у Node.js:

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

Також обробляйте файли послідовно, а не паралельно, коли пам’ять обмежена:

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
}

Див. також

 Українська