Funkcijas un iespējas

Aspose.3D FOSS for TypeScript ir MIT licencēta Node.js bibliotēka 3D skenējumu ielādēšanai, konstruēšanai un eksportēšanai. Tā tiek piegādāta ar pilnīgiem TypeScript tipa definīcijām, vienu izpildlaika atkarību (xmldom), un atbalstu sešiem galvenajiem 3D failu formātiem. Šī lapa ir galvenais atsauces materiāls visām funkcionalitātes jomām un ietver izpildāmus TypeScript koda piemērus katram no tiem.

Instalēšana un iestatīšana

Instalējiet pakotni no npm, izmantojot vienu komandu:

npm install @aspose/3d

Pakotne mērķē uz CommonJS un pieprasa Node.js 18 vai jaunāku. Pēc instalēšanas pārbaudiet, vai jūsu tsconfig.json ietver šādas kompilatora opcijas pilnai saderībai:

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

Importējiet galveno Scene klasi no pakotnes saknes. Formāta specifiskās opciju klases tiek importētas no attiecīgajām apakšceļām:

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

Funkcijas un iespējas

Formātu atbalsts

Aspose.3D FOSS for TypeScript lasa un raksta sešus galvenos 3D failu formātus. Formāta noteikšana notiek automātiski, balstoties uz bināriem maģiskajiem skaitļiem ielādes laikā, tāpēc nav jānorāda avota formāts manuāli.

OBJ ielāde ar materiāliem:

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

Saglabāšana kā GLB (binārais 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);

Ainas grafiks

Visais 3D saturs ir organizēts kā koks no Node objektiem, kas sakņoti pie scene.rootNode. Katrs mezgls var nēsāt Entity (a Mesh, Camera, Light, vai cits SceneObject) un a Transform kas pozicionē to attiecībā pret tā vecāku.

Galvenās ainas grafika klases:

• Scene: augstākā līmeņa konteineris; satur rootNode un animationClips
• Node: nosaukts koka mezgls ar childNodes, entity, transform, un materials
• Entity: pamata klase pievienojamiem objektiem (Mesh, Camera, Light)
• SceneObject: pamata klase, ko koplieto Node un Entity
• A3DObject: saknes pamata klase ar name un īpašību soma
• Transform: lokāls pārvietojums, rotācija (Eilera un Kvaterniona), un mērogs

Ainas grafika pārlūkošana:

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

Izveidojot ainas hierarhiju programmatiski:

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

Ģeometrija un Mesh

Mesh ir galvenais ģeometrijas veids. Tas paplašina Geometry un atklāj kontroles punktus (virsotnes), daudzstūru indeksus, un virsotņu elementus normālēm, UV un virsotņu krāsām.

Galvenās ģeometrijas klases:

• Mesh: daudzstūra režģis ar controlPoints un polygonCount
• Geometry: pamata klase ar virsotnes elementu pārvaldību
• VertexElementNormal: katras virsotnes vai katras daudzstūra virsotnes normāles
• VertexElementUV: tekstūras koordinātas (viens vai vairāki UV kanāli)
• VertexElementVertexColor: krāsu dati uz katras virsotnes
• MappingMode: nosaka, kā elementu dati tiek kartēti uz daudzstūriem (CONTROL_POINT, POLYGON_VERTEX, POLYGON, EDGE, ALL_SAME)
• ReferenceMode: nosaka indeksēšanas stratēģiju (DIRECT, INDEX, INDEX_TO_DIRECT)
• VertexElementType: identificē virsotnes elementa semantiku
• TextureMapping: tekstūras kanālu enumerācija

Tīkla datu nolasīšana no ielādētas ainas:

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

Materiālu sistēma

Aspose.3D FOSS for TypeScript atbalsta trīs materiālu tipus, kas aptver pilnu spektru no mantotā Phong ēnošanas līdz fiziski balstītai renderēšanai:

• LambertMaterial: diffuse krāsa un ambientāla krāsa; kartējas uz vienkāršiem OBJ/DAE materiāliem
• PhongMaterial: pievieno spekulāro krāsu, spīdumu un emisīvo; noklusējuma OBJ materiāla veids
• PbrMaterial: fizikāli balstīts raupjuma/metāla modelis; tiek izmantots glTF 2.0 importam un eksportam

Materiālu nolasīšana no ielādētas OBJ ainas:

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 materiāla piemērošana, veidojot glTF ainu:

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

Matemātikas utilītprogrammas

Bibliotēka tiek piegādāta ar pilnu 3D matemātikas tipu komplektu, visi pilnīgi tipizēti:

• Vector3: 3-komponentu vektors; atbalsta minus(), times(), dot(), cross(), normalize(), length, angleBetween()
• Vector4: 4-komponentu vektors homogēnām koordinātām
• Matrix4: 4×4 transformācijas matrica ar concatenate(), transpose, decompose, setTRS
• Quaternion: rotācijas kvaternions ar fromEulerAngle() : (statiskā, vienīgā), eulerAngles() : (instanču metode), slerp(), normalize()
• BoundingBox: asīmēta ar asīmām iekļaujošā kaste ar minimum, maximum, center, size, merge
• FVector3:vienkāršas precizitātes variants Vector3 izmanto virsotnes elementu datos

Robežkastes aprēķināšana no režģa virsotnēm:

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

Transformācijas izveide no Eilera leņķiem:

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ācijas sistēma

Animācijas API modelē klipus, mezglus, kanālus un atslēgkadru secības:

• AnimationClip: nosauktā animācijas mezglu kolekcija; piekļūst caur scene.animationClips;atklāj animations: AnimationNode[]
• AnimationNode:nosauktā grupa BindPoints; izveidots caur clip.createAnimationNode(name), piekļūst caur clip.animations
• BindPoint: sasaista ar AnimationNode uz konkrētu īpašību ainas objektā; atklāj property un channelsCount
• AnimationChannel: paplašina KeyframeSequence; satur atsevišķu keyframeSequence; piekļūst caur bindPoint.getChannel(name)
• KeyFrame: viena laika/vērtības pāra; nes katram atslēgkadrim interpolation: Interpolation
• KeyframeSequence: sakārtots saraksts ar KeyFrame objektus caur keyFrames; ir preBehavior un postBehavior (Extrapolation)
• Interpolation: uzskaitījums: LINEAR, CONSTANT, BEZIER, B_SPLINE, CARDINAL_SPLINE, TCB_SPLINE
• Extrapolation: klase ar type: ExtrapolationType un repeatCount: number
• ExtrapolationType: enum: CONSTANT, GRADIENT, CYCLE, CYCLE_RELATIVE, OSCILLATE

Animācijas datu nolasīšana no ielādētas ainas:

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

Plūsmas un bufera atbalsts

Izmantot scene.openFromBuffer() lai ielādētu 3D ainu tieši no atmiņā esoša Buffer. Tas ir ieteicamais modelis serverless funkcijām, straumēšanas cauruļvadiem un aktīvu apstrādei, kas tiek iegūti caur HTTP, bez rakstīšanas uz diska.

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

Formāta automātiskā noteikšana no bināriem maģiskajiem skaitļiem tiek piemērota, ielādējot no bufera, tāpēc GLB, STL binārie un 3MF faili tiek atpazīti, nepievienojot formāta parametru.

Lietošanas piemēri

Piemērs 1: Ielādēt OBJ un eksportēt uz GLB

Šis piemērs ielādē Wavefront OBJ failu ar materiāliem, pēc tam atkārtoti eksportē ainu kā bināru glTF (GLB) failu, kas piemērots tīmekļa un spēļu dzinēju lietošanai.

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

Piemērs 2: Pilna ceļa STL ar normālu validāciju

Šis piemērs ielādē bināru STL failu, izvada katra virsotnes normālu informāciju, pēc tam atkārtoti eksportē ainu kā ASCII STL un pārbauda pilna ceļa procesu.

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

Piemērs 3: Izveidot ainu programmatiski un saglabāt kā glTF

Šis piemērs no nulles izveido ainu ar PBR materiālu un saglabā to kā JSON glTF failu.

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

Padomi un labākā prakse

• Izmantot ObjLoadOptions.enableMaterials = true ikreiz, kad nepieciešami materiālu dati no .mtl failiem. Bez tā katra mezgla materiālu saraksts būs tukšs.
• Dodiet priekšroku binaryMode = true GLB izveidojot aktīvus tīmekļa vai spēļu dzinējiem. Binārais GLB ir viens pašpietiekams fails, kas ielādējas ātrāk pārlūkprogrammās un dzinējos nekā JSON + .bin sadalījums.
• Izmantot openFromBuffer() serverless vidēs lai izvairītos no pagaidu failu I/O. Iegūsti aktīvu, pārsūti Buffer tieši, un ieraksti izvadi plūsmā vai citā buferī.
• Pārbaudi node.entity pirms pārveidošanas: ne visi mezgli nesatur entītiju. Vienmēr aizsargājies ar instanceof pārbaudi pirms piekļuves Mesh-specifiskas īpašības, piemēram controlPoints.
• Kopa normalizeNormal = true iekš ObjLoadOptions kad jūsu avota OBJ faili nāk no neuzticamiem avotiem. Tas novērš deģenerētu normālu izplatīšanos uz lejuplūstošajiem renderēšanas vai validācijas posmiem.
• Saglabāt strict: true tsconfig.json: bibliotēka ir izveidota ar noImplicitAny un strictNullChecks. Atspējojot strict maskē reālas tipa kļūdas un apdraud tipizētās API vērtību.
• Traversēt caur childNodes, nevis indeksa cikls: childNodes īpašība atgriež iterējamu objektu; izvairieties no atkarības no skaitliskās indeksēšanas, lai nodrošinātu nākotnes saderību.

Biežāk sastopamās problēmas

Biežāk uzdotie jautājumi

Vai bibliotēkai ir nepieciešami kādi vietējie papildinājumi vai sistēmas pakotnes? Nr. Aspose.3D FOSS priekš TypeScript ir viena izpildlaika atkarība: xmldom, kas ir tīrs JavaScript un tiek instalēts automātiski ar npm. Nav .node dabiski papildinājumi un nav sistēmas pakotņu, ko instalēt.

Kādas Node.js versijas tiek atbalstītas? Node.js 18, 20 un 22 LTS. Bibliotēka mērķē uz CommonJS izvadi un iekšēji izmanto ES2020 valodas funkcijas.

Vai varu izmantot bibliotēku pārlūkprogrammas pakotnē (webpack/esbuild)? Bibliotēka mērķē uz Node.js un izmanto Node.js fs un Buffer API. Pārlūkprogrammas pakotnes veidošana nav oficiāli atbalstīta. Lai izmantotu pārlūkā, ielādējiet ainu servera pusē un nosūtiet rezultātu (piemēram, kā GLB) klientam.

Kāda ir atšķirība starp GltfSaveOptions.binaryMode = true un false? binaryMode = false izveido .gltf JSON failu plus atsevišķu .bin bināro bufera blakusfailu. binaryMode = true izveido vienu pašpietiekamu .glb failu. Izmantojiet true ražošanas aktīvu piegādei.

Vai varu ielādēt failu no HTTP atbildes, nesaglabājot to diskā? Jā. Iegūstiet atbildi kā Buffer (piemēram, izmantojot node-fetch vai iebūvēto fetch Node 18+), tad izsauc scene.openFromBuffer(buffer, options).

Vai FBX atbalsts ir pilnīgs? Nē. FBX importētāja un eksportētāja klases ir bibliotēkā, bet FBX nav pieslēgts Scene.open() vai Scene.save() automātiskā noteikšana. Izsaucot scene.open('file.fbx') neizsauks FBX importētāju; fails tiks apstrādāts ar STL rezerves ceļu. Izmantojiet FBX‑specifiskās importētāja/eksportētāja klases tieši, ja jums vajag FBX I/O. Skatiet formāta atbalsta tabulu augstāk, kurā FBX ir atzīmēts kā No*.

Vai bibliotēka atbalsta TypeScript 4.x? Ieteicams izmantot TypeScript 5.0+. TypeScript 4.7+ praksē jābūt darboties, bet bibliotēka ir testēta un izstrādāta pret 5.0+.

API Atsauces Kopsavilkums