Como percorrer um grafo de cena 3D em TypeScript

O grafo de cena no Aspose.3D FOSS para TypeScript é uma árvore de objetos Node com raiz em scene.rootNode. A travessia é recursiva: cada nó expõe um iterável childNodes e uma propriedade opcional entity. Este guia mostra como percorrer toda a árvore, identificar tipos de entidade e coletar estatísticas de malhas.

Pré-requisitos

• Node.js 18 ou posterior
• TypeScript 5.0 ou posterior
• @aspose/3d instalado

Guia passo a passo

npm install @aspose/3d

import { Scene } from '@aspose/3d';
import { ObjLoadOptions } from '@aspose/3d/formats/obj';
import { Mesh } from '@aspose/3d/entities';

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

const scene = new Scene();
scene.open('model.obj', new ObjLoadOptions());

console.log(`Root node: "${scene.rootNode.name}"`);
console.log(`Top-level children: ${scene.rootNode.childNodes.length}`);

function traverse(node: any, depth = 0): void {
    const indent = '  '.repeat(depth);
    const entityType = node.entity ? node.entity.constructor.name : '-';
    console.log(`${indent}[${entityType}] ${node.name}`);
    for (const child of node.childNodes) {
        traverse(child, depth + 1);
    }
}

traverse(scene.rootNode);

[-] RootNode
  [Mesh] Cube

<div class="copy-icon group-[.copied]/copybtn:hx-hidden hx-pointer-events-none hx-h-4 hx-w-4"></div>
<div class="success-icon hx-hidden group-[.copied]/copybtn:hx-block hx-pointer-events-none hx-h-4 hx-w-4"></div>

import { Mesh } from '@aspose/3d/entities';

function visitWithTypeCheck(node: any, depth = 0): void {
    const indent = '  '.repeat(depth);
    if (node.entity instanceof Mesh) {
        const mesh = node.entity as Mesh;
        console.log(`${indent}MESH "${node.name}": ${mesh.controlPoints.length} vertices`);
    } else if (node.entity) {
        console.log(`${indent}${node.entity.constructor.name} "${node.name}"`);
    } else {
        console.log(`${indent}GROUP "${node.name}"`);
    }
    for (const child of node.childNodes) {
        visitWithTypeCheck(child, depth + 1);
    }
}

visitWithTypeCheck(scene.rootNode);

import { Mesh } from '@aspose/3d/entities';

function collectMeshes(
    node: any,
    results: Array<{ name: string; mesh: Mesh }> = []
): Array<{ name: string; mesh: Mesh }> {
    if (node.entity instanceof Mesh) {
        results.push({ name: node.name, mesh: node.entity as Mesh });
    }
    for (const child of node.childNodes) {
        collectMeshes(child, results);
    }
    return results;
}

const meshNodes = collectMeshes(scene.rootNode);
console.log(`Found ${meshNodes.length} mesh node(s)`);

import { Scene } from '@aspose/3d';
import { ObjLoadOptions } from '@aspose/3d/formats/obj';
import { Mesh } from '@aspose/3d/entities';

function collectMeshes(node: any, results: Array<{name: string, mesh: Mesh}> = []) {
    if (node.entity instanceof Mesh) {
        results.push({ name: node.name, mesh: node.entity as Mesh });
    }
    for (const child of node.childNodes) {
        collectMeshes(child, results);
    }
    return results;
}

const scene = new Scene();
scene.open('model.obj', new ObjLoadOptions());

const meshes = collectMeshes(scene.rootNode);
for (const { name, mesh } of meshes) {
    console.log(`${name}: ${mesh.controlPoints.length} vertices, ${mesh.polygonCount} polygons`);
}

Cube: 8 vertices, 6 polygons
Sphere: 482 vertices, 480 polygons

<div class="copy-icon group-[.copied]/copybtn:hx-hidden hx-pointer-events-none hx-h-4 hx-w-4"></div>
<div class="success-icon hx-hidden group-[.copied]/copybtn:hx-block hx-pointer-events-none hx-h-4 hx-w-4"></div>

Dicas e Melhores Práticas

• Sempre verifique null em node.entity antes de acessar propriedades específicas da entidade. Muitos nós são nós de grupo puros que não carregam nenhuma entidade.
• Use instanceof em vez de constructor.name para verificações de tipo em caminhos de lógica. instanceof é seguro para refatoração; a comparação de strings em constructor.name quebra com a minificação.
• Percorra com for...of em childNodes: o iterável lida com todos os tamanhos de array com segurança. Evite indexação numérica para compatibilidade futura.
• Evite mutar a árvore durante a travessia: não adicione ou remova nós dentro da chamada recursiva. Colete os resultados primeiro e depois modifique.
• Passe um array de resultados como parâmetro: isso evita alocar um novo array em cada chamada recursiva e facilita a mesclagem de resultados de subárvores.

Problemas Comuns

Perguntas Frequentes

scene.rootNode em si carrega uma entidade? Não. O nó raiz é um contêiner criado automaticamente pela biblioteca. Ele não tem entidade. Sua geometria e outros objetos de cena vivem em nós filhos um ou mais níveis abaixo de rootNode.

Qual é a diferença entre node.entity e node.entities? node.entity contém a única entidade primária (o caso comum). Alguns arquivos FBX e COLLADA mais antigos podem produzir nós com múltiplas entidades anexadas; nesse caso node.entities (plural) fornece a lista completa.

Posso percorrer em ordem de largura em vez de profundidade? Sim. Use uma fila em vez de uma chamada recursiva: empurre scene.rootNode para um array, depois extraia e processe os nós enquanto empurra os childNodes de cada nó para o final da fila.

scene.open() é síncrono? Sim. scene.open() e scene.openFromBuffer() ambos bloqueiam a thread chamante até que o arquivo seja totalmente analisado. Envolva-os em uma thread de trabalho se você precisar manter o loop de eventos responsivo.

Como obter posições no espaço mundial de um nó? Leia node.globalTransform; ele retorna um GlobalTransform somente leitura com a matriz no espaço mundial, composta a partir de todas as transformações ancestrais. Para operações matemáticas de matriz explícitas, chame node.evaluateGlobalTransform(false).

Quais tipos de entidade são possíveis além de Mesh? Camera, Light e entidades de esqueleto/osso personalizadas. Verifique node.entity.constructor.name ou use instanceof com a classe específica importada de @aspose/3d.

Veja Também

• Como carregar modelos 3D em TypeScript
• Como construir uma malha 3D programaticamente em TypeScript
• Guia do desenvolvedor: Grafo de cena
• npm: @aspose/3d