Hvordan laste 3D-modeller i TypeScript

Den @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 lastingsalternativer, så traverser scene.rootNode for å få tilgang til geometri, materialer og transformasjoner.

Steg-for-steg guide

Trinn 1: Installer @aspose/3d via npm

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

npm install @aspose/3d

For TypeScript‑prosjekter er type‑definisjonene 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 alternativ‑objekt 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';

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

Opprett en Scene instans, så kall scene.open() med filstien og et valgfrie lastingsalternativer‑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 allerede i minnet (nyttig i serverløse eller strømmingskontekster):

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

Trinn 4: Iterer over scenenoder

Scene‑grafen 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 den 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 lasting av materialer

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

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

Vanlige problemer og løsninger

Feil: Kan ikke finne modulen ‘@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 en avsluttende ny linje. Verifiser 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 distribusjon.

controlPoints-arrayet har null lengde Meshen 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 vertexer.

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

Typefeil: ’entity’ er av typen ‘unknown’ Den entity egenskapen er typet bredt. 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, FBX og COLLADA (.dae) støttes alle for import. Send den tilsvarende *LoadOptions klassen for hvert format.

Kan jeg laste en fil uten å spesifisere alternativer? Ja. scene.open('model.glb') fungerer uten alternativer for formater som ikke krever spesiell konfigurasjon. Å sende alternativer anbefales 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øype responsiv.

Støttes OBJ-eksport? Ja. OBJ-eksport støttes via scene.save('output.obj'). Den .mtl materialfilen skrives automatisk ved siden av den .obj fil.

Hvor forventes .mtl-filen når du laster OBJ? Som standard ser parseren etter .mtl fil referert i OBJ-en (mtllib directive) relativt til OBJ‑filens katalog. Sørg for at begge filene er i samme mappe.