Funkcie a vlastnosti

Aspose.3D FOSS pre TypeScript je knižnica Node.js licencovaná pod MIT, určená na načítanie, konštruovanie a exportovanie 3D scén. Dodáva sa s kompletnými definíciami typov TypeScript, jednou runtime závislosťou (xmldom), a podporou šiestich hlavných 3D formátov súborov. Táto stránka je hlavnou referenciou pre všetky oblasti funkcií a obsahuje spustiteľné príklady kódu TypeScript pre každú z nich.

Inštalácia a nastavenie

Nainštalujte balík z npm pomocou jedného príkazu:

npm install @aspose/3d

Balík ciele na CommonJS a vyžaduje Node.js 18 alebo novší. Po inštalácii overte, že váš tsconfig.json obsahuje nasledujúce možnosti kompilátora pre úplnú kompatibilitu:

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

Importujte hlavný Scene triedu z koreňa balíka. Triedy možností špecifické pre formát sa importujú z ich príslušných podcest:

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

Funkcie a vlastnosti

Podpora formátov

Aspose.3D FOSS pre TypeScript číta a zapisuje šesť hlavných 3D formátov súborov. Detekcia formátu je automatická na základe binárnych magických čísel pri načítaní, takže nie je potrebné explicitne uvádzať zdrojový formát.

Načítanie OBJ s materiálmi:

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

Ukladanie do GLB (binárny 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);

Scénový graf

Všetok 3D obsah je usporiadaný ako strom Node objektov s koreňom v scene.rootNode. Každý uzol môže niesť Entity (jeden Mesh, Camera, Light, alebo iný SceneObject) a Transform ktorý ho umiestňuje relatívne k jeho rodičovi.

Kľúčové triedy grafu scény:

• Scene: kontajner najvyššej úrovne; obsahuje rootNode a animationClips
• Node: pomenovaný uzol stromu s childNodes, entity, transform, a materials
• Entity: základná trieda pre pripojiteľné objekty (Mesh, Camera, Light)
• SceneObject: základná trieda zdieľaná s Node a Entity
• A3DObject: koreňová základná trieda s name a kontajnerom vlastností
• Transform: lokálny posun, rotácia (Eulerova a kvaternionová) a mierka

Prechádzanie grafu scény:

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

Vytváranie hierarchie scény programovo:

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

Geometria a Mesh

Mesh je primárny typ geometrie. Rozširuje Geometry a poskytuje kontrolné body (vrcholy), indexy polygonov a prvky vrcholov pre normály, UV a farby vrcholov.

Kľúčové triedy geometrie:

• Mesh: polygonová sieť s controlPoints a polygonCount
• Geometry: základná trieda s riadením prvkov vrcholov
• VertexElementNormal: normály per-vertex alebo per-polygon-vertex
• VertexElementUV: textúrové súradnice (jeden alebo viac UV kanálov)
• VertexElementVertexColor: farbové dáta per-vertex
• MappingMode: riadi, ako sa dáta elementov mapujú na polygóny (CONTROL_POINT, POLYGON_VERTEX, POLYGON, EDGE, ALL_SAME)
• ReferenceMode: riadi stratégiu indexovania (DIRECT, INDEX, INDEX_TO_DIRECT)
• VertexElementType: identifikuje semantiku vrcholového elementu
• TextureMapping: enumerácia textúrových kanálov

Čítanie dát siete z načítanej scény:

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

Systém materiálov

Aspose.3D FOSS pre TypeScript podporuje tri typy materiálov, ktoré pokrývajú celý rozsah od starého Phong osvetlenia po fyzikálne založené renderovanie:

• LambertMaterial: difúzna farba a ambientná farba; mapuje sa na jednoduché materiály OBJ/DAE
• PhongMaterial: pridáva spekulárnu farbu, lesk a emisivitu; predvolený typ materiálu OBJ
• PbrMaterial: fyzikálne založený model drsnosti/kovovosti; používaný pre import a export glTF 2.0

Čítanie materiálov z načítanej OBJ scény:

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

Aplikovanie PBR materiálu pri zostavovaní glTF scény:

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

Matematické nástroje

Knižnica je dodávaná s kompletnou sadou 3D matematických typov, všetky plne typované:

• Vector3: 3-komponentový vektor; podporuje minus(), times(), dot(), cross(), normalize(), length, angleBetween()
• Vector4: 4-komponentový vektor pre homogénne súradnice
• Matrix4: 4×4 transformačná matica s concatenate(), transpose, decompose, setTRS
• Quaternion: rotačný kvaternion s fromEulerAngle() (statický, jedinečný), eulerAngles() (metóda inštancie), slerp(), normalize()
• BoundingBox: osovo zarovnaný ohraničujúci box s minimum, maximum, center, size, merge
• FVector3: variant s jednoduchou presnosťou pre Vector3 : používaný v dátach vrcholových elementov

Výpočet ohraničujúcej krabice z vrcholov siete:

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

Zostavenie transformácie z Eulerových uhlov:

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

Systém animácií

API animácií modeluje klipy, uzly, kanály a sekvencie kľúčových snímok:

• AnimationClip: pomenovaná kolekcia animačných uzlov; prístupná cez scene.animationClips; zverejňuje animations: AnimationNode[]
• AnimationNode: pomenovaná skupina BindPoints; vytvorené pomocou clip.createAnimationNode(name), prístupné cez clip.animations
• BindPoint: viaže AnimationNode na konkrétnu vlastnosť objektu scény; zverejňuje property a channelsCount
• AnimationChannel:rozširuje KeyframeSequence; obsahuje samostatný keyframeSequence; prístupné cez bindPoint.getChannel(name)
• KeyFrame: jeden čas/hodnota pár; nesie per-keyframe interpolation: Interpolation
• KeyframeSequence: usporiadaný zoznam KeyFrame objektov cez keyFrames; má preBehavior a postBehavior (Extrapolation)
• Interpolation: enum: LINEAR, CONSTANT, BEZIER, B_SPLINE, CARDINAL_SPLINE, TCB_SPLINE
• Extrapolation: trieda s type: ExtrapolationType a repeatCount: number
• ExtrapolationType: enum: CONSTANT, GRADIENT, CYCLE, CYCLE_RELATIVE, OSCILLATE

Čítanie animačných dát z načítanej scény:

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

Podpora streamov a bufferov

Použiť scene.openFromBuffer() na načítanie 3D scény priamo z pamäti Buffer. Toto je odporúčaný vzor pre serverless funkcie, streamingové pipeline a spracovanie aktív načítaných cez HTTP bez zápisu na 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);
  }
}

Automatická detekcia formátu z binárnych magických čísel sa uplatňuje pri načítaní z bufferu, takže súbory GLB, binárny STL a 3MF sú rozpoznané bez nutnosti zadávať parameter formátu.

Príklady použitia

Príklad 1: Načítanie OBJ a export do GLB

Tento príklad načíta súbor Wavefront OBJ s materiálmi a následne exportuje scénu ako binárny glTF (GLB) súbor vhodný pre web a herné enginy.

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

Príklad 2: Otočný cyklus STL s overením normál

Tento príklad načíta binárny STL súbor, vypíše informácie o normálach pre každý vrchol, potom exportuje scénu ako ASCII STL a overí správnosť cyklu.

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

Príklad 3: Vytvoriť scénu programovo a uložiť ako glTF

Tento príklad vytvára scénu s PBR materiálom od začiatku a ukladá ju ako JSON glTF súbor.

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

Tipy a osvedčené postupy

• Použite ObjLoadOptions.enableMaterials = true vždy, keď potrebujete materiálové dáta z .mtl súborov. Bez toho bude zoznam materiálov na každom uzle prázdny.
• Preferovať binaryMode = true pre GLB pri vytváraní aktív pre web alebo herné enginy. Binárny GLB je jeden samostatný súbor a načítava sa rýchlejšie v prehliadačoch a engineoch než rozdelenie JSON + .bin.
• Použiť openFromBuffer() v serverless prostrediach aby ste sa vyhli dočasnému I/O súborov. Načítajte asset, odovzdajte Buffer priamo, a zapíšte výstup do streamu alebo iného bufferu.
• Skontrolovať node.entity pred pretypovaním: nie všetky uzly nesú entitu. Vždy chráňte pomocou instanceof kontroly pred prístupom k Mesh-špecifických vlastností, ako napríklad controlPoints.
• Nastaviť normalizeNormal = true v ObjLoadOptions keď vaše zdrojové OBJ súbory pochádzajú z nedôveryhodných zdrojov. Toto zabraňuje šíreniu degenerovaných normál do následných renderovacích alebo validačných krokov.
• Udržiavať strict: true v tsconfig.json: knižnica je vytvorená pomocou noImplicitAny a strictNullChecks. Zakázanie strict maskuje skutočné typové chyby a podkopáva hodnotu typovaného API.
• Prechádzať pomocou childNodes, nie indexová slučka: childNodes vlastnosť vracia iterovateľný objekt; vyhnite sa spoliehaniu na číselné indexovanie pre budúcu kompatibilitu.

Bežné problémy

Často kladené otázky

Vyžaduje knižnica nejaké natívne doplnky alebo systémové balíky? Nie. Aspose.3D FOSS pre TypeScript má jedinú runtime závislosť: xmldom, čo je čistý JavaScript a je automaticky nainštalovaný cez npm. Nie sú žiadne .node natívne doplnky ani systémové balíky na inštaláciu.

Ktoré verzie Node.js sú podporované? Node.js 18, 20 a 22 LTS. Knižnica ciele na výstup CommonJS a interné používa jazykové funkcie ES2020.

Môžem použiť knižnicu v prehliadačovom balíku (webpack/esbuild)? Knižnica ciele na Node.js a používa Node.js fs a Buffer API. Zlučovanie pre prehliadač nie je oficiálne podporované. Pre použitie v prehliadači načítajte scénu na serveri a odovzdajte výsledok (napr. ako GLB) klientovi.

Aký je rozdiel medzi GltfSaveOptions.binaryMode = true a false? binaryMode = false vytvára .gltf súbor JSON plus samostatný .bin binárny buffer sidecar. binaryMode = true vytvára jeden samostatný .glb súbor. Použite true pre doručovanie produkčných aktív.

Môžem načítať súbor z HTTP odpovede bez uloženia na disk? Áno. Načítajte odpoveď ako Buffer (napríklad pomocou node-fetch alebo vstavaný fetch v Node 18+), potom zavolajte scene.openFromBuffer(buffer, options).

Je podpora FBX kompletná? Nie. Triedy importéra a exportéra FBX existujú v knižnici, ale FBX nie je prepojený do Scene.open() alebo Scene.save() automatické rozpoznávanie. Volanie scene.open('file.fbx') nevyvolá importér FBX; súbor bude spracovaný záložnou cestou STL. Ak potrebujete I/O pre FBX, použite priamo špecifické triedy importéra/exportéra pre FBX. Pozrite si vyššie uvedenú tabuľku podpory formátov, ktorá označuje FBX ako No*.

Podporuje knižnica TypeScript 4.x? Odporúča sa TypeScript 5.0+. TypeScript 4.7+ by mal v praxi fungovať, ale knižnica je testovaná a vyvíjaná proti 5.0+.

Zhrnutie referencie API