Funkcionalnosti i mogućnosti

Aspose.3D FOSS za TypeScript je MIT-licencirana Node.js biblioteka za učitavanje, konstruisanje i izvoz 3D scena. Dostavlja se sa kompletnim TypeScript definicijama tipova, jednim runtime zavisnošću (xmldom).

Instalacija i podešavanje

Instalirajte paket sa npm koristeći jednu komandu:

npm install @aspose/3d

Paket cilja CommonJS i zahteva Node.js 18 ili noviji. Nakon instalacije, proverite vaš tsconfig.json sadrži sledeće opcije kompajlera za potpunu kompatibilnost:

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

Uvezite glavni Scene klasu iz korena paketa. Klase opcija specifične za format se uvoze iz njihovih odgovarajućih podputanja:

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

Funkcionalnosti i mogućnosti

Podrška za formate

Aspose.3D FOSS za TypeScript čita i piše šest glavnih 3D formata fajlova. Detekcija formata je automatska na osnovu binarnih magičnih brojeva prilikom učitavanja, tako da nije potrebno eksplicitno navoditi izvorni format.

Učitavanje OBJ-a sa materijalima:

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

Čuvanje u GLB (binarni 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);

Graf scene

Sav 3D sadržaj je organizovan kao stablo od Node objekata ukorenjenih u scene.rootNode. Svaki čvor može nositi Entity (a Mesh, Camera, Light, ili drugi SceneObject) i a Transform koji ga pozicionira relativno u odnosu na njegovog roditelja.

Ključne klase scene‑grafika:

• Scene: kontejner najvišeg nivoa; sadrži rootNode i animationClips
• Node: imenovani čvor stabla sa childNodes, entity, transform, i materials
• Entity: osnovna klasa za objekte koji se mogu prikačiti (Mesh, Camera, Light)
• SceneObject: osnovna klasa koju dele Node i Entity
• A3DObject: korenska osnovna klasa sa name i property bag
• Transform: lokalni pomeraj, rotacija (Euler i Quaternion), i skala

Prolazak kroz grafiku scene:

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

Kreiranje hijerarhije scene programatski:

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

Geometrija i Mesh

Mesh je primarni tip geometrije. Proširuje Geometry i izlaže kontrolne tačke (vrhove), indekse poligona, i elemente vrhova za normale, UV‑ove, i boje vrhova.

Ključne klase geometrije:

• Mesh:poligonalna mreža sa controlPoints i polygonCount
• Geometry: osnovna klasa sa upravljanjem elementima vrhova
• VertexElementNormal: normale po vrhu ili po vrhu-poligona
• VertexElementUV: teksturne koordinate (jedan ili više UV kanala)
• VertexElementVertexColor: podaci o boji po vrhu
• MappingMode: kontroliše kako se podaci elementa mapiraju na poligone (CONTROL_POINT, POLYGON_VERTEX, POLYGON, EDGE, ALL_SAME)
• ReferenceMode: kontroliše strategiju indeksiranja (DIRECT, INDEX, INDEX_TO_DIRECT)
• VertexElementType: identifikuje semantiku elementa vrha
• TextureMapping: enumeracija teksturnih kanala

Čitanje podataka mreže iz učitane 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}`);
    }
  }
}

Sistem materijala

Aspose.3D FOSS za TypeScript podržava tri tipa materijala koji pokrivaju čitav spektar od nasleđenog Phong osvetljenja do fizički zasnovanog renderovanja:

• LambertMaterial: difuzna boja i ambijentalna boja; mapira se na jednostavne OBJ/DAE materijale
• PhongMaterial: dodaje specular color, shininess i emissive; podrazumevani OBJ tip materijala
• PbrMaterial: fizički zasnovani model hrapavosti/metalnosti; koristi se za glTF 2.0 uvoz i izvoz

Čitanje materijala iz učitane 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)}`);
    }
  }
}

Primena PBR materijala prilikom izgradnje 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);

Matematički alati

Biblioteka dolazi sa kompletnim skupom 3D matematičkih tipova, svi potpuno tipizovani:

• Vector3: vektor sa 3 komponente; podržava minus(), times(), dot(), cross(), normalize(), length, angleBetween()
• Vector4: vektor sa 4 komponente za homogene koordinate
• Matrix4: matrica transformacije 4×4 sa concatenate(), transpose, decompose, setTRS
• Quaternion: kvaternion rotacije sa fromEulerAngle() (static, singular), eulerAngles() (instance method), slerp(), normalize()
• BoundingBox: axis-aligned bounding box са minimum, maximum, center, size, merge
• FVector3: варијанта једноструке прецизности од Vector3 користи се у подацима елементa врха

Izračunavanje okvira (bounding box) iz vrhova mreže:

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

Izgradnja transformacije iz Eulerovih uglova:

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

Sistem animacije

API za animaciju modeluje klipove, čvorove, kanale i sekvence ključnih frejmova:

• AnimationClip: именована колекција анимационих чворова; приступа се преко scene.animationClips; излаже animations: AnimationNode[]
• AnimationNode: именована група BindPoints; креирано преко clip.createAnimationNode(name), приступа се преко clip.animations
• BindPoint: povezuje jedan AnimationNode : na određeno svojstvo na objektu scene; izlaže property i channelsCount
• AnimationChannel: proširuje KeyframeSequence; drži zaseban keyframeSequence; pristupa se putem bindPoint.getChannel(name)
• KeyFrame: jedan par vreme/vrednost; nosi po‑ključni okvir interpolation: Interpolation
• KeyframeSequence: uređen spisak od KeyFrame objekti putem keyFrames; ima preBehavior i postBehavior (Extrapolation)
• Interpolation: enum: LINEAR, CONSTANT, BEZIER, B_SPLINE, CARDINAL_SPLINE, TCB_SPLINE
• Extrapolation: class sa type: ExtrapolationType i repeatCount: number
• ExtrapolationType: enum: CONSTANT, GRADIENT, CYCLE, CYCLE_RELATIVE, OSCILLATE

Čitanje podataka animacije iz učitane 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}`);
    }
  }
}

Podrška za tokove i bafer

Koristi scene.openFromBuffer() za učitavanje 3D scene direktno iz in-memory Buffer. Ovo je preporučeni obrazac za serverless funkcije, streaming pipeline‑ove i obradu sredstava preuzetih preko HTTP‑a bez upisivanja 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);
  }
}

Automatsko otkrivanje formata na osnovu binarnih magičnih brojeva primenjuje se prilikom učitavanja iz bafera, tako da se GLB, STL binarni i 3MF fajlovi prepoznaju bez navođenja parametra formata.

Primeri upotrebe

Primer 1: Učitaj OBJ i izvezi u GLB

Ovaj primer učitava Wavefront OBJ fajl sa materijalima, a zatim ponovo izveze scenu kao binarni glTF (GLB) fajl pogodan za upotrebu na vebu i u game engine‑ovima.

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

Primer 2: Povratni STL sa validacijom normala

Ovaj primer učitava binarni STL fajl, ispisuje informacije o normalama po vrhu, a zatim ponovo izveze scenu kao ASCII STL i proverava povratni proces.

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

Primer 3: Izgradnja scene programatski i čuvanje kao glTF

Ovaj primer konstruše scenu sa PBR materijalom od nule i čuva je kao JSON glTF fajl.

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

Saveti i najbolje prakse

• Koristite ObjLoadOptions.enableMaterials = true kad god vam podaci o materijalu iz .mtl fajlova budu potrebni. Bez toga, lista materijala na svakom čvoru će biti prazna.
• Preferirajte binaryMode = true za GLB pri proizvodnji sredstava za web ili game engine‑e. Binarni GLB je jedan samostalni fajl i učitava se brže u pregledačima i engine‑ima nego JSON + .bin razdvajanje.
• Koristite openFromBuffer() u serverless okruženjima da bi se izbeglo privremeno I/O fajlova. Preuzmite resurs, prosledite Buffer direktno i upišite izlaz u stream ili drugi bafer.
• Proveri node.entity pre kastovanja: ne svi čvorovi nose entitet. Uvek zaštitite sa instanceof proverom pre pristupa Mesh-specifična svojstva kao što su controlPoints.
• Postavi normalizeNormal = true u ObjLoadOptions kada vaši izvorni OBJ fajlovi dolaze iz nepouzdanih izvora. Ovo sprečava da degenerisane normale propagiraju u naredne korake renderovanja ili validacije.
• Zadrži strict: true u tsconfig.json: biblioteka je napisana uz noImplicitAny i strictNullChecks. Onemogućavanje strict maskira stvarne tipove grešaka i poništava vrednost tipizovanog API-ja.
• Prođite putem childNodes, a ne petlja po indeksima: childNodes svojstvo vraća iterabilni objekat; izbegavajte oslanjanje na numeričko indeksiranje radi unapred kompatibilnosti.

Uobičajeni problemi

Često postavljana pitanja

Da li biblioteka zahteva neke native dodatke ili sistemske pakete? Br. Aspose.3D FOSS za TypeScript ima jednu runtime zavisnost: xmldom, koji je čisti JavaScript i automatski se instalira putem npm-a. Nema .node nativnih dodataka i nema sistemskih paketa za instalaciju.

Koje verzije Node.js su podržane? Node.js 18, 20 i 22 LTS. Biblioteka cilja CommonJS izlaz i interno koristi ES2020 jezičke karakteristike.

Mogu li koristiti biblioteku u browser paketu (webpack/esbuild)? Biblioteka cilja Node.js i koristi Node.js fs i Buffer API‑ji. Pakovanje za pregledač nije zvanično podržano. Za upotrebu u pregledaču učitajte scenu na serveru i pošaljite rezultat (npr. kao GLB) klijentu.

Koja je razlika između GltfSaveOptions.binaryMode = true i false? binaryMode = false generiše .gltf JSON fajl plus zaseban .bin binarni bafer sidecar. binaryMode = true generiše jedan samostalni .glb fajl. Koristite true za isporuku proizvodnih sredstava.

Mogu li učitati datoteku iz HTTP odgovora bez čuvanja na disku? Da. Preuzmite odgovor kao a Buffer (npr., koristeći node-fetch ili ugrađeni fetch u Node 18+), zatim pozovite scene.openFromBuffer(buffer, options).

Da li je podrška za FBX potpuna? Ne. Klase za uvoz i izvoz FBX‑a postoje u biblioteci, ali FBX nije povezan u Scene.open() ili Scene.save() automatsko otkrivanje. Pozivanje scene.open('file.fbx') neće pozvati FBX uvoznik; fajl će biti obrađen putem STL rezervnog puta. Koristite FBX‑specifične klase uvoznika/izvoznika direktno ako vam je potreban FBX I/O. Pogledajte tabelu podrške formata iznad koja označava FBX kao No*.

Da li biblioteka podržava TypeScript 4.x? Preporučuje se TypeScript 5.0+. TypeScript 4.7+ bi trebao raditi u praksi, ali je biblioteka testirana i razvijana prema 5.0+.

Sažetak API reference