Ako načítať 3D modely v TypeScript

The @aspose/3d balík poskytuje aplikáciám TypeScript a Node.js jednoduché API na otváranie 3D súborov scén. Scene je koreňový objekt: zavolajte scene.open() s cestou k súboru a voliteľnými možnosťami načítania špecifickými pre formát, potom prejdite scene.rootNode na prístup k geometrii, materiálom a transformáciám.

Postupný návod

Krok 1: Nainštalujte @aspose/3d cez npm

Pridajte balík do svojho projektu. Nie sú potrebné natívne binárky ani nástroje špecifické pre platformu; stačí Node.js 18 alebo novší.

npm install @aspose/3d

Pre TypeScript projekty sú definície typov zahrnuté v balíku:

##tsconfig.json: minimum required settings
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "strict": true
  }
}

Krok 2: Importujte Scene a možnosti špecifické pre formát

Každý formát poskytuje svoju vlastnú triedu načítača a objekt možností pod podcestou. Importujte len to, čo potrebujete:

import { Scene } from '@aspose/3d';
import { ObjLoadOptions } from '@aspose/3d/formats/obj';

Pre ostatné formáty je vzor rovnaký:

import { GltfLoadOptions } from '@aspose/3d/formats/gltf';
import { FbxLoadOptions } from '@aspose/3d/formats/fbx';
import { StlLoadOptions } from '@aspose/3d/formats/stl';

Krok 3: Otvorte 3D súbor pomocou scene.open()

Vytvorte Scene inštanciu, potom zavolajte scene.open() s cestou k súboru a voliteľným objektom load-options. Volanie je synchronné.

import { Scene } from '@aspose/3d';
import { ObjLoadOptions } from '@aspose/3d/formats/obj';

const scene = new Scene();
const options = new ObjLoadOptions();
options.enableMaterials = true;

scene.open('model.obj', options);
console.log('Scene loaded successfully');

Na načítanie z Buffer už v pamäti (užitočné v serverless alebo streamovacích kontextoch):

import * as fs from 'fs';
import { Scene } from '@aspose/3d';
import { ObjLoadOptions } from '@aspose/3d/formats/obj';

const buffer = fs.readFileSync('model.obj');
const scene = new Scene();
scene.openFromBuffer(buffer, new ObjLoadOptions());

Krok 4: Prechádzajte uzly scény

Graf scény je strom s koreňom v scene.rootNode. Node Každý entity môže obsahovať podriadené uzly a voliteľný.

import { Scene } from '@aspose/3d';
import { ObjLoadOptions } from '@aspose/3d/formats/obj';

const scene = new Scene();
scene.open('model.obj', new ObjLoadOptions());

function visitNode(node: any, depth: number = 0): void {
    const indent = '  '.repeat(depth);
    console.log(`${indent}Node: ${node.name}`);
    if (node.entity) {
        console.log(`${indent}  Entity type: ${node.entity.constructor.name}`);
    }
    for (const child of node.childNodes) {
        visitNode(child, depth + 1);
    }
}

visitNode(scene.rootNode);

Krok 5: Pristupujte k dátam vrcholov meshu cez controlPoints

(mesh, kamera, svetlo, atď.). Mesh,Keď je entita uzla , môžete čítať surové kontrolné body (vrcholy) z controlPoints pole. Každá položka je Vector4 s x, y, z, a w komponenty.

import { Scene } from '@aspose/3d';
import { ObjLoadOptions } from '@aspose/3d/formats/obj';

const scene = new Scene();
scene.open('model.obj', new ObjLoadOptions());

for (const node of scene.rootNode.childNodes) {
    if (!node.entity) continue;
    const entity = node.entity;
    // Check if the entity is a Mesh by duck-typing controlPoints
    if ('controlPoints' in entity) {
        const mesh = entity as any;
        console.log(`Mesh "${node.name}": ${mesh.controlPoints.length} vertices`);
        // Print first three vertices
        for (let i = 0; i < Math.min(3, mesh.controlPoints.length); i++) {
            const v = mesh.controlPoints[i];
            console.log(`  v[${i}]: x=${v.x.toFixed(4)}, y=${v.y.toFixed(4)}, z=${v.z.toFixed(4)}`);
        }
    }
}

Krok 6: Nakonfigurujte ObjLoadOptions pre načítanie materiálov

ObjLoadOptions zverejňuje vlastnosti na kontrolu toho, ako sa spracúvajú pripojené .mtl súbory materiálov a textúry sa riešia.

import { Scene } from '@aspose/3d';
import { ObjLoadOptions } from '@aspose/3d/formats/obj';

const options = new ObjLoadOptions();
options.enableMaterials = true;   // parse .mtl file if present

const scene = new Scene();
scene.open('model.obj', options);

// Inspect materials attached to nodes
for (const node of scene.rootNode.childNodes) {
    if (node.entity && node.entity.material) {
        console.log(`Material on "${node.name}": ${node.entity.material.constructor.name}`);
    }
}

Bežné problémy a riešenia

Chyba: Cannot find module ‘@aspose/3d/formats/obj’ Formátové podcesty vyžadujú exporty balíka Node.js 12.7+. Uistite sa, že používate Node.js 18 alebo novší. Ak používate TypeScript, nastavte "moduleResolution": "node16" alebo "bundler" v tsconfig.json.

scene.rootNode.childNodes je prázdny po open() Niektoré OBJ súbory používajú neštandardné konce riadkov alebo im chýba koncová nová línia. Overte, že súbor je platný OBJ otvorením v textovom editore. Tiež potvrďte, že ste odovzdali ObjLoadOptions a nie všeobecný LoadOptions: formátovo-špecifické možnosti sú potrebné pre správne smerovanie.

pole controlPoints má nulovú dĺžku Mriežka mohla byť načítaná, ale neobsahuje žiadnu geometriu (napr. prázdna skupina v OBJ). Použite mesh.polygonCount na kontrolu pred iteráciou vrcholov.

Využitie pamäte je vysoké pre veľké súbory Načítanie z bufferu s scene.openFromBuffer() neskracuje špičkové využitie pamäte: celý súbor musí byť analyzovaný. Pre veľké súbory (> 100 MB) zabezpečte, aby váš proces Node.js mal dostatočný heap: node --max-old-space-size=4096 yourScript.js.

Chyby typu: ’entity’ je typu ‘unknown’ The entity vlastnosť je typovaná široko. Pretypovať na any alebo na konkrétnu triedu (Mesh, Camera, atď.) v závislosti od toho, čo očakávate vo vašej scéne.

Často kladené otázky (FAQ)

Aké formáty je možné načítať pomocou scene.open()? Formáty OBJ, glTF 2.0 (.gltf + .bin), GLB, STL, 3MF, FBX a COLLADA (.dae) sú všetky podporované pre import. Odovzdajte príslušnú *LoadOptions triedu pre každý formát.

Môžem načítať súbor bez špecifikovania možností? Áno. scene.open('model.glb') funguje bez možností pre formáty, ktoré nevyžadujú špeciálnu konfiguráciu. Odovzdanie možností sa odporúča pre OBJ, pretože rozlíšenie materiálu závisí na enableMaterials.

Prebieha načítanie asynchrónne? Nie. scene.open() a scene.openFromBuffer() sú synchronné. Zabaľte ich do pracovného vlákna alebo setImmediate ak potrebujete udržať slučku udalostí responzívnu.

Je podporovaný export OBJ? Áno. Export OBJ je podporovaný cez scene.save('output.obj'). Súbor .mtl súbor materiálu sa automaticky zapíše vedľa the .obj súbor.

Kde sa očakáva .mtl súbor pri načítavaní OBJ? V predvolenom nastavení parser hľadá .mtl súbor odkazovaný v OBJ (mtllib directive) relatívne k adresáru súboru OBJ. Uistite sa, že oba súbory sú v rovnakom priečinku.