Функции и възможности

Aspose.3D FOSS за TypeScript е библиотека за Node.js с лиценз MIT, предназначена за зареждане, конструиране и експортиране на 3D сцени. Тя се доставя с пълни TypeScript типови дефиниции, една единствена runtime зависимост (xmldom).

Инсталиране и настройка

Инсталирайте пакета от npm с една команда:

npm install @aspose/3d

Пакетът е насочен към CommonJS и изисква Node.js 18 или по-нов. След инсталацията проверете вашия tsconfig.json включва следните компилаторни опции за пълна съвместимост:

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

Импортирайте главния Scene клас от корена на пакета. Класовете с опции, специфични за формат, се импортират от съответните под‑пътища:

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

Функции и възможности

Поддръжка на формати

Aspose.3D FOSS for TypeScript чете и записва шест основни 3D файлови формати. Откриването на формата е автоматично въз основа на бинарните магически числа при зареждане, така че не е необходимо изрично да посочвате изходния формат.

Зареждане на OBJ с материали:

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

Записване в GLB (бинарен 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);

Граф на сцената

Цялото 3D съдържание е организирано като дърво от Node обекти, чиито корен е в scene.rootNode. Всеки възел може да съдържа Entity (а Mesh, Camera, Light, или друг SceneObject) и Transform което го позиционира относно неговия родител.

Ключови класове на графа на сцената:

• Scene: контейнер от най-високо ниво; съдържа rootNode и animationClips
• Node: именуван възел в дървото с childNodes, entity, transform, и materials
• Entity: базов клас за прикрепяеми обекти (Mesh, Camera, Light)
• SceneObject: базов клас, споделен от Node и Entity
• A3DObject: коренов базов клас с name и контейнер за свойства
• Transform: локално транслация, ротация (Euler и Quaternion) и мащаб

Обхождане на графа на сцената:

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

Създаване на йерархия на сцената програмно:

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

Геометрия и Mesh

Mesh е основният тип геометрия. Той разширява Geometry и предоставя контролни точки (върхове), индекси на полигони и елементи на върховете за нормали, UV координати и цветове на върховете.

Ключови класове за геометрия:

• Mesh: полигонна мрежа с controlPoints и polygonCount
• Geometry: базов клас с управление на елементите на върховете
• VertexElementNormal: нормали за всеки връх или за всеки полигон‑връх
• VertexElementUV: текстурни координати (един или повече UV канала)
• VertexElementVertexColor: данни за цвят по връх
• MappingMode: контролира как данните на елементите се съпоставят с полигоните (ByControlPoint, ByPolygonVertex, и т.н.)
• ReferenceMode: контролира стратегията за индексиране (Direct, IndexToDirect)
• VertexElementType: идентифицира семантиката на елемент от връх
• TextureMapping: изброяване на текстурните канали

Четене на данни за мрежа от заредена сцена:

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

Система за материали

Aspose.3D FOSS за TypeScript поддържа три типа материали, обхващащи целия спектър от наследен Phong сенчест ефект до физически базирано рендериране:

• LambertMaterial: дифузен цвят и околен цвят; съответства на прости OBJ/DAE материали
• PhongMaterial: добавя спекуларен цвят, блясък и емисивност; стандартният тип материал за OBJ
• PbrMaterial: физически базиран модел за грубост/металност; използва се за импортиране и експортиране на glTF 2.0

Четене на материали от заредена 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)}`);
    }
  }
}

Прилагане на PBR материал при създаване на glTF сцена:

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

Математически помощни функции

Библиотеката се доставя с пълен набор от 3D математически типове, всички напълно типизирани:

• Vector3: вектор с 3 компонента; поддържа add, subtract, scale, dot, cross, normalize, length
• Vector4: вектор с 4 компонента за хомогенни координати
• Matrix4: 4×4 матрица за трансформация с multiply, invert, transpose, decompose
• Quaternion: кватернион за ротация с fromEulerAngles, toEulerAngles, slerp, normalize
• BoundingBox: axis-aligned bounding box с min, max, center, size, merge
• FVector3: вариант с единична точност на Vector3 използва се в данни за върхови елементи

Изчисляване на ограничителна кутия от върховете на мрежата:

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

Създаване на трансформация от ъгли на Юлер:

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

Система за анимация

API‑то за анимация моделира клипове, възли, канали и последователности от ключови кадри:

• AnimationClip: именована колекция от анимационни възли; достъпва се чрез scene.animationClips
• AnimationNode: свързва клип към сценичен възел по име
• AnimationChannel: насочва към конкретно свойство (например транслация X) в анимационен възел
• KeyFrame: единична двойка време/стойност
• KeyframeSequence: подреден списък от KeyFrame обекти с Interpolation и Extrapolation настройки
• Interpolation: режим на интерполация на ключов кадър: Linear, Constant, Cubic
• Extrapolation: поведение преди/след диапазона на ключовите кадри: Constant, Cycle, Mirror

Четене на анимационни данни от заредена сцена:

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

Поддръжка на потоци и буфери

Използвайте scene.openFromBuffer() за зареждане на 3D сцена директно от памет Buffer. Това е препоръчаният модел за безсървърни функции, поточни конвейери и обработка на активи, извлечени чрез HTTP, без записване на диск.

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

Автоматичното разпознаване на формата от бинарни магически числа се прилага при зареждане от буфер, така че файловете GLB, STL binary и 3MF се разпознават без задаване на параметър за формат.

Примери за употреба

Пример 1: Зареждане на OBJ и експортиране към GLB

Този пример зарежда Wavefront OBJ файл с материали, след което отново експортира сцената като бинарен glTF (GLB) файл, подходящ за уеб и игрови енджини.

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

Пример 2: Пълен цикъл на STL с проверка на нормалите

Този пример зарежда бинарен STL файл, извежда информация за нормалите за всеки връх, след което отново експортира сцената като ASCII STL и проверява пълния цикъл.

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

Пример 3: Програмено създаване на сцена и запазване като glTF

Този пример създава сцена с PBR материал от нулата и я запазва като JSON glTF файл.

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

Съвети и най-добри практики

• Използвайте ObjLoadOptions.enableMaterials = true винаги когато се нуждаете от данни за материалите от .mtl файлове. Без това, списъкът с материали за всеки възел ще бъде празен.
• Предпочитайте binaryMode = true за GLB при създаване на активи за уеб или игрови енджини. Бинарният GLB е един самостоятелен файл и се зарежда по-бързо в браузъри и енджини, отколкото разделеният JSON + .bin.
• Използвайте openFromBuffer() в безсървърни среди за да избегнете временен файлов I/O. Изтеглете актива, предайте Buffer директно и запишете изхода в поток или друг буфер.
• Провери node.entity преди преобразуване: не всички възли носят entity. Винаги предпазвайте с instanceof проверка преди достъп Mesh-специфични свойства като controlPoints.
• Задай normalizeNormal = true в ObjLoadOptions когато вашите изходни OBJ файлове идват от недоверени източници. Това предотвратява разпространението на дегенеративни нормали в последващи етапи на рендериране или валидиране.
• Запази strict: true в tsconfig.json: библиотеката е създадена с noImplicitAny и strictNullChecks. Деактивирането strict маскира реалните типови грешки и подкопава стойността на типизирания API.
• Обхождай чрез childNodes, а не индексен цикъл:този childNodes свойството връща итерируем обект; избягвайте да разчитате на числова индексация за бъдеща съвместимост.

Чести проблеми

Често задавани въпроси

Изисква ли библиотеката някакви native addons или системни пакети? Не. Aspose.3D FOSS за TypeScript има единствена runtime зависимост: xmldom, което е чист JavaScript и се инсталира автоматично чрез npm. Няма .node native addons и няма системни пакети за инсталиране.

Кои версии на Node.js се поддържат? Node.js 18, 20 и 22 LTS. Библиотеката е насочена към CommonJS изход и използва езикови функции ES2020 вътрешно.

Мога ли да използвам библиотеката в браузърен пакет (webpack/esbuild)? Библиотеката е насочена към Node.js и използва Node.js fs и Buffer API-та. Браузърното пакетиране не се поддържа официално. За използване в браузър, заредете сцената от сървъра и предайте резултата (например като GLB) на клиента.

Каква е разликата между GltfSaveOptions.binaryMode = true и false? binaryMode = false произвежда .gltf JSON файл плюс отделен .bin двоичен буфер sidecar. binaryMode = true произвежда един единствен самостоятелен .glb файл. Използвайте true за доставка на продукционни активи.

Мога ли да заредя файл от HTTP отговор без да го запазвам на диск? Да. Изтеглете отговора като Buffer (например, използвайки node-fetch или вграденото fetch в Node 18+), след което извикайте scene.openFromBuffer(buffer, options).

Поддръжката на FBX е пълна? Четенето и записването на FBX се поддържат за йерархия на сцената, мрежи и геометрични данни, анимационни клипове и материали. Много сложни FBX файлове с вграден медия материал могат да дадат частични резултати; тествайте с вашия конкретен набор от активи.

Поддържа ли библиотеката TypeScript 4.x? Препоръчва се TypeScript 5.0+. TypeScript 4.7+ трябва да работи на практика, но библиотеката е тествана и разработена спрямо 5.0+.

Обобщение на API справката