API Overview

API Overview — @aspose/3d for TypeScript

Пакет: @aspose/3d (v24.12.0) Язык: TypeScript / Node.js 18+ Лицензия: MIT

@aspose/3d это библиотека с лицензией MIT для чтения, построения и экспорта 3D‑сцен в Node.js. Она поставляется с полными определениями типов TypeScript, единственной runtime‑зависимостью (xmldom), и поддерживает семь основных форматов 3D‑файлов. Весь ввод/вывод синхронный. Нативные аддоны не требуются.

npm install @aspose/3d

tsconfig.json настройки для правильного разрешения под‑путей:

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

Основные классы

Корневой контейнер 3D‑сцены. Всё содержимое; узлы, геометрия, материалы и анимации; хранится в дереве, корнем которого является scene.rootNode.Используйте open() / openFromBuffer() для загрузки файла и save() / saveToBuffer() для экспорта.


`rootNode`	`Node`	Корень графа сцены
`assetInfo`	`AssetInfo`	Метаданные файла (создатель, единицы измерения, система координат)
`animationClips`	`AnimationClip[]`	Все анимационные клипы в сцене
`open(path, opts?)`	`(string, LoadOptions?) → void`	Загрузить файл с диска
`openFromBuffer(buf, opts?)`	`(Buffer, LoadOptions?) → void`	Загрузить из буфера в памяти
`save(path, opts?)`	`(string, SaveOptions?) → void`	Сохранить на диск (формат определяется по расширению)
`saveToBuffer(ext, opts?)`	`(string, SaveOptions?) → Buffer`	Сохранить в буфер в памяти
`createAnimationClip(name)`	`(string) → AnimationClip`	Создать и зарегистрировать новый анимационный клип

Именованный узел дерева в графе сцены. Узлы несут необязательный Entity (mesh, camera, light) и Transform который позиционирует узел относительно его родителя.


`name`	`string`	Имя узла
`childNodes`	`Node[]`	Прямые дочерние узлы
`entity`	`Entity	null`
`transform`	`Transform`	Локальное перемещение, вращение, масштаб
`materials`	`Material[]`	Материалы, назначенные этому узлу
`createChildNode(name)`	`(string) → Node`	Добавить дочерний узел
`getChildNode(name)`	`(string) → Node	null`

Полигональная сетка; основной тип геометрии. Расширяет Geometry.


`controlPoints`	`Vector4[]`	Позиции вершин (w=1 для позиций)
`polygonCount`	`number`	Количество полигонов
`createPolygon(indices)`	`(number[]) → void`	Добавить полигон (треугольник или четырёхугольник)
`getElement(type)`	`(VertexElementType) → VertexElement	null`
`createElement(type)`	`(VertexElementType) → VertexElement`	Создать элемент вершины

Локальное преобразование, применяемое к узлу.


`translation`	`Vector3`	Локальная позиция
`eulerAngles`	`Vector3`	Эйлерово вращение в градусах (порядок XYZ)
`rotation`	`Quaternion`	Вращение в виде кватерниона
`scaling`	`Vector3`	Локальный масштаб

Классы материалов

		Ключевые свойства
`LambertMaterial`	Диффузное + окружающее затенение	`diffuseColor`, `ambientColor`, `transparency`
`PhongMaterial`	Добавляет спекулярный + излучающий к Lambert	`specularColor`, `shininess`, `emissiveColor`
`PbrMaterial`	Физически основанный на glTF 2.0	`albedo`, `metallicFactor`, `roughnessFactor`, `emissiveColor`

Классы математики


`Vector3`	3-component double-precision vector (`x`, `y`, `z`)
`Vector4`	4-component vector for homogeneous math (`x`, `y`, `z`, `w`)
`FVector3`	Вариант одинарной точности, используемый в данных вершин
`Matrix4`	4×4 transformation matrix; `multiply`, `invert`, `decompose`
`Quaternion`	Кватернион вращения; `fromEulerAngle`, `toEulerAngles`, `slerp`
`BoundingBox`	Осиально-выравненный ограничивающий короб; `minimum`, `maximum`, `center`, `size`, `merge`

Классы анимации


`AnimationClip`	Именованный клип; содержит `AnimationNode` список; доступен через `scene.animationClips`
`AnimationNode`	Привязывает клип к именованному узлу сцены; содержит `AnimationChannel` список
`AnimationChannel`	Нацеливается на одно свойство (например, перемещение по X); содержит `KeyframeSequence`
`KeyframeSequence`	Упорядоченный список `KeyFrame` объекты с `interpolation` и `extrapolation`
`KeyFrame`	Одна пара время/значение


`VertexElementType`	`NORMAL`, `UV`, `VERTEX_COLOR`, `BINORMAL`, `TANGENT`	Семантика вершинного элемента
`MappingMode`	`CONTROL_POINT`, `POLYGON_VERTEX`, `POLYGON`, `ALL_SAME`	Как данные сопоставляются с геометрией
`ReferenceMode`	`DIRECT`, `INDEX`, `INDEX_TO_DIRECT`	Стратегия индексации данных вершинных элементов
`Interpolation`	`CONSTANT`, `LINEAR`, `BEZIER`	Интерполяция ключевых кадров
`Extrapolation`	`CONSTANT`, `GRADIENT`, `CYCLE`, `CYCLE_RELATIVE`, `OSCILLATE`	Поведение за пределами диапазона ключевых кадров

Модули форматов

Классы параметров, специфичных для формата, экспортируются из модулей подпутей. Импортируйте их отдельно:

import { ObjLoadOptions } from '@aspose/3d/formats/obj';
import { GltfSaveOptions, GltfFormat } from '@aspose/3d/formats/gltf';
import { StlLoadOptions, StlSaveOptions } from '@aspose/3d/formats/stl';
import { FbxLoadOptions, FbxSaveOptions } from '@aspose/3d/formats/fbx';
import { ColladaLoadOptions } from '@aspose/3d/formats/collada';
import { ThreeMfSaveOptions } from '@aspose/3d/formats/3mf';

Модуль OBJ (`@aspose/3d/formats/obj`)

	Ключевые параметры
`ObjLoadOptions`	`enableMaterials`, `flipCoordinateSystem`, `scale`, `normalizeNormal`

Модуль glTF/GLB (`@aspose/3d/formats/gltf`)

	Ключевые параметры
`GltfSaveOptions`	`binaryMode` (true → .glb), `flipTexCoordV`
`GltfFormat`	`GltfFormat.getInstance()`: экземпляр формата для `scene.save()`

Модуль STL (`@aspose/3d/formats/stl`)

	Параметры ключа
`StlLoadOptions`	N/A
`StlSaveOptions`	`binaryMode` (false → ASCII, true → binary)

Модуль FBX (`@aspose/3d/formats/fbx`)

	Ключевые параметры
`FbxLoadOptions`	N/A
`FbxSaveOptions`	`embedTextures`

Поддерживаемые форматы


	`.obj`
glTF 2.0	`.gltf`
	`.glb`
STL	`.stl`
FBX	`.fbx`	Нет*	Нет*
COLLADA	`.dae`
3MF	`.3mf`

Пример быстрого справочника

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

// Load OBJ with materials
const scene = new Scene();
const loadOpts = new ObjLoadOptions();
loadOpts.enableMaterials = true;
scene.open('input.obj', loadOpts);

// Inspect root nodes
for (const node of scene.rootNode.childNodes) {
    console.log(`Node: ${node.name}, entity: ${node.entity?.constructor.name}`);
}

// Export as GLB (binary glTF)
const saveOpts = new GltfSaveOptions();
saveOpts.binaryMode = true;
scene.save('output.glb', saveOpts);