Sådan indlæses 3D-modeller i TypeScript

Den @aspose/3d pakken giver TypeScript- og Node.js-applikationer et enkelt API til at åbne 3D-scene-filer. Scene er rodobjektet: kald scene.open() med en filsti og valgfrie format‑specifikke indlæsningsindstillinger, og derefter traversér scene.rootNode for at få adgang til geometri, materialer og transformationer.

Trin-for-trin guide

Trin 1: Installer @aspose/3d via npm

Tilføj pakken til dit projekt. Ingen native‑binære filer eller platforms‑specifikke build‑værktøjer er påkrævet; kun Node.js 18 eller nyere.

npm install @aspose/3d

For TypeScript‑projekter er type‑definitionerne medtaget i pakken:

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

Trin 2: Importér Scene og format‑specifikke indstillinger

Hvert format eksponerer sin egen loader‑klasse og options‑objekt under en under‑sti. Importér kun det, du har brug for:

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

Trin 3: Åbn en 3D‑fil ved hjælp af scene.open()

Opret en Scene instans, og kald derefter scene.open() med filstien og et valgfrit load‑options‑objekt. Kaldet 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 at indlæse fra en Buffer allerede i hukommelsen (nyttigt i serverløse eller streaming‑kontekster):

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

Trin 4: Iterér over scene‑noder

Scene‑grafen er et træ med rod i scene.rootNode. Hver Node kan indeholde underknuder 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);

Trin 5: Få adgang til mesh‑vertex‑data via controlPoints

Når en nodes enhed er en Mesh,kan du læse de rå kontrolpunkter (vertices) fra controlPoints array. Hver post 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)}`);
        }
    }
}

Trin 6: Konfigurér ObjLoadOptions for indlæsning af materialer

ObjLoadOptions eksponerer egenskaber til at styre, hvordan tilhørende .mtl materialefiler 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}`);
    }
}

Almindelige problemer og løsninger

Fejl: Kan ikke finde modulet ‘@aspose/3d/formats/obj’ Format-understierne kræver Node.js 12.7+ pakkeeksport. Sørg for, at du bruger Node.js 18 eller nyere. Hvis du bruger TypeScript, skal du sætte "moduleResolution": "node16" eller "bundler" i tsconfig.json.

scene.rootNode.childNodes er tom efter open() Nogle OBJ-filer bruger ikke-standard linjeafslutninger eller mangler et afsluttende linjeskift. Bekræft, at filen er en gyldig OBJ ved at åbne den i en teksteditor. Bekræft også, at du har videregivet ObjLoadOptions og ikke en generisk LoadOptions: de format-specifikke indstillinger er påkrævet for korrekt dispatch.

controlPoints-arrayet har nul længde Mesh’en kan være indlæst, men indeholder ingen geometri (f.eks. en tom gruppe i OBJ). Brug mesh.polygonCount til at tjekke, før du itererer over vertexer.

Hukommelsesforbruget er højt for store filer Load-from-buffer med scene.openFromBuffer() reducerer ikke peak-hukommelsen: hele filen skal parses. For store filer (> 100 MB) skal du sikre, at din Node.js-proces har tilstrækkelig heap: node --max-old-space-size=4096 yourScript.js.

Typefejl: ’entity’ er af typen ‘unknown’ Den entity egenskaben er bredt typet. Cast til any eller til en specifik klasse (Mesh, Camera, osv.) afhængigt af hvad du forventer i din scene.

Ofte stillede spørgsmål (FAQ)

Hvilke formater kan indlæses med scene.open()? OBJ, glTF 2.0 (.gltf + .bin), GLB, STL, 3MF, FBX og COLLADA (.dae) understøttes alle til import. Videregiv den tilsvarende *LoadOptions klasse for hvert format.

Kan jeg indlæse en fil uden at angive indstillinger? Ja. scene.open('model.glb') virker uden indstillinger for formater, der ikke kræver særlig konfiguration. Det anbefales at angive indstillinger for OBJ, fordi materialopløsning afhænger af enableMaterials.

Kører indlæsning asynkront? Nej. scene.open() og scene.openFromBuffer() er synkrone. Pak dem ind i en worker‑tråd eller setImmediate hvis du har brug for at holde en event‑loop responsiv.

Understøttes OBJ‑eksport? Ja. OBJ‑eksport understøttes via scene.save('output.obj'). Den .mtl materialfilen skrives automatisk ved siden af den .obj fil.

Hvor forventes .mtl-filen at være, når du indlæser OBJ? Som standard søger parseren efter .mtl fil, der refereres til inde i OBJ (mtllib directive) relativt til OBJ‑filens mappe. Sørg for, at begge filer er i den samme mappe.