Functies en functionaliteiten

Aspose.3D FOSS voor TypeScript is een MIT-gelicentieerde Node.js-bibliotheek voor het laden, construeren en exporteren van 3D‑scènes. Het wordt geleverd met volledige TypeScript-typedefinities, één runtime‑afhankelijkheid (xmldom).

Installatie en configuratie

Installeer het pakket van npm met één enkele opdracht:

npm install @aspose/3d

Het pakket richt zich op CommonJS en vereist Node.js 18 of hoger. Na installatie, controleer uw tsconfig.json bevat de volgende compileropties voor volledige compatibiliteit:

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

Importeer de hoofd Scene klasse vanuit de pakket‑root. Formaat‑specifieke optieklassen worden geïmporteerd vanuit hun respectieve sub‑paden:

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

Functies en functionaliteiten

Formaatondersteuning

Aspose.3D FOSS for TypeScript leest en schrijft zes belangrijke 3D‑bestandformaten. Formaatdetectie gebeurt automatisch op basis van binaire magic numbers bij het laden, zodat u het bronformaat niet expliciet hoeft op te geven.

OBJ laden met materialen:

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

Opslaan naar GLB (binaire 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);

Scene‑graph

Alle 3D-inhoud is georganiseerd als een boom van Node objecten met wortel bij scene.rootNode. Elke knoop kan een Entity (een Mesh, Camera, Light, of andere SceneObject) en een Transform die het positioneert ten opzichte van zijn ouder.

Belangrijke scene‑graph‑klassen:

• Scene: de bovenste container; bevat rootNode en animationClips
• Node: een benoemd boomknooppunt met childNodes, entity, transform, en materials
• Entity: basisklasse voor koppelbare objecten (Mesh, Camera, Light)
• SceneObject: basisklasse gedeeld door Node en Entity
• A3DObject: wortelbasisklasse met name en eigenschapszak
• Transform: lokale translatie, rotatie (Euler en Quaternion), en schaal

Doorlopen van de scene‑graph:

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

Een scenahiërarchie programmatically maken:

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

Geometrie en Mesh

Mesh is het primaire geometrie-type. Het breidt uit Geometry en exposeert controlepunten (vertices), polygoonindices en vertex-elementen voor normalen, UV’s en vertexkleuren.

Belangrijke geometrieklassen:

• Mesh: polygoonmesh met controlPoints en polygonCount
• Geometry: basisklasse met vertex-elementbeheer
• VertexElementNormal: per-vertex of per-polygon-vertex normalen
• VertexElementUV: textuurcoördinaten (een of meer UV-kanalen)
• VertexElementVertexColor: per-vertex kleurgegevens
• MappingMode: bepaalt hoe elementgegevens naar polygonen worden gemapt (CONTROL_POINT, POLYGON_VERTEX, POLYGON, EDGE, ALL_SAME)
• ReferenceMode: beheert indexeringsstrategie (DIRECT, INDEX, INDEX_TO_DIRECT)
• VertexElementType: identificeert de semantiek van een vertex element
• TextureMapping: enumeratie van textuurkanalen

Mesh-gegevens lezen uit een geladen scène:

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

Materiaal Systeem

Aspose.3D FOSS voor TypeScript ondersteunt drie materiaalt types die het volledige bereik dekken van legacy Phong shading tot fysiek gebaseerde rendering:

• LambertMaterial: diffuse kleur en ambient kleur; map naar eenvoudige OBJ/DAE-materialen
• PhongMaterial: voegt specular kleur, glans en emissief toe; het standaard OBJ-materiaaltype
• PbrMaterial: fysiek-gebaseerd roughness/metallic model; gebruikt voor glTF 2.0-import en -export

Materialen lezen uit een geladen OBJ‑scène:

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

Een PBR‑materiaal toepassen bij het bouwen van een glTF‑scène:

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

Wiskundige hulpprogramma’s

De bibliotheek wordt geleverd met een volledige set 3D‑wiskundige types, allemaal volledig getypeerd:

• Vector3: 3-componentenvector; ondersteunt minus(), times(), dot(), cross(), normalize(), length, angleBetween()
• Vector4: 4-componentenvector voor homogene coördinaten
• Matrix4: 4×4 transformatiesmatrix met concatenate(), transpose, decompose, setTRS
• Quaternion: rotatiequaternion met fromEulerAngle() (statisch, enkelvoud), eulerAngles() (instantiemethode), slerp(), normalize()
• BoundingBox: asgeoriënteerde begrenzingsvak met minimum, maximum, center, size, merge
• FVector3: single-precision variant van Vector3 : gebruikt in vertex element-gegevens

Een begrenzingsdoos berekenen vanuit mesh‑vertices:

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

Een transformatie opbouwen vanuit Euler‑hoeken:

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

Animatiesysteem

De animatie‑API modelleert clips, knooppunten, kanalen en keyframe‑reeksen:

• AnimationClip: genaamde collectie van animatieknooppunten; benaderd via scene.animationClips; exposeert animations: AnimationNode[]
• AnimationNode: genoemde groep van BindPoints; gemaakt via clip.createAnimationNode(name), benaderd via clip.animations
• BindPoint: bindt een AnimationNode aan een specifieke eigenschap op een scène‑object; exposeert property en channelsCount
• AnimationChannel: breidt uit KeyframeSequence; houdt een aparte keyframeSequence; benaderd via bindPoint.getChannel(name)
• KeyFrame: een enkel tijd/waarde‑paar; draagt per‑keyframe interpolation: Interpolation
• KeyframeSequence: geordende lijst van KeyFrame objecten via keyFrames; heeft preBehavior en postBehavior (Extrapolation)
• Interpolation: enum: LINEAR, CONSTANT, BEZIER, B_SPLINE, CARDINAL_SPLINE, TCB_SPLINE
• Extrapolation: klasse met type: ExtrapolationType en repeatCount: number
• ExtrapolationType: enum: CONSTANT, GRADIENT, CYCLE, CYCLE_RELATIVE, OSCILLATE

Animatiedata lezen uit een geladen scène:

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

Stream‑ en Buffer‑ondersteuning

Gebruik scene.openFromBuffer() om een 3D-scène direct vanuit het geheugen te laden Buffer. Dit is het aanbevolen patroon voor serverless-functies, streaming‑pijplijnen en het verwerken van assets die via HTTP worden opgehaald zonder naar schijf te schrijven.

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

Formaat‑autodetectie op basis van binaire magic‑nummers geldt bij het laden vanuit een buffer, zodat GLB-, STL‑binary‑ en 3MF‑bestanden worden herkend zonder een formaatparameter op te geven.

Voorbeelden van gebruik

Voorbeeld 1: OBJ laden en exporteren naar GLB

Dit voorbeeld laadt een Wavefront OBJ‑bestand met materialen en exporteert de scène vervolgens opnieuw als een binair glTF‑bestand (GLB) dat geschikt is voor web‑ en game‑engine‑gebruik.

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

Voorbeeld 2: Round‑Trip STL met normaalvalidatie

Dit voorbeeld laadt een binair STL‑bestand, drukt per‑vertex normaal‑informatie af, en exporteert de scène vervolgens opnieuw als ASCII STL en verifieert de round‑trip.

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

Voorbeeld 3: Een scène programmatisch bouwen en opslaan als glTF

Dit voorbeeld bouwt een scène met een PBR-materiaal vanaf nul en slaat deze op als een JSON glTF‑bestand.

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 en best practices

• Gebruik ObjLoadOptions.enableMaterials = true wanneer je materiaalgegevens nodig hebt uit .mtl‑bestanden. Zonder dit zal de materiaallijst op elk knooppunt leeg zijn.
• Voorkeur binaryMode = true voor GLB bij het produceren van assets voor web- of game-engines. Binaire GLB is één enkel zelfvoorzienend bestand en laadt sneller in browsers en engines dan de JSON + .bin-splitsing.
• Gebruik openFromBuffer() in serverloze omgevingen om tijdelijke bestands‑I/O te vermijden. Haal de asset op, geef de Buffer direct door, en schrijf de output naar een stream of een andere buffer.
• Controleer node.entity voordat je cast: niet alle knooppunten dragen een entiteit. Bescherm altijd met een instanceof controle voordat je toegang krijgt tot Mesh-specifieke eigenschappen zoals controlPoints.
• Stel normalizeNormal = true in ObjLoadOptions wanneer je bron‑OBJ‑bestanden afkomstig zijn van onbetrouwbare bronnen. Dit voorkomt dat defecte normalen zich verspreiden naar downstream rendering‑ of validatiestappen.
• Bewaar strict: true in tsconfig.json: de bibliotheek is geschreven met noImplicitAny en strictNullChecks. Uitschakelen strict maskeert echte typefouten en ondermijnt de waarde van de getypeerde API.
• Doorlopen via childNodes, niet een indexlus: de childNodes eigenschap retourneert een iterabele; vermijd afhankelijkheid van numerieke indexering voor toekomstige compatibiliteit.

Veelvoorkomende problemen

Veelgestelde vragen

Vereist de bibliotheek native add-ons of systeempakketten? Nee. Aspose.3D FOSS voor TypeScript heeft één runtime‑afhankelijkheid: xmldom, die pure JavaScript is en automatisch wordt geïnstalleerd door npm. Er zijn geen .node native add-ons en geen systeempakketten om te installeren.

Welke Node.js‑versies worden ondersteund? Node.js 18, 20, en 22 LTS. De bibliotheek richt zich op CommonJS-output en gebruikt intern ES2020-taalfuncties.

Kan ik de bibliotheek gebruiken in een browserbundle (webpack/esbuild)? De bibliotheek richt zich op Node.js en gebruikt de Node.js fs en Buffer API’s. Browserbundeling wordt niet officieel ondersteund. Voor gebruik in de browser, laad de scène server‑side en zend het resultaat (bijv. als GLB) naar de client.

Wat is het verschil tussen GltfSaveOptions.binaryMode = true en false? binaryMode = false produceert een .gltf JSON‑bestand plus een aparte .bin binaire buffer‑sidecar. binaryMode = true produceert een enkel zelfvoorzienend .glb bestand. Gebruik true voor productie‑assetlevering.

Kan ik een bestand laden uit een HTTP‑respons zonder het op schijf op te slaan? Ja. Haal de respons op als een Buffer (bijv. met node-fetch of de ingebouwde fetch in Node 18+), roep dan scene.openFromBuffer(buffer, options).

Is FBX‑ondersteuning volledig? Nee. FBX‑import‑ en exportklassen bestaan in de bibliotheek, maar FBX is niet geïntegreerd in Scene.open() of Scene.save() automatische detectie. Aanroepen scene.open('file.fbx') zal de FBX-importeur niet aanroepen; het bestand wordt verwerkt via het STL-reservepad. Gebruik de FBX-specifieke importeur/exporteurklassen rechtstreeks als je FBX I/O nodig hebt. Zie de bovenstaande tabel met formatondersteuning die FBX aangeeft als No*.

Ondersteunt de bibliotheek TypeScript 4.x? TypeScript 5.0+ wordt aanbevolen. TypeScript 4.7+ zou in de praktijk moeten werken, maar de bibliotheek is getest en geschreven tegen 5.0+.

API-referentieoverzicht