Trabajando con el Grafo de Escena

Cada escena 3D en Aspose.3D para .NET está organizada como un árbol de Node objetos. Scene.RootNode es la raíz de ese árbol y cada pieza de geometría, material y transformación vive bajo ella como un hijo o descendiente.

Creando la Escena y Accediendo al Nodo Raíz

Scene se inicializa automáticamente con un nodo raíz llamado "RootNode":

using Aspose.ThreeD;

var scene = new Scene();
Node root = scene.RootNode; // always "RootNode"

Añadiendo Nodos Hijos

Llamar CreateChildNode() en cualquier nodo para añadir un hijo. El método tiene tres sobrecargas de uso común:

using Aspose.ThreeD;
using Aspose.ThreeD.Entities;

var scene = new Scene();
Node root = scene.RootNode;

// 1. Named node with no entity — useful as a pivot or transform container
Node pivot = root.CreateChildNode("pivot");

// 2. Named node with an entity
var box = new Box(2, 2, 2);
Node boxNode = root.CreateChildNode("box", box);

// 3. Named node with entity and material
var mat = new Aspose.ThreeD.Shading.PhongMaterial("red");
mat.Diffuse = new Vector4(0.8, 0.2, 0.2, 1.0);
Node decorated = pivot.CreateChildNode("red_box", box, mat);

Para adjuntar un nodo construido por separado, use AddChildNode():

var detached = new Node("standalone");
root.AddChildNode(detached);

Consultando Nodos Hijos

Encuentra un hijo directo por nombre o por índice, o itera todos los hijos directos:

// By name — returns null if no direct child has that name
Node? found = root.GetChild("box");
if (found != null)
    Console.WriteLine("Found: " + found.Name);

// By index
Node first = root.GetChild(0);

// Iterate all direct children
foreach (Node child in root.ChildNodes)
    Console.WriteLine(child.Name);

GetChild(string name) busca solo hijos directos, no todo el subárbol. Use un ayudante recursivo o Accept() para buscar en todo el árbol.

Recorriendo el Árbol Completo

Para un recorrido completo en profundidad, itere ChildNodes recursivamente:

static void Walk(Node node, int depth = 0)
{
    Console.WriteLine(new string(' ', depth * 2) + node.Name);
    foreach (var child in node.ChildNodes)
        Walk(child, depth + 1);
}

Walk(scene.RootNode);

Para un recorrido con salida anticipada, node.Accept(NodeVisitor) está disponible y llama al visitante en cada descendiente hasta que el visitante retorna false.

Usando Group para organizar objetos relacionados

Group es una entidad contenedora que organiza lógicamente los nodos sin añadir geometría. Adjúntela a un nodo cuyos hijos representan una unidad lógica:

using Aspose.ThreeD;
using Aspose.ThreeD.Entities;

var scene = new Scene();

// A group node for all furniture in a room
var furnitureGroup = new Group("furniture");
Node roomNode = scene.RootNode.CreateChildNode("living_room", furnitureGroup);

// Child nodes under the group node
Node sofaNode  = roomNode.CreateChildNode("sofa",         new Box(3, 1, 1));
Node tableNode = roomNode.CreateChildNode("coffee_table", new Box(2, 0.5, 1));

Mover roomNode transforma todos los muebles juntos porque los hijos heredan su Transform.

Controlando la Visibilidad y Exclusión de Exportación

Los nodos pueden ocultarse o excluirse de la exportación sin ser eliminados de la jerarquía:

Node ground = scene.RootNode.CreateChildNode("ground_plane", new Box(100, 0.1, 100));
ground.Visible = false;       // hidden in viewport / renderer

Node helperNode = scene.RootNode.CreateChildNode("debug_arrow", new Box());
helperNode.Excluded = true;   // omitted from all export operations

Visible = false es una pista de visualización. Excluded = true impide que el nodo aparezca en los archivos exportados sin importar el formato.

Adjuntar múltiples entidades a un nodo

Un nodo tiene un principal entidad (Entity propiedad), pero puede contener entidades adicionales a través de AddEntity(). Esto es útil cuando diferentes piezas de malla comparten una única transformación:

var bodyMesh  = new Mesh("body");
var wheelMesh = new Mesh("wheel");

Node carNode = scene.RootNode.CreateChildNode("car");
carNode.AddEntity(bodyMesh);
carNode.AddEntity(wheelMesh);

// Retrieve all entities on this node
foreach (Entity ent in carNode.Entities)
    Console.WriteLine(ent.GetType().Name + ": " + ent.Name);

Fusionar nodos

Merge() mueve todos los hijos, entidades y materiales de un nodo origen al nodo destino. El nodo origen queda vacío:

Node lod0 = scene.RootNode.CreateChildNode("lod0");
lod0.CreateChildNode("mesh_high", new Box(1, 1, 1));

Node lod1 = scene.RootNode.CreateChildNode("lod1");
lod1.CreateChildNode("mesh_low", new Box(1, 1, 1));

// Consolidate lod0 children into lod1
lod1.Merge(lod0);
// lod1 now has both mesh_high and mesh_low; lod0 is empty

Próximos pasos

Aplicando Transformaciones — posicionar, rotar y escalar cualquier nodo usando su Transform
Creando Geometría Primitiva — usar Box, Sphere, y Cylinder como entidades de escena
Creando y Trabajando con Mallas — crear geometría de polígono y adjuntarla a los nodos

Referencia rápida de la API

Miembro	Descripción
`scene.RootNode`	Raíz del árbol de escena; siempre presente después de `new Scene()`
`node.CreateChildNode(name)`	Crear un nodo hijo con nombre sin entidad
`node.CreateChildNode(name, entity)`	Crear un nodo hijo con nombre con una entidad
`node.CreateChildNode(name, entity, material)`	Crear un nodo hijo con nombre con entidad y material
`node.AddChildNode(node)`	Adjuntar una construida por separado `Node`
`node.GetChild(name)`	Buscar un hijo directo por nombre; devuelve `null` si no se encuentra
`node.GetChild(index)`	Obtener el hijo directo en un índice dado
`node.ChildNodes`	`IList<Node>` de todos los hijos directos
`node.Accept(visitor)`	Recorrer este nodo y todos sus descendientes en profundidad
`node.AddEntity(entity)`	Adjuntar una entidad adicional al nodo
`node.Entities`	`IList<Entity>` de todas las entidades en este nodo
`node.Visible`	Mostrar u ocultar el nodo
`node.Excluded`	Incluir o excluir el nodo de la exportación
`node.Merge(other)`	Mover todos los hijos y entidades de `other` a este nodo
`new Group(name)`	Entidad contenedora para agrupar lógicamente nodos hijos