Savybės ir funkcionalumas

Aspose.3D FOSS for TypeScript yra MIT licencijuota Node.js biblioteka, skirta įkelti, kurti ir eksportuoti 3D scenas. Ji pateikiama su pilnomis TypeScript tipų apibrėžtimis, viena vykdymo laiko priklausomybe (xmldom), ir palaikymu šešiems pagrindiniams 3D failų formatams. Šis puslapis yra pagrindinė nuoroda visoms funkcijų sritims ir jame pateikti vykdomi TypeScript kodo pavyzdžiai kiekvienai iš jų.

Įdiegimas ir konfigūracija

Įdiekite paketą iš npm naudodami vieną komandą:

npm install @aspose/3d

Paketas taikomas CommonJS ir reikalauja Node.js 18 arba naujesnės versijos. Įdiegus, patikrinkite, ar jūsų tsconfig.json įtraukia šias kompiliatoriaus parinktis, kad būtų visiškas suderinamumas:

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

Importuokite pagrindinį Scene klasę iš paketo šaknies. Formatui specifinės parinkčių klasės importuojamos iš atitinkamų po‑katalogų:

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

Savybės ir funkcionalumas

Formatų palaikymas

Aspose.3D FOSS for TypeScript skaito ir rašo šešis pagrindinius 3D failų formatus. Formato aptikimas įkeliant yra automatinis, remiantis binariniais magiškais skaičiais, todėl nereikia explicitiai nurodyti šaltinio formato.

OBJ įkėlimas su medžiagomis:

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

Išsaugojimas į GLB (binarinį 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);

Scenos grafas

Visas 3D turinys organizuotas kaip medžio Node objektų, kurių šaknys yra scene.rootNode. Kiekvienas mazgas gali nešti Entity (vieną Mesh, Camera, Light, arba kitą SceneObject) ir vieną Transform kuris padeda jį pozicionuoti santykinai pagal tėvą.

Svarbiausios scenos grafiko klasės:

• Scene: aukščiausio lygio konteineris; talpina rootNode ir animationClips
• Node: pavadintas medžio mazgas su childNodes, entity, transform, ir materials
• Entity: bazinė klasė prijungiamų objektų (Mesh, Camera, Light)
• SceneObject: bazinė klasė, kurią dalijasi Node ir Entity
• A3DObject: šaknies bazinė klasė su name ir savybių maišelis
• Transform: vietinis poslinkis, sukimas (Euler ir kvaternionas) ir mastelis

Scenos grafo perėjimas:

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

Scenos hierarchijos kūrimas programiškai:

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 ir Mesh

Mesh yra pagrindinis geometrijos tipas. Jis išplečia Geometry ir atskleidžia valdymo taškus (viršūnes), daugiakampių indeksus ir viršūnių elementus normalioms, UV ir viršūnių spalvoms.

Pagrindinės geometrijos klasės:

• Mesh: daugiakampių tinklelis su controlPoints ir polygonCount
• Geometry: bazinė klasė su viršūnių elementų valdymu
• VertexElementNormal: kiekvienos viršūnės arba daugiakampio viršūnės normalės
• VertexElementUV: tekstūros koordinatės (vienas arba keli UV kanalai)
• VertexElementVertexColor: kiekvienos viršūnės spalvų duomenys
• MappingMode: valdo, kaip elemento duomenys susiejami su daugiakampiaisCONTROL_POINT, POLYGON_VERTEX, POLYGON, EDGE, ALL_SAME)
• ReferenceMode: valdo indeksavimo strategiją (DIRECT, INDEX, INDEX_TO_DIRECT)
• VertexElementType: nustato viršūnės elemento semantiką
• TextureMapping: tekstūros kanalo išvardijimas

Tinklo duomenų skaitymas iš įkelto scenos:

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

Medžiagų sistema

Aspose.3D FOSS for TypeScript palaiko tris medžiagų tipus, apimančius visą spektrą nuo senosios Phong apšvietimo iki fiziškai pagrįsto atvaizdavimo:

• LambertMaterial: difuzinė spalva ir aplinkos spalva; susiejama su paprastais OBJ/DAE medžiagomis
• PhongMaterial: prideda spekuliarinę spalvą, blizgesį ir emisiją; numatytasis OBJ medžiagos tipas
• PbrMaterial: fizinio pagrindo šiurkštumo/metalų modelis; naudojamas glTF 2.0 importui ir eksportui

Medžiagų skaitymas iš įkelto OBJ scenos:

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 medžiagos taikymas kuriant glTF sceną:

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

Matematinės priemonės

Biblioteka tiekiama su pilnu 3D matematikos tipų rinkiniu, visi visiškai tipizuoti:

• Vector3: 3 komponentų vektorius; palaiko minus(), times(), dot(), cross(), normalize(), length, angleBetween()
• Vector4: 4 komponentų vektorius homogeninėms koordinatėms
• Matrix4: 4×4 transformacijos matrica su concatenate(), transpose, decompose, setTRS
• Quaternion: rotacijos kvaternionas su fromEulerAngle() (statinis, vienaskaitinis), eulerAngles() (instancijos metodas), slerp(), normalize()
• BoundingBox: ašies lygių ribų dėžutė su minimum, maximum, center, size, merge
• FVector3: viengubo tikslumo variantas Vector3 naudojamas viršūnių elemento duomenyse

Ribinės dėžės skaičiavimas iš tinklo viršūnių:

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

Transformacijos kūrimas iš Eulerio kampų:

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

Animacijos sistema

Animacijos API modeliuoja klipus, mazgus, kanalus ir raktų kadrų sekas:

• AnimationClip:pavadintas animacijos mazgų rinkinys; pasiekiamas per scene.animationClips; atskleidžia animations: AnimationNode[]
• AnimationNode: pavadinta grupė BindPoints; sukurta per clip.createAnimationNode(name), pasiekiama per clip.animations
• BindPoint: susieja AnimationNode prie konkrečios savybės scenos objekte; atskleidžia property ir channelsCount
• AnimationChannel: plečia KeyframeSequence; saugo atskirą keyframeSequence; pasiekiama per bindPoint.getChannel(name)
• KeyFrame: viena laiko/vertės pora; neša per raktų kadrą interpolation: Interpolation
• KeyframeSequence: išrikiuotas sąrašas KeyFrame objektus per keyFrames; turi preBehavior ir postBehavior (Extrapolation)
• Interpolation: enum: LINEAR, CONSTANT, BEZIER, B_SPLINE, CARDINAL_SPLINE, TCB_SPLINE
• Extrapolation: class with type: ExtrapolationType ir repeatCount: number
• ExtrapolationType: enum: CONSTANT, GRADIENT, CYCLE, CYCLE_RELATIVE, OSCILLATE

Animacijos duomenų skaitymas iš įkelto scenos:

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

Srauto ir buferio palaikymas

Naudokite scene.openFromBuffer() įkelti 3D sceną tiesiogiai iš atminties Buffer. Tai rekomenduojamas modelis serverless funkcijoms, srautinėms duomenų konvejoms ir išteklių apdorojimui, gautiems per HTTP, be įrašymo į 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);
  }
}

Formatų automatinis aptikimas pagal binarinius magiškus skaičius galioja įkeliant iš buferio, todėl GLB, STL binariniai ir 3MF failai yra atpažįstami be formatų parametro nurodymo.

Naudojimo pavyzdžiai

Pavyzdys 1: Įkelti OBJ ir eksportuoti į GLB

Šiame pavyzdyje įkeliamas Wavefront OBJ failas su medžiagomis, po to scena iš naujo eksportuojama kaip binarinis glTF (GLB) failas, tinkamas naudoti internete ir žaidimų varikliuose.

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

Pavyzdys 2: Pilnas STL ciklas su normalų tikrinimu

Šiame pavyzdyje įkeliamas binarinis STL failas, išvedama informacija apie normalus kiekvienam viršūnių taškui, po to scena iš naujo eksportuojama kaip ASCII STL ir patikrinamas ciklo tikslumas.

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

Pavyzdys 3: Sukurti sceną programiškai ir įrašyti kaip glTF

Šis pavyzdys sukuria sceną su PBR medžiaga nuo nulio ir įrašo ją kaip JSON glTF failą.

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

Patarimai ir geriausia praktika

• Naudokite ObjLoadOptions.enableMaterials = true kai jums reikia medžiagų duomenų iš .mtl failų. Be to, medžiagų sąrašas kiekviename mazge bus tuščias.
• Pirmenybę teikite binaryMode = true GLB formatui kai kuriate išteklius žiniatinkliui arba žaidimų varikliams. Binary GLB yra vienas savarankiškas failas ir įkeliamas greičiau naršyklėse ir varikliuose nei JSON + .bin suskirstymas.
• Naudokite openFromBuffer() serverless aplinkose siekiant išvengti laikino failų I/O. Atsisiųskite išteklių, perduokite Buffer tiesiogiai ir įrašykite išvestį į srautą arba kitą buferį.
• Patikrinkite node.entity prieš konvertavimą: ne visi mazgai turi objektą. Visada apsaugokite su instanceof patikrinimu prieš pasiekiant Mesh-specifinių savybių, pvz. controlPoints.
• Nustatykite normalizeNormal = true į ObjLoadOptions kai jūsų šaltinio OBJ failai ateina iš nepatikimų šaltinių. Tai neleidžia iškraipytų normalų plisti į tolimesnius atvaizdavimo ar validacijos etapus.
• Išlaikykite strict: true tsconfig.json faile: biblioteka sukurta su noImplicitAny ir strictNullChecks. Išjungimas strict maskuoja tikras tipų klaidas ir neigiamai veikia tipizuotos API vertę.
• Naršyti per childNodes, ne indeksų ciklas: childNodes savybė grąžina iteruojamą objektą; venkite pasikliauti skaitine indeksacija, kad išlaikytumėte ateities suderinamumą.

Dažnos problemos

Dažnai užduodami klausimai

Ar biblioteka reikalauja kokių nors natūralių papildinių arba sistemos paketų? Ne. Aspose.3D FOSS for TypeScript turi vieną vykdymo laiką priklausomybę: xmldom, kuris yra grynas JavaScript ir įdiegtas automatiškai per npm. Nėra .node natūralių papildinių ir jokių sistemos paketų, kurių reikia įdiegti.

Kokios Node.js versijos palaikomos? Node.js 18, 20 ir 22 LTS. Biblioteka orientuota į CommonJS išvestį ir viduje naudoja ES2020 kalbos funkcijas.

Ar galiu naudoti biblioteką naršyklės pakete (webpack/esbuild)? Biblioteka orientuota į Node.js ir naudoja Node.js fs ir Buffer API. Naršyklės paketavimas nėra oficialiai palaikomas. Naršyklės naudojimui įkelkite sceną serverio pusėje ir perduokite rezultatą (pvz., kaip GLB) klientui.

Kuo skiriasi GltfSaveOptions.binaryMode = true ir false? binaryMode = false sukuria .gltf JSON failą ir atskirą .bin dvejetainio buferio šoninis komponentas. binaryMode = true sukuria vieną savarankišką .glb failą. Naudokite true gamybos turto pristatymui.

Ar galiu įkelti failą iš HTTP atsakymo nesaugodamas jo diske? Taip. Gaukite atsakymą kaip Buffer (pvz., naudojant node-fetch arba įmontuotą fetch Node 18+), tada iškvieskite scene.openFromBuffer(buffer, options).

Ar FBX palaikymas baigtas? Ne. FBX importavimo ir eksportavimo klasės bibliotekoje egzistuoja, tačiau FBX nėra integruotas į Scene.open() arba Scene.save() automatinį aptikimą. Iškviečiant scene.open('file.fbx') nebus iškviestas FBX importuotojas; failas bus apdorotas naudojant STL atsarginį kelią. Naudokite FBX specifines importavimo/eksportavimo klases tiesiogiai, jei jums reikia FBX I/O. Žiūrėkite formatų palaikymo lentelę aukščiau, kurioje FBX pažymėta kaip No*.

Ar biblioteka palaiko TypeScript 4.x? Rekomenduojama TypeScript 5.0+. TypeScript 4.7+ turėtų veikti praktikoje, tačiau biblioteka yra testuota ir sukurta pagal 5.0+.

API nuorodų santrauka