Lavorare con il grafo della scena

Ogni scena 3D in Aspose.3D per Java è organizzata come un albero di Node oggetti. Scene fornisce una singola radice — getRootNode() — e ogni elemento di geometria, materiale e trasformazione vive sotto quella radice come nodo figlio o discendente.

Creare la scena e accedere al nodo radice

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

import com.aspose.threed.Scene;
import com.aspose.threed.Node;

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

Aggiungere nodi figlio

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

import com.aspose.threed.*;

Scene scene = new Scene();
Node root = scene.getRootNode();

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

// 2. Named node with an entity
Mesh mesh = new Mesh("box");
mesh.getControlPoints().add(new Vector4(0, 0, 0));
mesh.getControlPoints().add(new Vector4(1, 0, 0));
mesh.getControlPoints().add(new Vector4(1, 1, 0));
mesh.getControlPoints().add(new Vector4(0, 1, 0));
mesh.createPolygon(0, 1, 2, 3);
Node meshNode = root.createChildNode("box", mesh);

// 3. Named node with entity and material
PbrMaterial mat = new PbrMaterial("red");
mat.setAlbedo(new Vector4(0.8f, 0.2f, 0.2f, 1.0f));
Node decorated = pivot.createChildNode("red_box", mesh, mat);

Per collegare un nodo che è stato costruito separatamente, usa addChildNode():

Node 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) {
    System.out.println("Found: " + found.getName());
}

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

// Iterate all direct children
for (Node child : root.getChildNodes()) {
    System.out.println(child.getName());
}

getChild(String name) cerca solo i figli diretti, non l’intero sottoalbero. Usa accept() per cercare l’intero albero.

Attraversare l’albero completo

node.accept(NodeVisitor) attraversa un nodo e tutti i suoi discendenti in ordine depth-first. Il visitatore restituisce true per continuare o false per interrompere in anticipo:

import com.aspose.threed.NodeVisitor;

// Print every node name in the scene
scene.getRootNode().accept(n -> {
    System.out.println(n.getName());
    return true; // false would stop traversal
});

// Stop after finding the first node that has an entity
final Node[] found = {null};
scene.getRootNode().accept(n -> {
    if (n.getEntity() != null) {
        found[0] = n;
        return false; // stop walking
    }
    return true;
});

NodeVisitor è un’interfaccia a metodo singolo, quindi accetta una lambda in Java 8+.

Controllare la visibilità e l’esclusione dall’esportazione

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

Node ground = root.createChildNode("ground_plane", mesh);
ground.setVisible(false);       // hidden in viewport / renderer

Node helperNode = root.createChildNode("debug_arrow", mesh);
helperNode.setExcluded(true);   // omitted from all export operations

setVisible(false) è un suggerimento di visualizzazione. setExcluded(true) impedisce al nodo di apparire nei file esportati, indipendentemente dal formato.

Allegare più entità a un nodo

Un nodo ha un primario entity (getEntity() / setEntity()), ma può contenere entità aggiuntive tramite addEntity(). Questo è utile quando diversi pezzi di mesh condividono una singola trasformazione:

Mesh body  = new Mesh("body");
Mesh wheel = new Mesh("wheel");

Node carNode = root.createChildNode("car");
carNode.addEntity(body);
carNode.addEntity(wheel);

// Retrieve all entities on this node
for (Entity ent : carNode.getEntities()) {
    System.out.println(ent.getName());
}

Unire i nodi

merge() sposta tutti i figli, le entità e i materiali da un nodo sorgente al nodo di destinazione. Il nodo sorgente rimane vuoto:

Node lod0 = root.createChildNode("lod0");
lod0.createChildNode("mesh_high", mesh);

Node lod1 = root.createChildNode("lod1");
lod1.createChildNode("mesh_low", mesh);

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

Prossimi passi

Applicare le trasformazioni — posizionare, ruotare e scalare qualsiasi nodo usando il suo Transform
Creare e lavorare con le mesh — costruire geometria poligonale e collegarla ai nodi

Riferimento rapido API

Membro	Descrizione
`scene.getRootNode()`	Radice dell’albero della scena; sempre presente dopo `new Scene()`
`node.createChildNode(name)`	Crea un nodo figlio con nome senza entità
`node.createChildNode(name, entity)`	Crea un nodo figlio con nome con un’entità
`node.createChildNode(name, entity, material)`	Crea un nodo figlio con nome 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 indice specificato
`node.getChildNodes()`	`List<Node>` di tutti i figli diretti
`node.accept(visitor)`	Visita questo nodo e tutti i discendenti in profondità
`node.addEntity(entity)`	Allega un’entità aggiuntiva al nodo
`node.getEntities()`	`List<Entity>` di tutte le entità su questo nodo
`node.setVisible(bool)`	Mostra o nascondi il nodo
`node.setExcluded(bool)`	Includi o escludi il nodo dall’esportazione
`node.merge(other)`	Sposta tutti i figli e le entità da `other` in questo nodo