Funktioner og funktionaliteter

Aspose.3D FOSS for TypeScript er et MIT-licenseret Node.js-bibliotek til indlæsning, konstruktion og eksport af 3D-scener. Det leveres med komplette TypeScript-typedefinitioner, en enkelt runtime-afhængighed (xmldom), og understøttelse af seks store 3D-filformater. Denne side er den primære reference for alle funktionsområder og indeholder kørbare TypeScript-kodeeksempler for hver af dem.

Installation og opsætning

Installer pakken fra npm med en enkelt kommando:

npm install @aspose/3d

Pakken målretter CommonJS og kræver Node.js 18 eller senere. Efter installationen skal du verificere, at din tsconfig.json inkluderer følgende kompilatorindstillinger for fuld kompatibilitet:

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

Importér den primære Scene klasse fra pakkens rod. Format‑specifikke optionsklasser importeres fra deres respektive understier:

import { Scene } from '@aspose/3d';
import { ObjLoadOptions } from '@aspose/3d/formats/obj';
import { GltfSaveOptions, GltfFormat } from '@aspose/3d/formats/gltf';

Funktioner og funktionaliteter

Formatunderstøttelse

Aspose.3D FOSS for TypeScript læser og skriver seks store 3D-filformater. Formatdetektering er automatisk ud fra binære magiske tal ved indlæsning, så du behøver ikke angive kildeformatet eksplicit.

Indlæsning af OBJ med materialer:

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

const scene = new Scene();
const options = new ObjLoadOptions();
options.enableMaterials = true;
options.flipCoordinateSystem = false;
options.scale = 1.0;
options.normalizeNormal = true;
scene.open('model.obj', options);

Gemning til GLB (binær glTF):

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

const scene = new Scene();
// ... build or load scene content

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

Scenegraf

Alt 3D-indhold er organiseret som et træ af Node objekter rodfæstet ved scene.rootNode. Hver node kan bære en Entity (en Mesh, Camera, Light, eller andre SceneObject) Transform og en.

Vigtige scene‑graph‑klasser:

• Scene: den øverste niveau beholder; indeholder rootNode og animationClips
• Node: en navngivet trænode med childNodes, entity, transform, materials
• Entity: grundklasse for vedhæftelige objekter (Mesh, Camera, Light)
• SceneObject: grundklasse delt af Node og Entity
• A3DObject: rodgrundklasse med name og egenskabspose
• Transform: lokal translation, rotation (Euler og Quaternion) og skalering

Gennemløb af scene‑grafen:

import { Scene, Node, Mesh } from '@aspose/3d';

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

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

visit(scene.rootNode);

Oprettelse af et scenehierarki programmatisk:

import { Scene, Node } from '@aspose/3d';

const scene = new Scene();
const parent = scene.rootNode.createChildNode('chassis');
const wheel = parent.createChildNode('wheel_fl');
wheel.transform.translation.set(0.9, -0.3, 1.4);

Geometri og Mesh

Mesh er den primære geometritype. Den udvider Geometry og eksponerer kontrolpunkter (vertices), polygonindekser og vertex-elementer for normals, UVs og vertex-farver.

Vigtige geometri‑klasser:

• Mesh: polygonnet med controlPoints og polygonCount
• Geometry: grundklasse med vertex-elementhåndtering
• VertexElementNormal: per-vertex eller per-polygon-vertex normale
• VertexElementUV: teksturkoordinater (en eller flere UV-kanaler)
• VertexElementVertexColor: per-vertex farvedata
• MappingMode: styrer hvordan elementdata kortlægges til polygoner (ByControlPoint, ByPolygonVertex, osv.)
• ReferenceMode: styrer indekseringsstrategi (Direct, IndexToDirect)
• VertexElementType: identificerer semantikken for et vertex-element
• TextureMapping: teksturkanal-opsummering

Læser mesh-data fra en indlæst scene:

import { Scene, Mesh, VertexElementType } from '@aspose/3d';

const scene = new Scene();
scene.open('model.stl');

for (const node of scene.rootNode.childNodes) {
  if (node.entity instanceof Mesh) {
    const mesh = node.entity as Mesh;
    console.log(`Mesh "${node.name}": ${mesh.controlPoints.length} vertices, ${mesh.polygonCount} polygons`);

    const normals = mesh.getElement(VertexElementType.NORMAL);
    if (normals) {
      console.log(`  Normal mapping: ${normals.mappingMode}`);
    }
  }
}

Materialsystem

Aspose.3D FOSS for TypeScript understøtter tre materialetyper, der dækker hele spektret fra ældre Phong-shading til fysisk baseret rendering:

• LambertMaterial: diffus farve og omgivende farve; kortlægges til simple OBJ/DAE-materialer
• PhongMaterial: tilføjer spekulær farve, glans og emissiv; standard OBJ-materialetype
• PbrMaterial: fysisk-baseret ruhed/metallisk model; bruges til glTF 2.0-import og -eksport

Læser materialer fra en indlæst OBJ-scene:

import { Scene, PhongMaterial, LambertMaterial } 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);

for (const node of scene.rootNode.childNodes) {
  for (const mat of node.materials) {
    if (mat instanceof PhongMaterial) {
      const phong = mat as PhongMaterial;
      console.log(`  Phong: diffuse=${JSON.stringify(phong.diffuseColor)}, shininess=${phong.shininess}`);
    } else if (mat instanceof LambertMaterial) {
      console.log(`  Lambert: diffuse=${JSON.stringify((mat as LambertMaterial).diffuseColor)}`);
    }
  }
}

Anvender et PBR-materiale ved opbygning af en glTF-scene:

import { Scene, Node, PbrMaterial } from '@aspose/3d';
import { GltfSaveOptions, GltfFormat } from '@aspose/3d/formats/gltf';

const scene = new Scene();
const node = scene.rootNode.createChildNode('sphere');
const mat = new PbrMaterial();
mat.albedo = new Vector3(0.8, 0.2, 0.2);   // albedo starts null, must assign
mat.metallicFactor = 0.0;
mat.roughnessFactor = 0.5;
node.material = mat;

const opts = new GltfSaveOptions();
opts.binaryMode = false;
scene.save('output.gltf', GltfFormat.getInstance(), opts);

Matematikværktøjer

Biblioteket leveres med et komplet sæt af 3D-matematiktyper, alle fuldt typede:

• Vector3: 3-komponents vektor; understøtter add, subtract, scale, dot, cross, normalize, length
• Vector4: 4-komponents vektor for homogene koordinater
• Matrix4: 4×4 transformationsmatrix med multiply, invert, transpose, decompose
• Quaternion: rotationskvaternion med fromEulerAngles, toEulerAngles, slerp, normalize
• BoundingBox: aksejusteret begrænsningsboks med min, max, center, size, merge
• FVector3:single-precision-variant af Vector3 brugt i vertex-elementdata

Beregning af en afgrænsningsboks ud fra mesh-vertexer:

import { Scene, Mesh, Vector3, BoundingBox } from '@aspose/3d';

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

let box = new BoundingBox();
for (const node of scene.rootNode.childNodes) {
  if (node.entity instanceof Mesh) {
    for (const pt of (node.entity as Mesh).controlPoints) {
      box.merge(new Vector3(pt.x, pt.y, pt.z));
    }
  }
}
console.log('Center:', box.center);
console.log('Extents:', box.size);

Opbygning af en transformation ud fra Euler-vinkler:

import { Quaternion, Vector3, Matrix4 } from '@aspose/3d';

const rot = Quaternion.fromEulerAngle(0, Math.PI / 4, 0); // 45° around Y
const mat = new Matrix4();
mat.setTRS(new Vector3(0, 0, 0), rot, new Vector3(1, 1, 1));

Animationssystem

Animations-API’en modellerer klip, noder, kanaler og keyframe‑sekvenser:

• AnimationClip: navngivet samling af animationsnoder; tilgået via scene.animationClips
• AnimationNode: binder et klip til en scenenode efter navn
• AnimationChannel: målretter en specifik egenskab (f.eks. translation X) inden for en animationsnode
• KeyFrame: et enkelt tid/værdi-par
• KeyframeSequence: ordnet liste over KeyFrame objekter med Interpolation og Extrapolation indstillinger
• Interpolation: keyframe-interpolationsmode: Linear, Constant, Cubic
• Extrapolation: opførsel før/efter keyframe-intervallet: Constant, Cycle, Mirror

Læsning af animationsdata fra en indlæst scene:

import { Scene, AnimationClip, KeyframeSequence } from '@aspose/3d';

const scene = new Scene();
scene.open('animated.fbx');

for (const clip of scene.animationClips) {
  console.log(`Clip: "${clip.name}"`);
  for (const animNode of clip.nodes) {
    console.log(`  Node: ${animNode.name}`);
    for (const channel of animNode.channels) {
      const seq: KeyframeSequence = channel.keyframeSequence;
      console.log(`    Channel "${channel.name}": ${seq.keyFrames.length} keyframes`);
      console.log(`    Interpolation: ${seq.interpolation}`);
    }
  }
}

Stream‑ og Buffer‑understøttelse

Brug scene.openFromBuffer() til at indlæse en 3D-scene direkte fra en in-memory Buffer. Dette er det anbefalede mønster for serverløse funktioner, streaming-pipelines og behandling af assets hentet over HTTP uden at skrive til disk.

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

// Load file into memory, then parse from buffer
const buffer: Buffer = fs.readFileSync('model.obj');
const scene = new Scene();
const options = new ObjLoadOptions();
options.enableMaterials = true;
scene.openFromBuffer(buffer, options);

for (const node of scene.rootNode.childNodes) {
  if (node.entity) {
    console.log(node.name, node.entity.constructor.name);
  }
}

Automatisk formatgenkendelse ud fra binære magiske tal gælder ved indlæsning fra buffer, så GLB-, STL‑binary‑ og 3MF‑filer genkendes uden at angive en formatparameter.

Brugseksempler

Eksempel 1: Indlæs OBJ og Eksporter til GLB

Dette eksempel indlæser en Wavefront OBJ-fil med materialer, og eksporterer derefter scenen som en binær glTF (GLB)-fil, der er egnet til brug på web og i spilmotorer.

import { Scene } from '@aspose/3d';
import { ObjLoadOptions } from '@aspose/3d/formats/obj';
import { GltfSaveOptions, GltfFormat } from '@aspose/3d/formats/gltf';

function convertObjToGlb(inputPath: string, outputPath: string): void {
  const scene = new Scene();

  const loadOpts = new ObjLoadOptions();
  loadOpts.enableMaterials = true;
  loadOpts.flipCoordinateSystem = false;
  loadOpts.normalizeNormal = true;
  scene.open(inputPath, loadOpts);

  // Report what was loaded
  for (const node of scene.rootNode.childNodes) {
    if (node.entity) {
      console.log(`Loaded: ${node.name} (${node.entity.constructor.name})`);
    }
  }

  const saveOpts = new GltfSaveOptions();
  saveOpts.binaryMode = true; // write .glb instead of .gltf + .bin
  scene.save(outputPath, GltfFormat.getInstance(), saveOpts);

  console.log(`Exported GLB to: ${outputPath}`);
}

convertObjToGlb('input.obj', 'output.glb');

Eksempel 2: Rundtur STL med Normalvalidering

Dette eksempel indlæser en binær STL-fil, udskriver normalinformation pr. vertex, og eksporterer derefter scenen som ASCII STL og verificerer rundturen.

import { Scene, Mesh, VertexElementNormal, VertexElementType } from '@aspose/3d';
import { StlLoadOptions, StlSaveOptions } from '@aspose/3d/formats/stl';

const scene = new Scene();
const loadOpts = new StlLoadOptions();
scene.open('model.stl', loadOpts);

let totalPolygons = 0;
for (const node of scene.rootNode.childNodes) {
  if (node.entity instanceof Mesh) {
    const mesh = node.entity as Mesh;
    totalPolygons += mesh.polygonCount;

    const normElem = mesh.getElement(VertexElementType.NORMAL) as VertexElementNormal | null;
    if (normElem) {
      console.log(`  Normals: ${normElem.data.length} entries, mapping=${normElem.mappingMode}`);
    }
  }
}
console.log(`Total polygons: ${totalPolygons}`);

// Re-export as ASCII STL
const saveOpts = new StlSaveOptions();
saveOpts.binaryMode = false; // ASCII output
scene.save('output_ascii.stl', saveOpts);

Eksempel 3: Byg en scene programmatisk og gem som glTF

Dette eksempel konstruerer en scene med et PBR-materiale fra bunden og gemmer den som en JSON glTF-fil.

import { Scene, Mesh, PbrMaterial, Vector4 } from '@aspose/3d';
import { GltfSaveOptions, GltfFormat } from '@aspose/3d/formats/gltf';

const scene = new Scene();
const node = scene.rootNode.createChildNode('floor');

// Build a simple quad mesh (two triangles)
// controlPoints are Vector4 (x, y, z, w) where w=1 for positions
const mesh = new Mesh();
mesh.controlPoints.push(
  new Vector4(-1, 0, -1, 1),
  new Vector4( 1, 0, -1, 1),
  new Vector4( 1, 0,  1, 1),
  new Vector4(-1, 0,  1, 1),
);
mesh.createPolygon([0, 1, 2]);
mesh.createPolygon([0, 2, 3]);
node.entity = mesh;

// Apply a PBR material
const mat = new PbrMaterial();
mat.albedo = new Vector3(0.6, 0.6, 0.6);   // albedo starts null, must assign
mat.metallicFactor = 0.0;
mat.roughnessFactor = 0.8;
node.material = mat;

// Save as JSON glTF
const opts = new GltfSaveOptions();
opts.binaryMode = false;
scene.save('floor.gltf', GltfFormat.getInstance(), opts);
console.log('Scene written to floor.gltf');

Tips og bedste praksis

• Brug ObjLoadOptions.enableMaterials = true når du har brug for materialedata fra .mtl-filer. Uden dem vil materialelisten på hver node være tom.
• Foretræk binaryMode = true til GLB når du producerer assets til web- eller spilmotorer. Binær GLB er en enkelt selvstændig fil og indlæses hurtigere i browsere og motorer end JSON + .bin-opdelingen.
• Brug openFromBuffer() i serverløse miljøer for at undgå midlertidig fil‑I/O. Hent assettet, videregiv den Buffer direkte, og skriv outputtet til en stream eller en anden buffer.
• Tjek node.entity før du caster: ikke alle noder bærer en entitet. Beskyt altid med en instanceof tjek før du får adgang til Mesh-specifikke egenskaber såsom controlPoints.
• Sæt normalizeNormal = true i ObjLoadOptions når dine kilde‑OBJ‑filer kommer fra upålidelige kilder. Dette forhindrer degenererede normaler i at sprede sig til efterfølgende renderings‑ eller valideringsprocesser.
• Bevar strict: true i tsconfig.json: biblioteket er skrevet med noImplicitAny og strictNullChecks. Deaktivering strict maskerer reelle typefejl og underminerer værdien af den typede API.
• Traversér via childNodes, ikke en indeksløkke: den childNodes egenskaben returnerer en iterabel; undgå at stole på numerisk indeksering for fremadrettet kompatibilitet.

Almindelige problemer

Ofte stillede spørgsmål

Kræver biblioteket nogen native-tilføjelser eller systempakker? Nej. Aspose.3D FOSS for TypeScript har kun én runtime-afhængighed: xmldom, som er ren JavaScript og installeres automatisk af npm. Der er ingen .node native addons og ingen systempakker at installere.

Hvilke Node.js-versioner understøttes? Node.js 18, 20 og 22 LTS. Biblioteket har som mål CommonJS-output og bruger ES2020-sprogfunktioner internt.

Kan jeg bruge biblioteket i en browserpakke (webpack/esbuild)? Biblioteket har som mål Node.js og bruger Node.js fs og Buffer API’er. Browserpakning understøttes ikke officielt. Til brug i browseren skal du indlæse scenen på serveren og overføre resultatet (f.eks. som GLB) til klienten.

Hvad er forskellen mellem GltfSaveOptions.binaryMode = true og false? binaryMode = false producerer en .gltf JSON-fil plus en separat .bin binær buffer-sidecar. binaryMode = true producerer en enkelt selvstændig .glb fil. Brug true til levering af produktions‑assets.

Kan jeg indlæse en fil fra et HTTP-svar uden at gemme den på disk? Ja. Hent svaret som en Buffer (f.eks. ved at bruge node-fetch eller den indbyggede fetch i Node 18+), så kald scene.openFromBuffer(buffer, options).

Er FBX-understøttelsen komplet? FBX-læsning og -skrivning understøttes for scenehierarki, mesh- og geometridata, animationsklip og materialer. Meget komplekse FBX-filer med indlejret medie kan give delvise resultater; test med dit specifikke asset‑korpus.

Understøtter biblioteket TypeScript 4.x? TypeScript 5.0+ anbefales. TypeScript 4.7+ bør fungere i praksis, men biblioteket er testet og udviklet mod 5.0+.

API-referencens oversigt