Aspose.3D FOSS
TypeScript
Poradniki rozwiązywania problemów

Poradniki rozwiązywania problemów

Ta strona opisuje najczęstsze błędy napotykane podczas używania @aspose/3d w projektach TypeScript i Node.js, wraz z wyjaśnieniami przyczyn oraz zweryfikowanymi rozwiązaniami.

Błędy rozwiązywania modułów

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

Przyczyna źródłowa: Strategia rozwiązywania modułów w TypeScript nie obsługuje eksportów podścieżek w stylu Node.js (exports w package.json) chyba że moduleResolution jest ustawione na node lub node16.

Rozwiązanie: Ustaw moduleResolution na "node" w twoim tsconfig.json:

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

Jeśli używasz TypeScript 5.x z "module": "node16" lub "module": "nodenext", użyj "moduleResolution": "node16" aby dopasować.

SyntaxError: Cannot use import statement in a module

Przyczyna źródłowa: Skrypt JavaScript skompilowany jest uruchamiany z require() semantyką, ale wynik zawiera ES module import składnia; dzieje się to, gdy module jest ustawione na es2020 lub esnext ale środowisko uruchomieniowe Node.js oczekuje CommonJS.

Napraw: Użyj "module": "commonjs" w tsconfig.json i uruchom skompilowane .js pliki przy użyciu node bezpośrednio:

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

Następnie skompiluj i uruchom:

npx tsc
node dist/main.js

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

Przyczyna źródłowa: Pakiet nie jest zainstalowany, lub node_modules jest przestarzały.

Napraw:

npm install @aspose/3d

Zweryfikuj instalację:

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

Pusta scena po załadowaniu

Scena ładuje się, ale rootNode.childNodes jest pusta

Przyczyna źródłowa (1): Format pliku umieszcza całą geometrię bezpośrednio na rootNode.entity zamiast jako węzły potomne. To jest powszechne w przypadku jednoskładnikowych plików STL.

Diagnoza:

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

Naprawa: Przejdź zaczynając od scene.rootNode samego siebie, a nie tylko jego potomków:

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

Przyczyna źródłowa (2): Ścieżka do pliku jest nieprawidłowa lub plik ma zerowy rozmiar. Sprawdź, czy plik istnieje i nie jest pusty przed wywołaniem 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}`);

Lista materiałów jest pusta po załadowaniu OBJ

Przyczyna źródłowa: Ładowanie materiałów jest domyślnie wyłączone w ObjLoadOptions. Biblioteka ładuje geometrię bez odczytywania .mtl pliku pomocniczego.

Poprawka: Ustaw 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);

Upewnij się również, że .mtl plik znajduje się w tym samym katalogu co .obj plik, ponieważ biblioteka rozwiązuje go względem .obj ścieżki.

Błędy formatu i I/O

openFromBuffer zgłasza błąd nieznanego formatu

Przyczyna źródłowa: Zawartość bufora nie jest rozpoznawalnym formatem binarnym lub bufor jest uszkodzony (obcięty, nieprawidłowe kodowanie lub base64 zamiast surowych bajtów).

Diagnoza:

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

Naprawa: Dla formatów tekstowych (OBJ, COLLADA) przekaż odpowiednią klasę opcji, aby zasugerować format:

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

Wyjściowy plik GLB otwiera się jako JSON w przeglądarkach 3D

Przyczyna źródłowa: GltfSaveOptions.binaryMode przyjmuje wartość domyślną false, generując .gltf wyjście w formacie JSON nawet gdy nazwa pliku wyjściowego jest .glb.

Naprawa: Jawnie ustaw binaryMode = true:

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

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

Wyjście STL nie zawiera danych o kolorze ani materiale w slicerze

Przyczyna źródłowa: Format STL nie obsługuje materiałów ani kolorów w swojej standardowej specyfikacji. Slicery obsługujące kolory używają własnych rozszerzeń, które nie są obsługiwane przez @aspose/3d.

Rozwiązanie: Eksportuj zamiast tego do formatu 3MF, który obsługuje metadane kolorów i materiałów:

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

Błędy kompilacji TypeScript

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

Przyczyna źródowa: Entity jest klasą bazową; Mesh jest konkretnym typem z właściwościami geometrycznymi. Potrzebujesz instanceof warunku przed dostępem do członków specyficznych dla siatki.

Rozwiązanie:

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'

Przyczyna źródowa: getChildNode() zwraca Node | null. Tryb ścisły TypeScript wymaga obsługi przypadku null.

Napraw:

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

Cannot find name 'GltfSaveOptions'

Przyczyna źródłowa: GltfSaveOptions jest w module podścieżki @aspose/3d/formats/gltf, nie w katalogu głównym pakietu.

Napraw: Importuj z podścieżki:

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

Problemy z pamięcią i wydajnością

Proces wyczerpuje pamięć przy dużych plikach FBX

Przyczyna źródłowa: Bardzo duże pliki FBX (>200 MB) przydzielają znaczną pamięć sterty. Domyślna sterta Node.js wynosi ~1,5 GB na systemach 64‑bitowych, ale może nie być wystarczająca dla plików wielosesyjnych.

Napraw: Zwiększ rozmiar sterty Node.js:

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

Przetwarzaj także pliki kolejno, a nie równolegle, gdy pamięć jest ograniczona:

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
}

Zobacz także

 Polski