Características e funcionalidades

Aspose.3D FOSS para TypeScript é uma biblioteca Node.js licenciada pelo MIT para carregamento, construção e exportação de cenas 3D. Ele vem com definições completas do tipo Type Script, uma dependência única no tempo de execução (xmldomEsta página é a referência principal para todas as áreas de recursos e inclui exemplos de código TypeScript executáveis para cada um.

Instalação e configuração

Instalar o pacote a partir do npm usando um único comando:

O pacote é direcionado para o CommonJS e requer Node.js 18 ou posterior. Após a instalação, verifique seu código de segurança em Windows XP. tsconfig.json Inclui as seguintes opções de compilador para a total compatibilidade:

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

Importar o principal Scene classes de opção específicas do formato são importadas a partir dos respectivos subcaminhos:

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

Características e funcionalidades

Suporte de formato

Aspose.3D FOSS para TypeScript lê e escreve seis formatos de arquivo 3D principais. A detecção de formato é automática a partir dos números mágicos binários ao carregar, então você não precisa especificar o formato fonte explicitamente.

Carregamento do OBJ com materiais:

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

A poupança para GLB (glTF binário):

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

Gráfico de cena

Todo o conteúdo 3D é organizado como uma árvore de Node objetos enraizados em: scene.rootNode.Cada nó pode transportar um Entity (a) Mesh, Camera, Light, ou outros SceneObject) e a) Transform que a posiciona em relação ao seu pai.

Classes de gráficos-cenas principais:

• Scene: o recipiente de nível superior; contém: rootNode e a) animationClips
• Node: um nó de árvore com nome childNodes, entity, transform, e materials
• Entity: classe de base para objetos acopláveis (Mesh, Camera, Light)
• SceneObject:Classe de base: partilhada por: Node e a) Entity
• A3DObject:Classe de base raiz com: name e saco de propriedade.
• Transform:- tradução local, rotação (Euler e Quaternion) e escala;

A atravessar o gráfico da cena:

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

Criando uma hierarquia de cenas programaticamente:

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

Geometria e malha

Mesh é o tipo de geometria primária. Geometry e expõe pontos de controle (vertices), índices de polígonos, e elementos do vértice para normais, UVs e cores dos vértebras.

Classe de geometria:

• Mesh: malha de polígonos com: controlPoints e a) polygonCount
• Geometry: classe base com gestão de elementos verticais
• VertexElementNormal: normais por vértice ou por polígono-vértice
• VertexElementUV: coordenadas de textura (um ou mais canais UV)
• VertexElementVertexColor: dados de cor por vértice
• MappingMode: controla como os dados dos elementos são mapeados para polígonos (CONTROL_POINT, POLYGON_VERTEX, POLYGON, EDGE, ALL_SAME)
• ReferenceMode: controlo da estratégia de indexação (DIRECT, INDEX, INDEX_TO_DIRECT)
• VertexElementType: identifica a semântica de um elemento vertebral.
• TextureMapping: enumeração do canal de textura

Leitura de dados em malha numa cena carregada:

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

Sistema de materiais

O Aspose.3D FOSS para TypeScript suporta três tipos de material que cobrem toda a gama, desde o legado Phong shading até renderização física:

• LambertMaterial: cor difusa e cor ambiente; mapas para materiais OBJ/DAE simples
• PhongMaterial: adiciona cor especular, brilho e emissão; o tipo de material OBJ padrão
• PbrMaterial: modelo de rugosidade/metálico com base física; utilizado para importação e exportação glTF 2.0

Matérias de leitura de uma cena OBJ carregada:

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

Aplicação de um material PBR na construção da cena 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);

Utilidades de Matemática

A biblioteca fornece um conjunto completo de tipos matemáticos 3D, todos completamente digitados:

• Vector3:Vector de três componentes; suporte minus(), times(), dot(), cross(), normalize(), length, angleBetween()
• Vector4: Vector de quatro componentes para coordenadas homogéneas
• Matrix4: Matriz de transformação 4×4 com: concatenate(), transpose, decompose, setTRS
• Quaternion: quaternio de rotação com: fromEulerAngle() (estático, singular), eulerAngles() (método de instância), slerp(), normalize()
• BoundingBox: caixa de contorno alinhada ao eixo com: minimum, maximum, center, size, merge
• FVector3:Variante de uma só vez: Vector3 utilizado em dados de elementos vertebrais

Computação de uma caixa delimitadora a partir dos vértices da malha:

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

Construir uma transformação a partir de ângulos de Euler:

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

Sistema de animação

A API de animação modela clips, nós, canais e sequências de keyframes:

• AnimationClip: coleção nomeada de nós de animação; acessado via scene.animationClips;expõe; animations: AnimationNode[]
• AnimationNode: grupo de nomeados BindPoints; criado através de: clip.createAnimationNode(name), acessado através de: clip.animations
• BindPoint: liga um AnimationNode a uma propriedade específica num objeto de cena; expõe property e a) channelsCount
• AnimationChannel: estende-se a: KeyframeSequence;O Conselho Europeu de Essen, em 15 de Março. keyframeSequence; acessado através de: bindPoint.getChannel(name)
• KeyFrame: um único par de tempo/valor; carrega por quadro-chave. interpolation: Interpolation
• KeyframeSequence:Lista ordenada de: KeyFrame objetos via keyFrames;, tem preBehavior e a) postBehavior (Extrapolation)
• Interpolation:- Não .: LINEAR, CONSTANT, BEZIER, B_SPLINE, CARDINAL_SPLINE, TCB_SPLINE
• Extrapolation:Classe com: type: ExtrapolationType e a) repeatCount: number
• ExtrapolationType:- Não .: CONSTANT, GRADIENT, CYCLE, CYCLE_RELATIVE, OSCILLATE

Leitura de dados de animação de uma cena carregada:

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

Suporte de fluxo e buffer

Utilização: scene.openFromBuffer() para carregar uma cena 3D diretamente de um in-memory Buffer.Este é o padrão recomendado para funções sem servidor, pipelines de streaming e ativos de processamento obtidos por HTTP sem escrever no disco.

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

A detecção automática de formato a partir dos números mágicos binários se aplica ao carregamento do buffer, então os arquivos GLB, STL binário e 3MF são reconhecidos sem especificar um parâmetro de formatar.

Exemplos de uso

Exemplo 1: Carga OBJ e exportação para GLB

Este exemplo carrega um arquivo Wavefront OBJ com materiais, em seguida re-exporta a cena como um ficheiro glTF (GLB) binário adequado para uso na web e no motor de jogos.

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

Exemplo 2: STL de ida e volta com validação normal

Este exemplo carrega um arquivo STL binário, imprime informações normais por vértice e depois reexporta a cena como ASCII ST L e verifica o regresso.

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

Exemplo 3: Criar uma cena programaticamente e salvar como glTF

Este exemplo constrói uma cena com um material PBR a partir do zero e salva-o como um arquivo 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');

Dicas e melhores práticas

• Utilização: ObjLoadOptions.enableMaterials = true Sem ele, a lista de materiais em cada nó será vazia.
• Preferência binaryMode = true para o GLB quando produzem ativos para motores de web ou jogos. O GLB binário é um único arquivo autocontido e carrega mais rápido em navegadores e mecanismos do que o JSON + .bin split.
• Utilização: openFromBuffer() em ambientes sem servidor Para evitar arquivos temporários de entrada/saída. Traga o activo, passa-lhe a informação do agente da navegação. Buffer diretamente, e escrever a saída para um fluxo ou outro buffer.
• Verificação node.entity antes da fundição: nem todos os nós carregam uma entidade. Sempre guardar com um instanceof Verificar antes de aceder. Mesh- propriedades específicas, tais como: controlPoints.
• Set (s) normalizeNormal = true em: ObjLoadOptions Isto impede que os normais degenerados se propaguem para as etapas de renderização ou validação a jusante.
• Mantém-no. strict: true em tsconfig.json: a biblioteca é composta por: noImplicitAny e a) strictNullChecks.Desativação . strict mascara erros reais de tipo e derrota o valor da API digitada.
• Via de travessão childNodes, não um ciclo de índice:O: childNodes Propriedade retorna uma iteração; evitar confiar na indexação numérica para a compatibilidade com o futuro.

Problemas comuns

Perguntas Frequentes

A biblioteca requer algum addon nativo ou pacotes de sistema? Não. Aspose.3D FOSS para TypeScript tem uma única dependência de tempo de execução: xmldom, que é JavaScript puro e instalado automaticamente por npm. Não há nenhum .node Addon nativos e nenhum pacote de sistema para instalar.

Quais versões do Node.js são suportadas? Node.js 18, 20, and 22 LTS. The library targets CommonJS output and uses ES2020 language features internally.

Posso usar a biblioteca num pacote de navegador (webpack/esbuild)? A biblioteca tem como alvo o Node.js e usa o fs e a) Buffer APIs. O agrupamento do navegador não é oficialmente suportado. Para uso no navegador, carregue a cena do lado do servidor e transmita o resultado (por exemplo, como GLB) ao cliente.

Qual é a diferença entre: GltfSaveOptions.binaryMode = true e a) false? binaryMode = false produz uma .gltf Arquivo JSON mais um separado .bin sidecar de tampão binário. binaryMode = true produz uma única unidade de produção autónoma, que é a mesma do produto. .glb Arquivo. true para a entrega de activos de produção.

Posso carregar um arquivo de uma resposta HTTP sem salvá-lo para o disco? Sim, traga a resposta como um “A” para o seu cliente. Buffer (por exemplo, utilizando o método de cálculo do valor da node-fetch ou o sistema integrado. fetch em Nodo 18+), depois chamar scene.openFromBuffer(buffer, options).

O suporte do FBX está completo? Não. Existem classes FBX importador e exportador na biblioteca, mas o FBx não está conectado a ela Scene.open() ou a) Scene.save() - Auto-detecção. scene.open('file.fbx') Não invocará o importador FBX; o arquivo será tratado pelo caminho de reserva STL. Use diretamente as classes de importadores/exportadores específicas do FBx se precisar de I/O FB X. Veja a tabela de suporte ao formato acima, que marca o FB x como No*.

A biblioteca suporta o TypeScript 4.x? TypeScript 5.0+ é recomendado. Type Script 4.7+ deve funcionar na prática, mas a biblioteca é testada e escrita contra o 5.0.

Resumo de referência da API

Ver também:

• Aspose.3D para TypeScript Documentação Empresarial