Hvordan laste 3D-modeller i TypeScript

@aspose/3d-pakken gir TypeScript- og Node.js-applikasjoner et enkelt API for å åpne 3D-scene-filer. Scene er rotobjektet: kall scene.open() med en filsti og valgfrie formatspesifikke lastalternativer, og deretter traverser scene.rootNode for å få tilgang til geometri, materialer og transformasjoner.

Steg-for-steg guide

Steg 1: Installer @aspose/3d via npm

Legg til pakken i prosjektet ditt. Ingen native binærfiler eller plattformspesifikke byggverktøy er påkrevd; kun Node.js 18 eller nyere.

npm install @aspose/3d

For TypeScript‑prosjekter er type‑definisjoner pakket med pakken:

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

Trinn 2: Importer scene og formatspesifikke alternativer

Hvert format eksponerer sin egen loader‑klasse og alternativobjekt under en understi. Importer kun det du trenger:

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

For andre formater er mønsteret identisk:

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

Steg 3: Åpne en 3D‑fil ved å bruke scene.open()

Opprett en Scene‑instans, og kall deretter scene.open() med filstien og et valgfritt load‑options‑objekt. Kallet er synkront.

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

For å laste fra en Buffer som allerede er i minnet (nyttig i serverløse eller strømmekontekster):

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

Steg 4: Iterer over scenenoder

Scenegraphen er et tre med rot i scene.rootNode. Hver Node kan inneholde undernoder og en valgfri entity (mesh, kamera, lys, osv.).

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

Trinn 5: Få tilgang til mesh vertex data via controlPoints

Når en nodes enhet er en Mesh, kan du lese de rå kontrollpunktene (vertices) fra controlPoints array. Hvert element er en Vector4 med x, y, z og w komponenter.

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

Trinn 6: Konfigurer ObjLoadOptions for materiallasting

ObjLoadOptions eksponerer egenskaper for å kontrollere hvordan tilhørende .mtl materialfiler og teksturer løses.

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.material) {
        console.log(`Material on "${node.name}": ${node.material.constructor.name}`);
    }
}

Vanlige problemer og løsninger

Error: Cannot find module ‘@aspose/3d/formats/obj’
Format-understiene krever Node.js 12.7+ pakkeeksporter. Sørg for at du bruker Node.js 18 eller nyere. Hvis du bruker TypeScript, sett "moduleResolution": "node16" eller "bundler" i tsconfig.json.

scene.rootNode.childNodes er tom etter open()
Noen OBJ-filer bruker ikke‑standard linjeskift eller mangler et avsluttende linjeskift. Bekreft at filen er en gyldig OBJ ved å åpne den i en teksteditor. Bekreft også at du har sendt ObjLoadOptions og ikke en generisk LoadOptions: formatspesifikke alternativer er påkrevd for korrekt håndtering.

controlPoints array har null lengde
Mesh‑en kan ha blitt lastet, men inneholder ingen geometri (f.eks. en tom gruppe i OBJ). Bruk mesh.polygonCount for å sjekke før du itererer over vertikser.

Minnebruk er høy for store filer
Load-from-buffer med scene.openFromBuffer() reduserer ikke toppminnet: hele filen må parses. For store filer (> 100 MB), sørg for at Node.js‑prosessen har tilstrekkelig heap: node --max-old-space-size=4096 yourScript.js.

Typefeil: ’entity’ er av typen ‘unknown’
Egenskapen entity er bredt typet. Kast til any eller til en spesifikk klasse (Mesh, Camera, osv.) avhengig av hva du forventer i scenen din.

Ofte stilte spørsmål (FAQ)

Hvilke formater kan lastes med scene.open()? OBJ, glTF 2.0 (.gltf + .bin), GLB, STL, 3MF og COLLADA (.dae) støttes alle for import. Send inn den tilsvarende *LoadOptions-klassen for hvert format.

Kan jeg laste inn en fil uten å spesifisere alternativer?
Ja. scene.open('model.glb') fungerer uten alternativer for formater som ikke krever spesiell konfigurasjon. Det anbefales å bruke alternativer for OBJ fordi materialoppløsning avhenger av enableMaterials.

Kjører lasting asynkront?
Nei. scene.open() og scene.openFromBuffer() er synkrone. Pakk dem inn i en arbeidstråd eller setImmediate hvis du trenger å holde en hendelsesløkke responsiv.

Er OBJ-eksport støttet? Ja. OBJ-eksport støttes via scene.save('output.obj'). .mtl-materialfilen skrives automatisk ved siden av .obj-filen.

Hvor forventes .mtl-filen når du laster inn OBJ? Som standard ser parseren etter .mtl-filen som refereres inne i OBJ (mtllib-direktivet) relativt til OBJ-filens katalog. Sørg for at begge filene er i samme mappe.