Značajke i funkcionalnosti

Aspose.3D FOSS za TypeScript je MIT-licencirana Node.js biblioteka za učitavanje, konstruiranje i izvoz 3D scena. Dolazi s potpunim TypeScript definicijama tipova, jednim runtime ovisnošću (xmldom), i podrškom za šest glavnih 3D formata datoteka. Ova stranica je primarni referentni vodič za sve funkcionalne oblasti i uključuje izvršne TypeScript primjere koda za svaku od njih.

Instalacija i postavljanje

Instalirajte paket iz npm-a koristeći jednu naredbu:

npm install @aspose/3d

Paket cilja CommonJS i zahtijeva Node.js 18 ili noviji. Nakon instalacije, provjerite svoj tsconfig.json uključuje sljedeće opcije kompajlera za potpunu kompatibilnost:

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

Uvezite glavni Scene razred iz korijena paketa. Razredi opcija specifični za format uvoze se 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';

Značajke i funkcionalnosti

Podrška za formate

Aspose.3D FOSS za TypeScript čita i zapisuje šest glavnih 3D formata datoteka. Detekcija formata je automatska na temelju binarnih magičnih brojeva prilikom učitavanja, pa nije potrebno izričito navoditi izvorni format.

Učitavanje OBJ-a s 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);

Spremanje 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 organiziran je kao stablo Node objekata s korijenom u scene.rootNode. Svaki čvor može nositi Entity (neka Mesh, Camera, Light, ili druge SceneObject) i Transform koji ga pozicionira relativno na njegovog roditelja.

Ključne klase grafova scene:

• Scene: kontejner najviše razine; sadrži rootNode i animationClips
• Node: imenovani čvor stabla s childNodes, entity, transform, i materials
• Entity: osnovna klasa za pričvrstive objekte (Mesh, Camera, Light)
• SceneObject: osnovna klasa koju dijele Node i Entity
• A3DObject: korijenska osnovna klasa s name i spremnik svojstava
• Transform: lokalni pomak, rotacija (Euler i Kvaternion) i skaliranje

Prolazak kroz graf 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);

Stvaranje 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 primarna vrsta geometrije. Proširuje Geometry i izlaže kontrolne točke (vrhove), indekse poligona i elemente vrhova za normale, UV koordinate i boje vrhova.

Ključne klase geometrije:

• Mesh: poligonalna mreža s controlPoints i polygonCount
• Geometry: osnovna klasa s upravljanjem elementima vrhova
• VertexElementNormal: normale po vrhu ili po vrhu poligona
• VertexElementUV: teksturne koordinate (jedan ili više UV kanala)
• VertexElementVertexColor: podatci o boji po vrhu
• MappingMode: kontrolira kako se podaci elementa mapiraju na poligone (CONTROL_POINT, POLYGON_VERTEX, POLYGON, EDGE, ALL_SAME)
• ReferenceMode: kontrolira strategiju indeksiranja (DIRECT, INDEX, INDEX_TO_DIRECT)
• VertexElementType: identificira semantiku vertex elementa
• 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}`);
    }
  }
}

Sustav materijala

Aspose.3D FOSS za TypeScript podržava tri tipa materijala koji pokrivaju cijeli raspon od naslijeđenog Phong sjenčanja do fizički temeljene renderacije:

• LambertMaterial: difuzna boja i ambijentalna boja; mapira se na jednostavne OBJ/DAE materijale
• PhongMaterial: dodaje spekularnu boju, sjaj i emisivnost; zadana OBJ vrsta materijala
• PbrMaterial: fizički temeljeni model hrapavosti/metalnosti; koristi se za uvoz i izvoz glTF 2.0

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

Primjena PBR materijala pri izgradnji 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 s kompletnim skupom 3D matematičkih tipova, svi potpuno tipizirani:

• Vector3: vektor s 3 komponente; podržava minus(), times(), dot(), cross(), normalize(), length, angleBetween()
• Vector4: vektor s 4 komponente za homogen koordinate
• Matrix4: 4×4 matrica transformacije s concatenate(), transpose, decompose, setTRS
• Quaternion: kvaternion rotacije s fromEulerAngle() (statički, jedinstveni), eulerAngles() (instancna metoda), slerp(), normalize()
• BoundingBox: okvir ograničenja poravnat s osima s minimum, maximum, center, size, merge
• FVector3: varijanta jednostruke preciznosti za Vector3 : koristi se u podacima vertex elementa

Izračunavanje okvira ograničenja 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 kutova:

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

Sustav animacije

API za animaciju modelira isječke, čvorove, kanale i sekvence ključnih okvira:

• AnimationClip: imenovana kolekcija animacijskih čvorova; pristupa se putem scene.animationClips; izlaže animations: AnimationNode[]
• AnimationNode: imenovana grupa od BindPoints; stvoreno putem clip.createAnimationNode(name), pristupano putem clip.animations
• BindPoint: veže AnimationNode : na određeno svojstvo na objektu scene; izlaže property : i channelsCount
• AnimationChannel: proširuje KeyframeSequence; sadrži zasebni keyframeSequence; pristupa se putem bindPoint.getChannel(name)
• KeyFrame: jedan par vrijeme/vrijednost; nosi po‑ključnom okviru interpolation: Interpolation
• KeyframeSequence: uređeni popis KeyFrame objekata putem keyFrames; ima preBehavior i postBehavior (Extrapolation)
• Interpolation: enumeracija: LINEAR, CONSTANT, BEZIER, B_SPLINE, CARDINAL_SPLINE, TCB_SPLINE
• Extrapolation: klasa s type: ExtrapolationType i repeatCount: number
• ExtrapolationType: enumeracija: 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 streamove i buffer

Koristite scene.openFromBuffer() za učitavanje 3D scene izravno iz in-memory Buffer. Ovo je preporučeni obrazac za serverless funkcije, streaming cjevovode i obradu sredstava preuzetih putem HTTP-a bez zapisivanja 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 iz binarnih magičnih brojeva primjenjuje se pri učitavanju iz buffer‑a, pa se GLB, STL binarni i 3MF datoteke prepoznaju bez navođenja parametra formata.

Primjeri upotrebe

Primjer 1: Učitaj OBJ i izvezi u GLB

Ovaj primjer učitava Wavefront OBJ datoteku s materijalima, a zatim ponovno izvozi scenu kao binarnu glTF (GLB) datoteku prikladnu za web i korištenje u game engine‑ima.

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

Primjer 2: Ciklički STL s provjerom normala

Ovaj primjer učitava binarnu STL datoteku, ispisuje informacije o normalama po vrhu, a zatim ponovno izvozi scenu kao ASCII STL i provjerava ciklički 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);

Primjer 3: Izgradite scenu programatski i spremite je kao glTF

Ovaj primjer konstruira scenu s PBR materijalom od nule i sprema je kao JSON glTF datoteku.

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

Savjeti i najbolje prakse

• Koristite ObjLoadOptions.enableMaterials = true kad god trebate podatke o materijalu iz .mtl datoteka. Bez toga, popis materijala na svakom čvoru bit će prazan.
• Preferiraj binaryMode = true za GLB prilikom izrade sredstava za web ili game enginea. Binarni GLB je jedna samostalna datoteka i učitava se brže u preglednicima i engineima nego podjela JSON + .bin.
• Koristi openFromBuffer() u serverless okruženjima kako bi izbjegao privremeni I/O datoteka. Dohvati sredstvo, proslijedi Buffer izravno i zapiši izlaz u stream ili drugi buffer.
• Provjeri node.entity prije kastanja: ne svi čvorovi nose entitet. Uvijek zaštiti s instanceof provjerom prije pristupa Mesh-specifične svojstva poput controlPoints.
• Postavi normalizeNormal = true u ObjLoadOptions kada vaši izvorni OBJ datoteke dolaze iz nepouzdanih izvora. Ovo sprječava da degenerirane normale propagiraju u daljnje renderiranje ili korake validacije.
• Zadrži strict: true u tsconfig.json: biblioteka je napisana uz noImplicitAny i strictNullChecks. Onemogućavanje strict maskira stvarne tipne pogreške i poništava vrijednost tipiziranog API-ja.
• Prođite putem childNodes, a ne petlja s indeksom: the childNodes svojstvo vraća iterabilni objekt; izbjegavajte oslanjanje na numeričko indeksiranje radi buduće kompatibilnosti.

Uobičajeni problemi

Često postavljana pitanja

Zahtijeva li biblioteka neke izvorne dodatke ili sistemske pakete? Ne. Aspose.3D FOSS za TypeScript ima jedinu runtime ovisnost: xmldom, koji je čist JavaScript i automatski se instalira putem npm-a. Nema .node izvornih dodataka i nema sistemskih paketa za instalaciju.

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

Mogu li koristiti biblioteku u pregledničkom paketu (webpack/esbuild)? Biblioteka cilja Node.js i koristi Node.js fs i Buffer API‑ji. Pakiranje za preglednik nije službeno podržano. Za korištenje u pregledniku učitajte scenu na poslužitelju i prenesite rezultat (npr. kao GLB) klijentu.

Koja je razlika između GltfSaveOptions.binaryMode = true i false? binaryMode = false generira .gltf JSON datoteku plus zasebni .bin binarni buffer sidecar. binaryMode = true generira jedinstvenu samostalnu .glb datoteku. Upotrijebite true za isporuku produkcijskih sredstava.

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

Je li podrška za FBX potpuna? Ne. U biblioteci postoje klase za uvoz i izvoz FBX‑a, ali FBX nije integriran u Scene.open() ili Scene.save() automatsko otkrivanje. Pozivanje scene.open('file.fbx') neće pozvati FBX uvoznik; datoteka će biti obrađena putem STL rezervnog puta. Koristite FBX‑specifične klase uvoznika/izvoznika izravno ako trebate FBX I/O. Pogledajte tablicu podrške formata iznad koja označava FBX kao No*.

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

Sažetak API reference