API Overview

API Overview — @aspose/3d for TypeScript

Pacote: @aspose/3d (v24.12.0) Linguagem: TypeScript / Node.js 18+ Licença: MIT

@aspose/3d é uma biblioteca licenciada sob MIT para leitura, construção e exportação de cenas 3D no Node.js. Ela vem com definições de tipo TypeScript completas, uma única dependência de tempo de execução (xmldom), e suporta sete principais formatos de arquivo 3D. Todas as I/O são síncronas. Nenhum addon nativo é necessário.

npm install @aspose/3d

tsconfig.json configurações para resolução correta de subcaminhos:

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

Classes Principais

O contêiner raiz para uma cena 3D. Todo o conteúdo; nós, geometria, materiais e animações; é armazenado em uma árvore enraizada em scene.rootNode.Use open() / openFromBuffer() para carregar um arquivo e save() / saveToBuffer() para exportar.


`rootNode`	`Node`	Raiz do grafo de cena
`assetInfo`	`AssetInfo`	Metadados do arquivo (criador, unidades, sistema de coordenadas)
`animationClips`	`AnimationClip[]`	Todas as sequências de animação na cena
`open(path, opts?)`	`(string, LoadOptions?) → void`	Carregar um arquivo do disco
`openFromBuffer(buf, opts?)`	`(Buffer, LoadOptions?) → void`	Carregar de um buffer em memória
`save(path, opts?)`	`(string, SaveOptions?) → void`	Salvar no disco (formato inferido da extensão)
`saveToBuffer(ext, opts?)`	`(string, SaveOptions?) → Buffer`	Salvar em buffer em memória
`createAnimationClip(name)`	`(string) → AnimationClip`	Criar e registrar uma nova sequência de animação

Um nó de árvore nomeado no grafo de cena. Nós carregam um opcional Entity (malha, câmera, luz) e um Transform que posiciona o nó em relação ao seu pai.


`name`	`string`	Nome do nó
`childNodes`	`Node[]`	Nós filhos diretos
`entity`	`Entity	null`
`transform`	`Transform`	Translação, rotação e escala locais
`materials`	`Material[]`	Materiais atribuídos a este nó
`createChildNode(name)`	`(string) → Node`	Adicionar um nó filho
`getChildNode(name)`	`(string) → Node	null`

Malha poligonal; o tipo de geometria principal. Estende Geometry.


`controlPoints`	`Vector4[]`	Posicoes dos vértices (w=1 para posições)
`polygonCount`	`number`	Número de polígonos
`createPolygon(indices)`	`(number[]) → void`	Adicionar um polígono (triângulo ou quad)
`getElement(type)`	`(VertexElementType) → VertexElement	null`
`createElement(type)`	`(VertexElementType) → VertexElement`	Criar um elemento de vértice

Transformação local aplicada a um nó.


`translation`	`Vector3`	Posição local
`eulerAngles`	`Vector3`	Rotação Euler em graus (ordem XYZ)
`rotation`	`Quaternion`	Rotação como um quaternion
`scaling`	`Vector3`	Escala local

Classes de Material

		Propriedades principais
`LambertMaterial`	Sombras difusa + ambiente	`diffuseColor`, `ambientColor`, `transparency`
`PhongMaterial`	Adiciona especular + emissivo ao Lambert	`specularColor`, `shininess`, `emissiveColor`
`PbrMaterial`	Baseado em física para glTF 2.0	`albedo`, `metallicFactor`, `roughnessFactor`, `emissiveColor`

Classes de Matemática


`Vector3`	3-component double-precision vector (`x`, `y`, `z`)
`Vector4`	4-component vector for homogeneous math (`x`, `y`, `z`, `w`)
`FVector3`	Variante de precisão simples usada em dados de vértice
`Matrix4`	4×4 transformation matrix; `multiply`, `invert`, `decompose`
`Quaternion`	Quatérnio de rotação; `fromEulerAngle`, `toEulerAngles`, `slerp`
`BoundingBox`	Caixa delimitadora alinhada aos eixos; `minimum`, `maximum`, `center`, `size`, `merge`

Classes de Animação


`AnimationClip`	Clipe nomeado; contém `AnimationNode` lista; acessada via `scene.animationClips`
`AnimationNode`	Associa um clipe a um nó de cena nomeado; contém `AnimationChannel` lista
`AnimationChannel`	Alvo de uma única propriedade (ex.: translação X); contém um `KeyframeSequence`
`KeyframeSequence`	Lista ordenada de `KeyFrame` objetos com `interpolation` e `extrapolation`
`KeyFrame`	Par único de tempo/valor


`VertexElementType`	`NORMAL`, `UV`, `VERTEX_COLOR`, `BINORMAL`, `TANGENT`	Semântica do elemento de vértice
`MappingMode`	`CONTROL_POINT`, `POLYGON_VERTEX`, `POLYGON`, `ALL_SAME`	Como os dados são mapeados para a geometria
`ReferenceMode`	`DIRECT`, `INDEX`, `INDEX_TO_DIRECT`	Estratégia de indexação para dados de elemento de vértice
`Interpolation`	`CONSTANT`, `LINEAR`, `BEZIER`	Interpolação de quadros‑chave
`Extrapolation`	`CONSTANT`, `GRADIENT`, `CYCLE`, `CYCLE_RELATIVE`, `OSCILLATE`	Comportamento fora do intervalo de quadros‑chave

Módulos de Formato

Classes de opções específicas de formato são exportadas a partir de módulos de subcaminho. Importe-as separadamente:

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

Módulo OBJ (`@aspose/3d/formats/obj`)

	Opções chave
`ObjLoadOptions`	`enableMaterials`, `flipCoordinateSystem`, `scale`, `normalizeNormal`

Módulo glTF/GLB (`@aspose/3d/formats/gltf`)

	Opções chave
`GltfSaveOptions`	`binaryMode` (true → .glb), `flipTexCoordV`
`GltfFormat`	`GltfFormat.getInstance()`:instância de formato para `scene.save()`

Módulo STL (`@aspose/3d/formats/stl`)

	Opções-chave
`StlLoadOptions`	N/A
`StlSaveOptions`	`binaryMode` (false → ASCII, true → binário)

Módulo FBX (`@aspose/3d/formats/fbx`)

	Opções-chave
`FbxLoadOptions`	N/A
`FbxSaveOptions`	`embedTextures`

Formatos suportados


	`.obj`
glTF 2.0	`.gltf`
	`.glb`
STL	`.stl`
FBX	`.fbx`	Não*	Não*
COLLADA	`.dae`
3MF	`.3mf`

Exemplo de referência rápida

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