Lavorare con il grafo della scena

Ogni scena 3D in Aspose.3D per .NET è organizzata come un albero di Node oggetti. Scene.RootNode è la radice di quell’albero e ogni elemento di geometria, materiale e trasformazione vive sotto di essa come figlio o discendente.

Creare la scena e accedere al nodo radice

Scene si inizializza automaticamente con un nodo radice chiamato "RootNode":

using Aspose.ThreeD;

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

Aggiungere nodi figlio

Call CreateChildNode() su qualsiasi nodo per aggiungere un figlio. Il metodo ha tre overload comunemente usati:

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

Per collegare un nodo costruito separatamente, usa AddChildNode():

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

Interrogare i nodi figlio

Trova un figlio diretto per nome o per indice, oppure itera tutti i figli diretti:

// 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) cerca solo i figli diretti, non l’intero sottoalbero. Usa un helper ricorsivo o Accept() per cercare l’intero albero.

Attraversare l’albero completo

Per un’attraversamento completo in profondità, itera ChildNodes ricorsivamente:

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

Per un’attraversamento con uscita anticipata, node.Accept(NodeVisitor) è disponibile e chiama il visitor su ogni discendente finché il visitor restituisce false.

Usare Group per organizzare oggetti correlati

Group è un’entità contenitore che organizza logicamente i nodi senza aggiungere geometria. Collegala a un nodo i cui figli rappresentano un’unità logica:

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

Spostamento roomNode trasforma tutti i mobili insieme perché i figli ereditano il suo Transform.

Controllare la visibilità e l’esclusione dall’esportazione

I nodi possono essere nascosti o esclusi dall’esportazione senza essere rimossi dalla gerarchia:

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 è un suggerimento di visualizzazione. Excluded = true impedisce al nodo di apparire nei file esportati indipendentemente dal formato.

Allegare più entità a un nodo

Un node ha un primary entity (Entity property), ma può contenere entità aggiuntive tramite AddEntity(). Questo è utile quando diversi pezzi di mesh condividono una singola transform:

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

Unire i nodi

Merge() sposta tutti i children, le entities e i materials da un source node al target node. Il source node rimane vuoto:

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

Prossimi passi

Applying Transforms — position, rotate e scale any node using its Transform
Creating Primitive Geometry — use Box, Sphere, and Cylinder as scene entities
Creating and Working with Meshes — build polygon geometry e attach it to nodes

Riferimento rapido API

Member	Descrizione
`scene.RootNode`	Radice dell’albero della scena; sempre presente dopo `new Scene()`
`node.CreateChildNode(name)`	Crea un nodo figlio denominato senza entità
`node.CreateChildNode(name, entity)`	Crea un nodo figlio denominato con un’entità
`node.CreateChildNode(name, entity, material)`	Crea un nodo figlio denominato con entità e materiale
`node.AddChildNode(node)`	Allega un elemento costruito separatamente `Node`
`node.GetChild(name)`	Trova un figlio diretto per nome; restituisce `null` se non trovato
`node.GetChild(index)`	Ottieni il figlio diretto a un dato indice
`node.ChildNodes`	`IList<Node>` di tutti i figli diretti
`node.Accept(visitor)`	Percorri questo nodo e tutti i discendenti in profondità (depth‑first)
`node.AddEntity(entity)`	Allega un’entità aggiuntiva al nodo
`node.Entities`	`IList<Entity>` di tutte le entità su questo nodo
`node.Visible`	Mostra o nascondi il nodo
`node.Excluded`	Includi o escludi il nodo dall’esportazione
`node.Merge(other)`	Sposta tutti i figli e le entità da `other` in questo nodo
`new Group(name)`	Entità contenitore per raggruppare logicamente i nodi figli