Funksjoner og funksjonalitet

Aspose.3D FOSS for TypeScript er et MIT-lisensiert Node.js-bibliotek for lasting, konstruering og eksportering av 3D‑scener. Det leveres med komplette TypeScript‑type‑definisjoner, en enkelt kjøretidsavhengighet (xmldom), og støtte for seks store 3D‑filformater. Denne siden er den primære referansen for alle funksjonsområder og inneholder kjørbare TypeScript‑kodeeksempler for hver av dem.

Installasjon og oppsett

Installer pakken fra npm med en enkelt kommando:

npm install @aspose/3d

Pakken retter seg mot CommonJS og krever Node.js 18 eller nyere. Etter installasjon, verifiser at din tsconfig.json inkluderer følgende kompilatoralternativer for full kompatibilitet:

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

Importer hoved‑ Scene klassen fra pakkens rot. Format‑spesifikke alternativklasser 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';

Funksjoner og funksjonalitet

Formatstøtte

Aspose.3D FOSS for TypeScript leser og skriver seks store 3D‑filformater. Formatgjenkjenning er automatisk fra binære magiske tall ved lasting, så du trenger ikke å spesifisere kildeformatet eksplisitt.

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

Lagrer 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

All 3D-innhold er organisert som et tre av Node objekter med rot i scene.rootNode. Hver node kan bære en Entity (en Mesh, Camera, Light, eller andre SceneObject) og en Transform som posisjonerer den relativt til dens forelder.

Viktige scene‑grafklasser:

• Scene: den øverste beholderen; inneholder rootNode og animationClips
• Node: en navngitt tre-node med childNodes, entity, transform, og materials
• Entity: basisklasse for vedleggbare objekter (Mesh, Camera, Light)
• SceneObject: basisklasse delt av Node og Entity
• A3DObject: rotbasisklasse med name og egenskapspose
• Transform: lokal translasjon, rotasjon (Euler og Quaternion), og skalering

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

Opprette 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 geometritypen. Den utvider Geometry og eksponerer kontrollpunkter (vertikser), polygonindekser og vertex-elementer for normaler, UV-er og vertex-farger.

Viktige geometriklasser:

• Mesh: polygonnett med controlPoints og polygonCount
• Geometry: basisklasse med vertex-elementhåndtering
• VertexElementNormal: per-vertex eller per-polygon-vertex normaler
• VertexElementUV: teksturkoordinater (en eller flere UV-kanaler)
• VertexElementVertexColor: per-vertex fargedata
• MappingMode: styrer hvordan elementdata kartlegges til polygoner (CONTROL_POINT, POLYGON_VERTEX, POLYGON, EDGE, ALL_SAME)
• ReferenceMode: styrer indekseringsstrategi (DIRECT, INDEX, INDEX_TO_DIRECT)
• VertexElementType: identifiserer semantikken til et vertex-element
• TextureMapping: opptelling av teksturkanaler

Lese mesh-data fra en lastet 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 støtter tre materialtyper som dekker hele spekteret fra eldre Phong-skygging til fysisk-basert rendering:

• LambertMaterial: diffus farge og omgivelsesfarge; kartlegger til enkle OBJ/DAE-materialer
• PhongMaterial: legger til specular-farge, glans og emissiv; standard OBJ-materialtype
• PbrMaterial: fysisk-basert roughness/metallic-modell; brukt for glTF 2.0-import og -eksport

Leser materialer fra en lastet 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)}`);
    }
  }
}

Bruk av et PBR-materiale når du bygger en glTF-scene:

import { Scene, Node, PbrMaterial } from '@aspose/3d';
import { Vector3 } 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);   // red-tinted albedo; 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);

Matematikkverktøy

Biblioteket leveres med et komplett sett av 3D-mattematikk-typer, alle fullt typet:

• Vector3: 3-komponentvektor; støtter minus(), times(), dot(), cross(), normalize(), length, angleBetween()
• Vector4: 4-komponentvektor for homogene koordinater
• Matrix4: 4×4 transformasjonsmatrise med concatenate(), transpose, decompose, setTRS
• Quaternion: rotasjonskvaternion med fromEulerAngle() (statisk, entydig), eulerAngles() (instansmetode), slerp(), normalize()
• BoundingBox: aksejustert begrensningsboks med minimum, maximum, center, size, merge
• FVector3: enkeltpresisjonsvariant av Vector3 brukt i vertex-elementdata

Beregn en begrensningsboks 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);

Bygger en transformasjon 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));

Animasjonssystem

Animasjons-API-et modellerer klipp, noder, kanaler og keyframe-sekvenser:

• AnimationClip: navngitt samling av animasjonsnoder; aksessert via scene.animationClips; eksponerer animations: AnimationNode[]
• AnimationNode: navngitt gruppe av BindPoints; opprettet via clip.createAnimationNode(name), aksessert via clip.animations
• BindPoint: binder en AnimationNode til en spesifikk egenskap på et sceneobjekt; eksponerer property og channelsCount
• AnimationChannel: utvider KeyframeSequence; holder en separat keyframeSequence; aksessert via bindPoint.getChannel(name)
• KeyFrame: et enkelt tids-/verdi-par; bærer per-nøkkelbilde interpolation: Interpolation
• KeyframeSequence: sortert liste over KeyFrame objekter via keyFrames; har preBehavior og postBehavior (Extrapolation)
• Interpolation: enum: LINEAR, CONSTANT, BEZIER, B_SPLINE, CARDINAL_SPLINE, TCB_SPLINE
• Extrapolation: klasse med type: ExtrapolationType og repeatCount: number
• ExtrapolationType: enum: CONSTANT, GRADIENT, CYCLE, CYCLE_RELATIVE, OSCILLATE

Lese animasjonsdata fra en lastet scene:

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

const scene = new Scene();
scene.open('animated.dae');   // COLLADA animation import is supported

for (const clip of scene.animationClips) {
  console.log(`Clip: "${clip.name}"`);
  for (const animNode of clip.animations) {          // clip.animations, not clip.nodes
    console.log(`  AnimationNode: ${animNode.name}`);
    for (const bp of animNode.bindPoints) {           // animNode.bindPoints, not animNode.channels
      console.log(`  BindPoint: property="${bp.property.name}", channels=${bp.channelsCount}`);
    }
  }
}

Strøm- og bufferstøtte

Bruk scene.openFromBuffer() for å laste en 3D-scene direkte fra minnet Buffer. Dette er det anbefalte mønsteret for serverløse funksjoner, strømmings‑pipelines og behandling av ressurser hentet over HTTP uten å 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 formatgjenkjenning fra binære magiske tall gjelder ved lasting fra buffer, så GLB-, STL‑binary- og 3MF‑filer blir gjenkjent uten å måtte angi en formatparameter.

Brukseksempler

Eksempel 1: Last inn OBJ og eksporter til GLB

Dette eksemplet laster inn en Wavefront OBJ‑fil med materialer, og eksporterer deretter scenen på nytt som en binær glTF (GLB)-fil som er egnet for bruk på nett og i spillmotorer.

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 eksemplet laster inn en binær STL‑fil, skriver ut normalinformasjon per vertex, og eksporterer deretter scenen på nytt som ASCII STL og verifiserer rundreisen.

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: Bygg en scene programmatisk og lagre som glTF

Dette eksemplet konstruerer en scene med et PBR-materiale fra bunnen av og lagrer den som en JSON glTF-fil.

import { Scene, Mesh, PbrMaterial, Vector4, Vector3 } 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 beste praksis

• Bruk ObjLoadOptions.enableMaterials = true når du trenger materialdata fra .mtl‑filer. Uten den vil materiallisten på hver node være tom.
• Foretrekk binaryMode = true for GLB når du produserer ressurser for nett eller spillmotorer. Binær GLB er en enkelt selvstendig fil og lastes raskere i nettlesere og motorer enn JSON + .bin-delingen.
• Bruk openFromBuffer() i serverløse miljøer for å unngå midlertidig fil‑I/O. Hent ressursen, send Buffer direkte, og skriv utdata til en strøm eller en annen buffer.
• Sjekk node.entity før du kaster: ikke alle noder har en enhet. Beskytt alltid med en instanceof sjekk før du får tilgang til Mesh-spesifikke egenskaper som controlPoints.
• Sett normalizeNormal = true i ObjLoadOptions når kilde‑OBJ‑filene dine kommer fra upålitelige kilder. Dette forhindrer degenererte normaler i å spre seg inn i nedstrøms rendering‑ eller valideringssteg.
• Behold strict: true i tsconfig.json: biblioteket er skrevet med noImplicitAny og strictNullChecks. Deaktivering strict maskerer ekte typefeil og undergraver verdien av den typede API-en.
• Traverser via childNodes, ikke en indeksløkke: den childNodes egenskapen returnerer en iterabel; unngå å stole på numerisk indeksering for fremtidig kompatibilitet.

Vanlige problemer

Ofte stilte spørsmål

Krever biblioteket noen native-tillegg eller systempakker? Nei. Aspose.3D FOSS for TypeScript har en enkelt runtime‑avhengighet: xmldom, som er ren JavaScript og installeres automatisk av npm. Det finnes ingen .node native‑tillegg og ingen systempakker å installere.

Hvilke Node.js‑versjoner støttes? Node.js 18, 20 og 22 LTS. Biblioteket retter seg mot CommonJS-utdata og bruker ES2020-språkfunksjoner internt.

Kan jeg bruke biblioteket i en nettleserpakke (webpack/esbuild)? Biblioteket retter seg mot Node.js og bruker Node.js fs og Buffer API-er. Nettleser‑pakking støttes ikke offisielt. For bruk i nettleser, last inn scenen på server‑siden og overfør resultatet (f.eks. som GLB) til klienten.

Hva er forskjellen mellom GltfSaveOptions.binaryMode = true og false? binaryMode = false produserer en .gltf JSON‑fil pluss en separat .bin binær buffer‑sidecar. binaryMode = true produserer en enkelt selvstendig .glb fil. Bruk true for produksjons‑levering av ressurser.

Kan jeg laste inn en fil fra et HTTP‑svar uten å lagre den til disk? Ja. Hent svaret som en Buffer (f.eks. ved å bruke node-fetch eller den innebygde fetch i Node 18+), og deretter kall scene.openFromBuffer(buffer, options).

Er FBX‑støtte komplett? Nei. FBX‑import‑ og eksportklasser finnes i biblioteket, men FBX er ikke integrert i Scene.open() eller Scene.save() automatisk gjenkjenning. Å kalle scene.open('file.fbx') vil ikke aktivere FBX-importøren; filen vil bli håndtert av STL-reserveveien. Bruk de FBX-spesifikke import-/eksportklassene direkte hvis du trenger FBX I/O. Se formatstøttabellen ovenfor som merker FBX som No*.

Støtter biblioteket TypeScript 4.x? TypeScript 5.0+ anbefales. TypeScript 4.7+ bør fungere i praksis, men biblioteket er testet og skrevet mot 5.0+.

API-referansesammendrag