Funkce a vlastnosti

Aspose.3D FOSS pro TypeScript je knihovna Node.js licencovaná pod MIT, určená pro načítání, vytváření a export 3D scén. Dodává se s kompletními definicemi typů TypeScript, jednou runtime závislostí (xmldom), a podporou šesti hlavních formátů 3D souborů. Tato stránka je hlavní referencí pro všechny oblasti funkcí a obsahuje spustitelné příklady kódu TypeScript pro každou z nich.

Instalace a nastavení

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

npm install @aspose/3d

Balíček cílí na CommonJS a vyžaduje Node.js 18 nebo novější. Po instalaci ověřte, že vaše tsconfig.json obsahuje následující možnosti kompilátoru pro plnou kompatibilitu:

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

Importujte hlavní Scene třídu z kořene balíčku. Třídy možností specifické pro formát jsou importovány z jejich příslušných podcest:

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

Funkce a vlastnosti

Podpora formátů

Aspose.3D FOSS for TypeScript čte a zapisuje šest hlavních formátů 3D souborů. Detekce formátu je při načítání automatická na základě binárních magických čísel, takže není nutné explicitně uvádět zdrojový formát.

Načítání OBJ s 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);

Ukládání do 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);

Scénový graf

Veškerý 3D obsah je uspořádán jako strom Node objektů s kořenem v scene.rootNode. Každý uzel může nést Entity (a Mesh, Camera, Light, nebo jiný SceneObject) a Transform který jej umisťuje relativně k jeho rodiči.

Klíčové třídy scénového grafu:

• Scene: kontejner nejvyšší úrovně; obsahuje rootNode a animationClips
• Node: pojmenovaný uzel stromu s childNodes, entity, transform, a materials
• Entity: základní třída pro připojitelné objekty (Mesh, Camera, Light)
• SceneObject: základní třída sdílená mezi Node a Entity
• A3DObject: kořenová základní třída s name a kapsa vlastností
• Transform: lokální posunutí, rotace (Euler a Quaternion) a měřítko

Procházení grafu 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);

Programové vytváření hierarchie scény:

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 Mesh

Mesh je primárním typem geometrie. Rozšiřuje Geometry a zpřístupňuje řídicí body (vrcholy), indexy polygonů a elementy vrcholů pro normály, UV a barvy vrcholů.

Klíčové třídy geometrie:

• Mesh: polygonová síť s controlPoints a polygonCount
• Geometry: základní třída se správou elementů vrcholů
• VertexElementNormal: per-vertex nebo per-polygon-vertex normály
• VertexElementUV: texturové souřadnice (jeden nebo více UV kanálů)
• VertexElementVertexColor: per-vertex barevná data
• MappingMode: řídí, jak se data elementů mapují na polygony (ByControlPoint, ByPolygonVertex, atd.)
• ReferenceMode: řídí strategii indexování (Direct, IndexToDirect)
• VertexElementType: identifikuje sémantiku vrcholového elementu
• TextureMapping: enumerace texturových kanálů

Čtení dat mesh z načtené scény:

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

Systém materiálů

Aspose.3D FOSS pro TypeScript podporuje tři typy materiálů pokrývající celý rozsah od starého Phong stínování po fyzikálně založené renderování:

• LambertMaterial: difúzní barva a ambientní barva; mapuje na jednoduché materiály OBJ/DAE
• PhongMaterial: přidává spekulární barvu, lesk a emisivitu; výchozí typ materiálu OBJ
• PbrMaterial: fyzicky založený model drsnosti/kovovosti; používá se pro import a export glTF 2.0

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

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

Aplikace PBR materiálu při vytváření glTF scény:

import { Scene, Node, PbrMaterial } 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);   // 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é utility

Knihovna je dodávána s kompletním souborem 3D matematických typů, všechny plně typované:

• Vector3: 3‑komponentový vektor; podporuje add, subtract, scale, dot, cross, normalize, length
• Vector4: 4‑komponentový vektor pro homogenní souřadnice
• Matrix4: 4×4 transformační matice s multiply, invert, transpose, decompose
• Quaternion: rotační kvaternion s fromEulerAngles, toEulerAngles, slerp, normalize
• BoundingBox: osově zarovnaná ohraničující krabice s min, max, center, size, merge
• FVector3: jednopřesnostní varianta Vector3 použito v datech vrcholových elementů

Výpočet ohraničujícího boxu z vrcholů sítě:

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

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

Systém animace

API animace modeluje klipy, uzly, kanály a sekvence klíčových snímků:

• AnimationClip: pojmenovaná kolekce animačních uzlů; přístupná přes scene.animationClips
• AnimationNode: sváže klip se scénovým uzlem podle názvu
• AnimationChannel: cílí na konkrétní vlastnost (např. translation X) v animačním uzlu
• KeyFrame: jedna dvojice čas/hodnota
• KeyframeSequence: uspořádaný seznam KeyFrame objekty s Interpolation a Extrapolation nastavení
• Interpolation: režim interpolace klíčových snímků: Linear, Constant, Cubic
• Extrapolation: chování před/po rozsahu klíčových snímků: Constant, Cycle, Mirror

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

import { Scene, AnimationClip, KeyframeSequence } from '@aspose/3d';

const scene = new Scene();
scene.open('animated.fbx');

for (const clip of scene.animationClips) {
  console.log(`Clip: "${clip.name}"`);
  for (const animNode of clip.nodes) {
    console.log(`  Node: ${animNode.name}`);
    for (const channel of animNode.channels) {
      const seq: KeyframeSequence = channel.keyframeSequence;
      console.log(`    Channel "${channel.name}": ${seq.keyFrames.length} keyframes`);
      console.log(`    Interpolation: ${seq.interpolation}`);
    }
  }
}

Podpora streamů a bufferů

Použijte scene.openFromBuffer() k načtení 3D scény přímo z paměti Buffer. Toto je doporučený vzor pro serverless funkce, streamovací pipeline a zpracování aktiv načtených přes HTTP bez zápisu 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);
  }
}

Automatiké rozpoznání formátu z binárních magických čísel se použije při načítání z bufferu, takže soubory GLB, binární STL a 3MF jsou rozpoznány bez nutnosti zadávat parametr formátu.

Příklady použití

Příklad 1: Načíst OBJ a exportovat do GLB

Tento příklad načte soubor Wavefront OBJ s materiály a poté znovu exportuje scénu jako binární glTF (GLB) soubor vhodný pro použití na webu a ve herních enginech.

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: Round‑Trip STL s validací normál

Tento příklad načte binární STL soubor, vypíše informace o normálách pro každý vrchol a poté znovu exportuje scénu jako ASCII STL a ověří round‑trip.

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: Programově vytvořit scénu a uložit jako glTF

Tento příklad vytvoří scénu s PBR materiálem od nuly a uloží ji jako JSON glTF soubor.

import { Scene, Mesh, PbrMaterial, Vector4 } 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 osvědčené postupy

• Použijte ObjLoadOptions.enableMaterials = true kdykoli potřebujete materiálová data ze souborů .mtl. Bez toho bude seznam materiálů na každém uzlu prázdný.
• Upřednostněte binaryMode = true pro GLB při tvorbě aktiv pro webové nebo herní enginy. Binární GLB je jediný samostatný soubor a načítá se rychleji v prohlížečích a enginech než rozdělení JSON + .bin.
• Použijte openFromBuffer() v serverless prostředích aby se předešlo dočasnému souborovému I/O. Načtěte aktivum, předávejte Buffer přímo a zapište výstup do proudu nebo jiného bufferu.
• Zkontrolovat node.entity před přetypováním: ne všechny uzly nesou entitu. Vždy se chraňte pomocí instanceof zkontrolujte před přístupem Mesh-specifické vlastnosti, jako například controlPoints.
• Nastavit normalizeNormal = true v ObjLoadOptions když vaše zdrojové soubory OBJ pocházejí z nedůvěryhodných zdrojů. To zabraňuje šíření degenerovaných normál do následných kroků renderování nebo validace.
• Zachovat strict: true v tsconfig.json: knihovna je vytvořena s noImplicitAny a strictNullChecks. Zakázání strict maskuje skutečné typové chyby a podkopává hodnotu typovaného API.
• Procházejte pomocí childNodes, ne indexovou smyčkou: childNodes vlastnost vrací iterovatelný objekt; vyhněte se spoléhaní na číselné indexování pro budoucí kompatibilitu.

Běžné problémy

Často kladené otázky

Vyžaduje knihovna nějaké nativní doplňky nebo systémové balíčky? Ne. Aspose.3D FOSS pro TypeScript má jedinou runtime závislost: xmldom, což je čistý JavaScript a je instalováno automaticky pomocí npm. Neexistují žádné .node nativní doplňky ani systémové balíčky k instalaci.

Které verze Node.js jsou podporovány? Node.js 18, 20 a 22 LTS. Knihovna cílí na výstup CommonJS a interně používá jazykové funkce ES2020.

Mohu knihovnu použít v balíčku pro prohlížeč (webpack/esbuild)? Knihovna cílí na Node.js a používá Node.js fs a Buffer API. Balíčkování pro prohlížeč není oficiálně podporováno. Pro použití v prohlížeči načtěte scénu na serveru a výsledek (např. jako GLB) přeneste klientovi.

Jaký je rozdíl mezi GltfSaveOptions.binaryMode = true a false? binaryMode = false produkuje .gltf soubor JSON plus samostatný .bin binární bufferový sidecar. binaryMode = true produkuje jeden samostatný .glb soubor. Použijte true pro doručení produkčních aktiv.

Mohu načíst soubor z HTTP odpovědi, aniž bych jej uložil na disk? Ano. Načtěte odpověď jako Buffer (např. pomocí node-fetch nebo vestavěného fetch v Node 18+), pak zavolejte scene.openFromBuffer(buffer, options).

Je podpora FBX kompletní? Čtení a zápis FBX je podporován pro hierarchii scény, síťová a geometrická data, animační klipy a materiály. Velmi komplexní soubory FBX s vloženými médii mohou poskytovat částečné výsledky; vyzkoušejte s vaším konkrétním korpusem aktiv.

Podporuje knihovna TypeScript 4.x? Doporučuje se TypeScript 5.0+. TypeScript 4.7+ by měl v praxi fungovat, ale knihovna je testována a vyvíjena proti verzi 5.0+.

Shrnutí referenčního API