Funktioner och funktionaliteter

Aspose.3D FOSS för TypeScript är ett MIT-licensierat Node.js‑bibliotek för att ladda, konstruera och exportera 3D‑scener. Det levereras med kompletta TypeScript‑typdefinitioner, ett enda körtidberoende (xmldom),.

Installation och konfiguration

Installera paketet från npm med ett enda kommando:

npm install @aspose/3d

Paketet riktar sig mot CommonJS och kräver Node.js 18 eller senare. Efter installation, verifiera din tsconfig.json inkluderar följande kompilatoralternativ för full kompatibilitet:

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

Importera huvud Scene klass från paketets rot. Format‑specifika alternativklasser importeras från deras respektive under‑sökvägar:

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

Funktioner och funktionaliteter

Formatstöd

Aspose.3D FOSS for TypeScript läser och skriver sex stora 3D‑filformat. Formatdetektering sker automatiskt från binära magiska tal vid inläsning, så du behöver inte ange källformatet explicit.

Laddar OBJ med material:

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

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

Scengraf

Allt 3D-innehåll är organiserat som ett träd av Node objekt med rot i scene.rootNode. Varje nod kan bära en Entity (en Mesh, Camera, Light, eller annan SceneObject) och en Transform som placerar den relativt till dess förälder.

Viktiga scen‑grafklasser:

• Scene: den översta behållaren; innehåller rootNode och animationClips
• Node: en namngiven trädnod med childNodes, entity, transform, och materials
• Entity: basklass för fästande objekt (Mesh, Camera, Light)
• SceneObject: basklass som delas av Node och Entity
• A3DObject: rotbasklass med name och egenskapsbehållare
• Transform: lokal translation, rotation (Euler och Quaternion) och skala

Traversera scen‑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);

Skapa en scenhierarki programatiskt:

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 och Mesh

Mesh är den primära geometritypen. Den utökar Geometry och exponerar kontrollpunkter (vertexar), polygonindex och vertexelement för normaler, UV:er och vertexfärger.

Viktiga geometri-klasser:

• Mesh: polygonnät med controlPoints och polygonCount
• Geometry: basklass med vertex-elementhantering
• VertexElementNormal: per-vertex eller per-polygon-vertex normaler
• VertexElementUV: texturkoordinater (en eller flera UV-kanaler)
• VertexElementVertexColor: per-vertex färgdata
• MappingMode: styr hur elementdata mappas till polygoner (CONTROL_POINT, POLYGON_VERTEX, POLYGON, EDGE, ALL_SAME)
• ReferenceMode: styr indexeringsstrategi (DIRECT, INDEX, INDEX_TO_DIRECT)
• VertexElementType: identifierar semantiken för ett vertex-element
• TextureMapping: uppräkning av texturkanaler

Läsa mesh-data från en laddad scen:

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 för TypeScript stöder tre materialtyper som täcker hela spektrumet från äldre Phong-belysning till fysiskt baserad rendering:

• LambertMaterial: diffus färg och omgivningsfärg; mappar till enkla OBJ/DAE-material
• PhongMaterial: lägger till spekulär färg, glans och emissiv; standard OBJ-materialtyp
• PbrMaterial: fysikbaserad roughness/metallic-modell; används för glTF 2.0-import och -export

Läser material från en inläst OBJ-scen:

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

Applicerar ett PBR-material när en glTF-scen byggs:

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

Matematikverktyg

Biblioteket levereras med en komplett uppsättning 3D-mathematiktyper, alla fullt typade:

• Vector3: 3-komponentsvektor; stöder minus(), times(), dot(), cross(), normalize(), length, angleBetween()
• Vector4: 4-komponentsvektor för homogena koordinater
• Matrix4: 4×4 transformationsmatris med concatenate(), transpose, decompose, setTRS
• Quaternion: rotationskvaternion med fromEulerAngle() (statisk, singular), eulerAngles() (instansmetod), slerp(), normalize()
• BoundingBox: axeljusterad begränsningsbox med minimum, maximum, center, size, merge
• FVector3: single-precision-variant av Vector3 : används i vertex-elementdata

Beräknar en begränsningslåda från mesh-vertexar:

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 transformation från Euler-vinklar:

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:et modellerar klipp, noder, kanaler och nyckelramsekvenser:

• AnimationClip: namngiven samling av animationsnoder; nås via scene.animationClips; exponerar animations: AnimationNode[]
• AnimationNode: namngiven grupp av BindPoints; skapad via clip.createAnimationNode(name), åtkomst via clip.animations
• BindPoint: binder en AnimationNode : till en specifik egenskap på ett scenobjekt; exponerar property : och channelsCount
• AnimationChannel: ärver KeyframeSequence;: ; håller en separat keyframeSequence;: ; nås via bindPoint.getChannel(name)
• KeyFrame: : ett enskilt tids-/värdepar; bär per-nyckelbild interpolation: Interpolation
• KeyframeSequence: : ordnad lista över KeyFrame : objekt via keyFrames;: ; har preBehavior : och postBehavior (Extrapolation)
• Interpolation: : enum: LINEAR, CONSTANT, BEZIER, B_SPLINE, CARDINAL_SPLINE, TCB_SPLINE
• Extrapolation: klass med type: ExtrapolationType : och repeatCount: number
• ExtrapolationType: : enum: CONSTANT, GRADIENT, CYCLE, CYCLE_RELATIVE, OSCILLATE

Läser animationsdata från en inläst scen:

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- och bufferstöd

: Använd scene.openFromBuffer() för att ladda en 3D-scen direkt från minnet Buffer. Detta är det rekommenderade mönstret för serverlösa funktioner, strömmande pipelines och bearbetning av resurser som hämtas via HTTP utan att skriva till 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 formatdetektering från binära magiska tal gäller vid inläsning från buffer, så att GLB-, STL‑binär‑ och 3MF‑filer identifieras utan att ange en formatparameter.

Exempel på användning

Exempel 1: Läs in OBJ och exportera till GLB

Detta exempel läser in en Wavefront OBJ‑fil med material, och exporterar sedan scenen som en binär glTF‑fil (GLB) som är lämplig för webb‑ och spelmotoranvändning.

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

Exempel 2: Rundresa STL med normalvalidering

Detta exempel läser in en binär STL‑fil, skriver ut normalinformation per vertex, och exporterar sedan scenen som ASCII‑STL och verifierar rundresan.

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

Exempel 3: Bygg en scen programatiskt och spara som glTF

Detta exempel konstruerar en scen med ett PBR-material från grunden och sparar 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 och bästa praxis

• Använd ObjLoadOptions.enableMaterials = true när du behöver materialdata från .mtl-filer. Utan den kommer materiallistan på varje nod att vara tom.
• Föredra binaryMode = true för GLB när du producerar tillgångar för webb- eller spelmotorer. Binär GLB är en enda självständig fil och laddas snabbare i webbläsare och motorer än JSON + .bin-spliten.
• Använd openFromBuffer() i serverlösa miljöer för att undvika temporär fil‑I/O. Hämta tillgången, skicka Buffer direkt, och skriv utdata till en ström eller en annan buffert.
• Kontrollera node.entity innan du kastar: inte alla noder bär en entitet. Skydda alltid med en instanceof kontroll innan du får åtkomst till Mesh-specifika egenskaper såsom controlPoints.
• Ställ in normalizeNormal = true i ObjLoadOptions när dina käll-OBJ-filer kommer från opålitliga källor. Detta förhindrar att degenererade normaler sprids till efterföljande renderings- eller valideringssteg.
• Behåll strict: true i tsconfig.json: biblioteket är skrivet med noImplicitAny och strictNullChecks. Inaktivera strict maskerar faktiska typfel och undergräver värdet av det typade API:et.
• Traversera via childNodes, inte en indexloop: den childNodes egenskapen returnerar en iterabel; undvik att förlita dig på numerisk indexering för framtida kompatibilitet.

Vanliga problem

Vanliga frågor

Kräver biblioteket några inbyggda tillägg eller systempaket? Nej. Aspose.3D FOSS för TypeScript har ett enda körtidberoende: xmldom, som är ren JavaScript och installeras automatiskt av npm. Det finns inga .node inbyggda tillägg och inga systempaket att installera.

Vilka Node.js‑versioner stöds? Node.js 18, 20 och 22 LTS. Biblioteket riktar sig mot CommonJS-utdata och använder ES2020-språkfunktioner internt.

Kan jag använda biblioteket i ett webbläsarpaket (webpack/esbuild)? Biblioteket riktar sig mot Node.js och använder Node.js fs och Buffer API:er. Browser‑paketering stöds inte officiellt. För användning i webbläsare, ladda scenen på servern och överför resultatet (t.ex. som GLB) till klienten.

Vad är skillnaden mellan GltfSaveOptions.binaryMode = true och false? binaryMode = false producerar en .gltf JSON‑fil plus en separat .bin binär buffer‑sidecar. binaryMode = true producerar en enda självständig .glb fil. Använd true för leverans av produktionsresurser.

Kan jag läsa in en fil från ett HTTP‑svar utan att spara den på disk? Ja. Hämta svaret som en Buffer (t.ex. med node-fetch eller den inbyggda fetch i Node 18+), och sedan anropa scene.openFromBuffer(buffer, options).

Är FBX‑stöd komplett? Nej. FBX‑importör- och exportörklasser finns i biblioteket, men FBX är inte integrerat i Scene.open() eller Scene.save() automatisk identifiering. Anropar scene.open('file.fbx') kommer inte att anropa FBX-importören; filen kommer att hanteras av STL-fallback‑vägen. Använd de FBX-specifika import-/exportklasserna direkt om du behöver FBX I/O. Se formatstödtabellen ovan som markerar FBX som No*.

Stöder biblioteket TypeScript 4.x? TypeScript 5.0+ rekommenderas. TypeScript 4.7+ bör fungera i praktiken, men biblioteket är testat och utvecklat mot 5.0+.

API-referenssammanfattning