Jellemzők és funkciók

Aspose.3D FOSS for TypeScript egy MIT-licencelt Node.js könyvtár a 3D jelenetek betöltéséhez, felépítéséhez és exportálásához. Teljes TypeScript típusdefiníciókkal érkezik, egyetlen futásidejű függőséggel (xmldom), és támogatja a hat fő 3D fájlformátumot. Ez az oldal az összes funkcióterület elsődleges hivatkozása, és futtatható TypeScript kódpéldákat tartalmaz mindegyikhez.

Telepítés és beállítás

Telepítsd a csomagot az npm‑ről egyetlen paranccsal:

npm install @aspose/3d

A csomag a CommonJS-t célozza, és Node.js 18 vagy újabb verziót igényel. Telepítés után ellenőrizze, hogy a tsconfig.json tartalmazza a következő fordítóbeállításokat a teljes kompatibilitás érdekében:

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

Importálja a fő Scene osztályt a csomag gyökeréből. A formátum-specifikus opcióosztályok a megfelelő alútvonalakról importálhatók:

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

Jellemzők és funkciók

Formátumtámogatás

Aspose.3D FOSS for TypeScript hat fő 3D fájlformátumot olvas és ír. A formátumdetektálás betöltéskor automatikusan a bináris mágikus számok alapján történik, így nem kell explicit módon megadnod a forrásformátumot.

OBJ betöltése anyagokkal:

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

Mentés GLB‑be (bináris 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);

Jelenet gráf

Minden 3D tartalom egy fává van szervezve Node objektumok, amelyek a scene.rootNode. Minden csomópont képes hordozni egy Entity (a Mesh, Camera, Light, vagy más SceneObject) és egy Transform ami a szülőhöz viszonyítva helyezi el.

A jelenetgrafikon kulcsosztályai:

• Scene: a legfelső szintű tároló; tartalmazza rootNode és animationClips
• Node: egy névvel ellátott fa csomópont, amely childNodes, entity, transform, és materials
• Entity: alaposztály a csatolható objektumokhoz (Mesh, Camera, Light)
• SceneObject: alaposztály, amelyet megosztanak a Node és Entity
• A3DObject: gyökér alaposztály, amely tartalmazza name és tulajdonság-táska
• Transform: helyi eltolás, forgatás (Euler és Kvaternion), és méretezés

A jelenetgrafikon bejárása:

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

Jelenet hierarchia programozott létrehozása:

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 és Mesh

Mesh az elsődleges geometria típus. Kiterjeszti Geometry és közzéteszi a vezérlőpontokat (csúcsok), poligon indexeket, valamint a csúcs elemeket a normálokhoz, UV-khez és csúcs színekhez.

Kulcsfontosságú geometria osztályok:

• Mesh: poligon háló a következővel controlPoints és polygonCount
• Geometry: alaposztály csúcs-elemek kezelésével
• VertexElementNormal: csúcsonkénti vagy poligon‑csúcsonkénti normálok
• VertexElementUV: textúra koordináták (egy vagy több UV csatorna)
• VertexElementVertexColor: csúcsonkénti színadat
• MappingMode: vezérli, hogyan térképeződik az elemadat a poligonokraCONTROL_POINT, POLYGON_VERTEX, POLYGON, EDGE, ALL_SAME)
• ReferenceMode:az indexelési stratégia vezérlése (DIRECT, INDEX, INDEX_TO_DIRECT)
• VertexElementType:azonosítja a csúcselem szemantikáját
• TextureMapping:textúra csatorna enumerációja

Mesh adatok beolvasása egy betöltött jelenetből:

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

Anyagrendszer

Aspose.3D FOSS for TypeScript három anyagtípust támogat, amelyek lefedik a teljes skálát a régi Phong árnyalástól a fizikailag alapú renderelésig:

• LambertMaterial:diffúz szín és környezeti szín; egyszerű OBJ/DAE anyagokra leképezve
• PhongMaterial:speculáris színt, fényességet és emisszív tulajdonságot ad hozzá; az alapértelmezett OBJ anyagtípus
• PbrMaterial:fizikai alapú durvaság/fémesség modell; a glTF 2.0 import és export során használatos

Anyagok beolvasása egy betöltött OBJ jelenetből:

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

PBR anyag alkalmazása glTF jelenet felépítésekor:

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

Matematikai segédeszközök

A könyvtár egy teljes 3D matematikai típuskészlettel érkezik, mindegyik teljesen típusos:

• Vector3:3 komponensű vektor; támogatja minus(), times(), dot(), cross(), normalize(), length, angleBetween()
• Vector4:4 komponensű vektor homogén koordinátákhoz
• Matrix4:4×4 transzformációs mátrix a következővel concatenate(), transpose, decompose, setTRS
• Quaternion:rotációs kvaternion a következővel fromEulerAngle() (statikus, szinguláris), eulerAngles() (példánymetódus), slerp(), normalize()
• BoundingBox:tengelyekhez igazított határoló doboz a következővel minimum, maximum, center, size, merge
• FVector3:egyszeres pontosságú változata a Vector3 csúcselem adatokban használt

Határoló doboz számítása a háló csúcspontjaiból:

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

Transzformáció építése Euler-szögekből:

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

Animációs rendszer

Az animációs API modellezi a klippeket, csomópontokat, csatornákat és kulcskocka sorozatokat:

• AnimationClip:nevesített animációs csomópontok gyűjteménye; elérhető a következőn keresztül scene.animationClips; kitesz animations: AnimationNode[]
• AnimationNode: névvel ellátott csoport BindPoints; létrehozva a clip.createAnimationNode(name), elérve a clip.animations
• BindPoint: összekapcsol egy AnimationNode egy adott tulajdonsághoz egy jelenetobjektumon; kitet property és channelsCount
• AnimationChannel: kiterjeszti KeyframeSequence; tart egy külön keyframeSequence; elérhető via bindPoint.getChannel(name)
• KeyFrame: egyetlen idő/érték pár; kulcskockánként hordoz interpolation: Interpolation
• KeyframeSequence: rendezett lista a KeyFrame objektumok via keyFrames; tartalmaz preBehavior és postBehavior (Extrapolation)
• Interpolation: enum: LINEAR, CONSTANT, BEZIER, B_SPLINE, CARDINAL_SPLINE, TCB_SPLINE
• Extrapolation: osztály a következővel type: ExtrapolationType és repeatCount: number
• ExtrapolationType: enum: CONSTANT, GRADIENT, CYCLE, CYCLE_RELATIVE, OSCILLATE

Animációs adatok beolvasása egy betöltött jelenetből:

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 és Buffer támogatás

Használja scene.openFromBuffer() 3D-s jelenet betöltéséhez közvetlenül egy memóriában lévőből Buffer. Ez a javasolt minta serverless függvényekhez, streaming csővezetékekhez, és HTTP-n keresztül lekért eszközök feldolgozásához anélkül, hogy lemezre írnánk.

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

A bináris varázsszámok alapján történő formátum automatikus felismerés a bufferből történő betöltéskor is érvényes, így a GLB, STL bináris és 3MF fájlok formátumparaméter megadása nélkül is felismertek.

Használati példák

Példa 1: OBJ betöltése és GLB-be exportálása

Ez a példa egy anyagokkal rendelkező Wavefront OBJ fájlt tölt be, majd a jelenetet bináris glTF (GLB) fájlként exportálja, amely alkalmas webes és játékmotoros felhasználásra.

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

Példa 2: Kétirányú STL normál ellenőrzéssel

Ez a példa egy bináris STL fájlt tölt be, kiírja a csúcsonkénti normál információkat, majd a jelenetet ASCII STL-ként exportálja, és ellenőrzi a körkörös átalakítást.

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

Példa 3: Jelenet programozott építése és mentése glTF formátumban

Ez a példa egy jelenetet épít fel egy PBR anyaggal a semmiből, és JSON glTF fájlként menti.

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

Tippek és bevált gyakorlatok

• Használja ObjLoadOptions.enableMaterials = true amikor anyagadatokra van szüksége .mtl fájlokból. Enélkül az egyes csomópontok anyaglistája üres lesz.
• Használja inkább binaryMode = true GLB-hez webes vagy játék motorokhoz eszközök előállításakor. A bináris GLB egy önálló, egyetlen fájl, és gyorsabban betöltődik a böngészőkben és motorokban, mint a JSON + .bin felosztás.
• Használja openFromBuffer() kiszolgáló nélküli környezetekben az ideiglenes fájl I/O elkerülése érdekében. Hozza be az eszközt, adja át a Buffer közvetlenül, és írja a kimenetet egy streambe vagy egy másik pufferbe.
• Ellenőrizze node.entity mielőtt átkonvertálná: nem minden csomópont tartalmaz entitást. Mindig ellenőrizzen egy instanceof ellenőrzést a hozzáférés előtt Mesh-specifikus tulajdonságokat, például controlPoints.
• Állítsa be normalizeNormal = true ban ObjLoadOptions amikor a forrás OBJ fájlok megbízhatatlan forrásokból származnak. Ez megakadályozza, hogy a degenerált normálok a downstream renderelés vagy validálási lépések során továbbterjedjenek.
• Tartsa strict: true a tsconfig.json-ban: a könyvtár a következővel készült noImplicitAny és strictNullChecks. Kikapcsolás strict elfedi a valódi típushibákat, és aláássa a típusos API értékét.
• Bejárás a childNodes, nem indexciklus: a childNodes a tulajdonság iterálható objektumot ad vissza; kerüld a numerikus indexelésre való támaszkodást a jövőbeli kompatibilitás érdekében.

Gyakori problémák

Gyakran Ismételt Kérdések

Igényel a könyvtár bármilyen natív kiegészítőt vagy rendszercsomagot? Nem. Aspose.3D FOSS for TypeScript egyetlen futásidejű függőséggel rendelkezik: xmldom, ami tiszta JavaScript, és az npm automatikusan telepíti. Nincsenek .node natív kiegészítők és nincs telepítendő rendszercsomag.

Mely Node.js verziók támogatottak? Node.js 18, 20, és 22 LTS. A könyvtár a CommonJS kimenetre céloz, és belsőleg ES2020 nyelvi funkciókat használ.

Használhatom a könyvtárat egy böngészőcsomagban (webpack/esbuild)? A könyvtár a Node.js-re céloz, és a Node.js-t használja fs és Buffer API-k. A böngészőben történő csomagolás nincs hivatalosan támogatva. Böngészőben való használathoz töltsd be a jelenetet szerveroldalon, és küldd át az eredményt (pl. GLB formátumban) a kliensnek.

Mi a különbség a GltfSaveOptions.binaryMode = true és false? binaryMode = false előállít egy .gltf JSON fájlt plusz egy külön .bin bináris puffer mellékletet. binaryMode = true előállít egyetlen önálló .glb fájlt. Használd a true a termelési eszközök szállításához.

Betölthetek egy fájlt egy HTTP válaszból anélkül, hogy lementeném a lemezre? Igen. Hozd be a választ mint egy Buffer (például a használatával node-fetch vagy a beépített fetch Node 18+-ban), majd hívd meg a scene.openFromBuffer(buffer, options).

Teljes-e az FBX támogatás? Nem. A könyvtárban léteznek FBX importáló és exportáló osztályok, de az FBX nincs beépítve a Scene.open() vagy Scene.save() automatikus felismerés. A hívás scene.open('file.fbx') nem fogja meghívni az FBX importálót; a fájlt az STL tartalék útvonal kezeli. Használja közvetlenül az FBX‑specifikus importáló/exportáló osztályokat, ha FBX I/O‑ra van szüksége. Tekintse meg a fenti formátumtámogatási táblázatot, amely az FBX‑et mint No*.

Támogatja a könyvtár a TypeScript 4.x‑et? A TypeScript 5.0+ ajánlott. A TypeScript 4.7+ a gyakorlatban működnie kell, de a könyvtárat 5.0+ verzióval tesztelték és írták.

API-referencia összefoglaló