Charakteristika a funkčnost

Aspose.3D FOSS pro TypeScript je knižnice Node.js s licencí MIT pro načítání, konstrukci a export 3D scén. Je dodávána se kompletními definicemi typů Typiskriptu (s jedinou závislostí na čase běhu).xmldomTato stránka je primární referencí pro všechny oblasti funkce a obsahuje běžné příklady kódu TypeScript pro každou z nich.

Instalace a nastavení

Nainstalujte balíček z npm pomocí jediného příkazu:

Balíček je zaměřen na CommonJS a vyžaduje Node.js 18 nebo novější. Po instalaci ověříte, zda jste si užili aplikaci Node .js (včetně funkcí Java). tsconfig.json obsahuje následující možnosti kompilátoru pro plnou kompatibilitu:

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

Import hlavní . Scene třída ze kořene balíčku. Klasi pro specifické formáty jsou importovány z jejich příslušných podcestu:

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

Charakteristika a funkčnost

Podpora formátu

Aspose.3D FOSS pro TypeScript čte a píše šest hlavních 3D formátů souborů. Detekce formátu je automatická z binárního magického čísla při načítání, takže nemusíte výslovně specifikovat zdrojový formáty.

Naložení OBJ materiály:

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

Ušetření na GLB (binární 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 scény

Všechny 3D obsah je organizován jako strom Node objekty zakořeněné v scene.rootNode.Každý uzel může mít Entity (a) Mesh, Camera, Light, nebo jiné SceneObject) a Transform který ji umístí ve vztahu k jejímu rodiči.

Klíčové třídy scén-grafu:

• Scene: vrchní nádrž; zásoby rootNode a) animationClips
• Node: jmenovaný stromový uzel s: childNodes, entity, transform,a) materials
• Entity: základní třída pro připojené předměty (Mesh, Camera, Light)
• SceneObject: základní třída sdílená: Node a) Entity
• A3DObject: základní třída s: name a majetková taška.
• Transform:Lokální překlad, rotace (Euler a Quaternion) a měřítko

Procházíme grafickou scény:

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

Programaticky vytváříme hierarchii scén:

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

Geometrie a síťová trubka

Mesh je primární typ geometrie. To se rozšiřuje na Geometry a odhaluje kontrolní body (křesky), indexy polygonů a prvky křižovatek pro normály, UV a barvy křížovek.

Klíčové geometrické třídy:

• Mesh: polygonová síť s: controlPoints a) polygonCount
• Geometry: základní třída s řízením prvků vrcholu.
• VertexElementNormal: normální hodnoty na vrchol nebo polygon-vrchol
• VertexElementUV: souřadnice textury (jeden nebo více UV kanálů)
• VertexElementVertexColor: barvová data v rámci vrcholu
• MappingMode: ovládá, jak jsou údaje o prvcích mapovány na polygony (CONTROL_POINT, POLYGON_VERTEX, POLYGON, EDGE, ALL_SAME)
• ReferenceMode: kontroluje strategii indexování (DIRECT, INDEX, INDEX_TO_DIRECT)
• VertexElementType: identifikuje sémantiku prvku vrcholu.
• TextureMapping: výčet texturačního kanálu

Čtení dat z síťového systému:

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ální systém

Aspose.3D FOSS pro TypeScript podporuje tři typy materiálů, které pokrývají celou škálu od starého stínění Phongu po fyzicky založené renderování:

• LambertMaterial: rozptýlená barva a okolní barvy; mapy na jednoduché materiály OBJ/DAE
• PhongMaterial: přidává zrcadlovou barvu, lesk a emise; standardní typ materiálu OBJ
• PbrMaterial: fyzicky založený drsnostní/metalický model; používaný pro dovoz a vývoz glTF 2.0

Čtení materiálů z natáčené scény OBJ:

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

Použití materiálu PBR při výstavbě scény glTF:

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

Matematické nástroje

Knihovna nabízí kompletní sadu 3D matematických typů, všechny plně vytypované:

• Vector3: 3-komponentový vektor; podpůrné systémy minus(), times(), dot(), cross(), normalize(), length, angleBetween()
• Vector4: 4komponentový vektor pro homogenní souřadnice
• Matrix4: 4×4 transformační matice s: concatenate(), transpose, decompose, setTRS
• Quaternion: rotační kvaternión s: fromEulerAngle() (statický, jednotný), eulerAngles() (metoda pro instanci), slerp(), normalize()
• BoundingBox: osově vyrovnaná ohraničovací krabice s: minimum, maximum, center, size, merge
• FVector3: jednopřesná varianta: Vector3 používané v datech o vrcholových prvcích

Výpočet omezujícího pole z vrcholů okna:

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

Vytvoření transformace z Eulerových úhlů:

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

Animovací systém

Animační API modeluje klipy, uzly, kanály a sekvence klíčových rámů:

• AnimationClip: jmenovaná sbírka animačních uzlů; přístup přes: scene.animationClips; odhalí animations: AnimationNode[]
• AnimationNode: jmenovaná skupina: BindPoints; vytvořeno prostřednictvím: clip.createAnimationNode(name), přístupné prostřednictvím: clip.animations
• BindPoint: se vztahuje k: AnimationNode na konkrétní vlastnost objektu scény; vystavuje property a) channelsCount
• AnimationChannel: se rozšiřuje: KeyframeSequence; má samostatný účetní závěrku. keyframeSequence;Přístup prostřednictvím: bindPoint.getChannel(name)
• KeyFrame: jednotný časový/hodnotový pár; nese za klíčové snímky interpolation: Interpolation
• KeyframeSequence: řádný seznam: KeyFrame objekty prostřednictvím keyFrames;, má: preBehavior a) postBehavior (Extrapolation)
• Interpolation:00: 01: 00: 00 , a to je ono .: LINEAR, CONSTANT, BEZIER, B_SPLINE, CARDINAL_SPLINE, TCB_SPLINE
• Extrapolation:Třída s: type: ExtrapolationType a) repeatCount: number
• ExtrapolationType:00: 01: 00: 00 , a to je ono .: CONSTANT, GRADIENT, CYCLE, CYCLE_RELATIVE, OSCILLATE

Čtení animačních dat z nabité scény:

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

Podpora proudění a bufrování

Použití: scene.openFromBuffer() Nahrát 3D scénu přímo z paměti Buffer.Toto je doporučený vzor pro bezserverové funkce, streamovací potrubí a zpracování aktiv přinesených přes HTTP bez psaní 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);
  }
}

Automatické detekce formátu z binárních magických čísel se použije při načtení ze bufferu, takže jsou rozpoznány soubory GLB, STL a 3MF bez upřesnění parametru formatu.

Příklady použití

Příklad 1: Náklad OBJ a vývoz do GLB

Tento příklad načte soubor Wavefront OBJ s materiály, poté re-exportuje scénu jako binární glTF (GLB) soubory vhodné pro použití web a herní motoru.

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říklad 2: STL z cesty zpět s normálním ověřováním

Tento příklad načte binární soubor STL, vytiskne normální informace na vrchol a pak scénu znovu vyveze jako ASCII ST L a ověří jízdní tok.

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říklad 3: Programaticky vytvořit scénu a uložit jako glTF

Tento příklad staví scénu s PBR materiálem od nuly a ukládá ji jako soubor JSON glTF.

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

Tipy a nejlepší postupy

• Použití: ObjLoadOptions.enableMaterials = true Bez něj bude seznam materiálů na každém uzlu prázdný.
• Preferovat binaryMode = true pro GLB při vytváření aktiv pro webové nebo herní motory. Binární GLB je jediný samostatný soubor a načítá se rychleji v prohlížečích a motorů než JSON + .bin split.
• Použití: openFromBuffer() v prostředí bez serverů - Přines aktivum, předáš ho. Buffer přímo a zapíše výstup do proudu nebo jiného bufera.
• Ček. node.entity před odlitím:Ne všechny uzly mají entitu. Vždy se střeďte s instanceof Zkontrolujte před vstupem. Mesh-specifikní vlastnosti, jako jsou: controlPoints.
• Sestavení: normalizeNormal = true v . ObjLoadOptions To zabraňuje, aby se degenerované normály šířily do postupů následného vykreslování nebo ověřování.
• Udržujte. strict: true v tsconfig.json: knihovna je založena na: noImplicitAny a) strictNullChecks.Nefunkční. strict maskuje skutečné chyby v typování a odstraňuje hodnotu napsaného API.
• Procházet přes childNodes, ne indexová smyčka: v childNodes vlastnost vrací iterovatelnou; vyhněte se spoléhání na číselné indexování pro budoucí kompatibilitu.

Obvyklé problémy

Časté otázky

Vyžaduje knihovna nějaké nativní doplňky nebo systémové balíčky? Ne. Aspose.3D FOSS pro TypeScript má jednu závislost na čase spouštění: xmldom, který je čistý JavaScript a automaticky instalován pomocí npm. Neexistují žádné .node Nativní doplňky a žádné systémové balíčky k instalaci.

Které verze Node.js jsou podporovány? Node.js 18, 20, and 22 LTS. The library targets CommonJS output and uses ES2020 language features internally.

Mohu knihovnu používat v balení prohlížeče (webpack/esbuild)? Knihovna se zaměřuje na Node.js a používá Node .js fs a) Buffer API. Browser bundling není oficiálně podporován. Pro použití prohlížeče naložíte scénu na straně serveru a přenášejte výsledek (např. jako GLB) klientovi.

Jaký je rozdíl mezi GltfSaveOptions.binaryMode = true a) false? binaryMode = false produkuje .gltf Soubor JSON plus samostatný soubor . .bin binární bufferový boční vozík. binaryMode = true produkuje jeden samostatný .glb Použití souboru. true pro dodávku výrobních aktiv.

Můžu si načíst soubor z HTTP odpovědi bez uložení na disk? Ano, odpověď je jako… Buffer (např. s použitím node-fetch nebo vestavěné fetch v uzlu 18+), pak zavolejte scene.openFromBuffer(buffer, options).

Je podpora FBX kompletní? Ne. V knihovně existují třídy FBX importér a exportér, ale FBx není připojen do této knížky. Scene.open() nebo: Scene.save() - Auto-detekce. scene.open('file.fbx') nebude volán FBX importér; soubor bude zpracováván pomocí STL rezervní cesty. Použijte přímo specifické třídy dovozce/exportéře, pokud potřebujete FBx I/O. Viz tabulka podpory formátu výše, která označuje FB X jako No*.

Podporuje knihovna TypeScript 4.x? Doporučuje se TypeScript 5.0+. TypScript 4.7+ by měl pracovat v praxi, ale knihovna je testována a autorská proti 5.0.

Souhrnná referenční informace API