Trabajando con el Grafo de Escena

Cada escena 3D en Aspose.3D para Java está organizada como un árbol de Node objetos. Scene proporciona una única raíz — getRootNode() — y cada pieza de geometría, material y transformación vive bajo esa raíz como un nodo hijo o descendiente.

Creando la Escena y Accediendo al Nodo Raíz

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

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

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

Añadiendo Nodos Hijos

Call createChildNode() en cualquier nodo para agregar un hijo. El método tiene tres sobrecargas de uso común:

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

Para adjuntar un nodo que fue construido por separado, use addChildNode():

Node 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) {
    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) busca solo hijos directos, no todo el subárbol. Use accept() para buscar en todo el árbol.

Recorriendo el Árbol Completo

node.accept(NodeVisitor) recorre un nodo y todos sus descendientes en orden de profundidad primero. El visitante devuelve true para continuar o false para detenerse temprano:

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 es una interfaz de un solo método, por lo que acepta una lambda en Java 8+.

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 = 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) es una pista de visualización. setExcluded(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 (getEntity() / setEntity()), pero puede contener entidades adicionales a través de addEntity(). Esto es útil cuando diferentes piezas de malla comparten una única transformación:

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

Fusionar nodos

merge() mueve todos los hijos, entidades y materiales de un nodo fuente al nodo objetivo. El nodo fuente queda vacío:

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

Próximos pasos

Aplicando Transformaciones — posicionar, rotar y escalar cualquier nodo usando su Transform
Crear y trabajar con mallas — construir geometría poligonal y adjuntarla a nodos

Referencia rápida de la API

Miembro	Descripción
`scene.getRootNode()`	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, entidad y material
`node.addChildNode(node)`	Adjuntar un construido 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.getChildNodes()`	`List<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.getEntities()`	`List<Entity>` de todas las entidades en este nodo
`node.setVisible(bool)`	Mostrar u ocultar el nodo
`node.setExcluded(bool)`	Incluir o excluir el nodo de la exportación
`node.merge(other)`	Mueve todos los hijos y entidades de `other` en este nodo