Arbeiten mit dem Szenengraph

Jede 3D‑Szene in Aspose.3D für Java ist als Baum von Node Objekten. Scene bietet eine einzige Wurzel — getRootNode() — und jedes Stück Geometrie, Material und Transform befindet sich unter dieser Wurzel als Kind‑ oder Nachfolgerknoten.

Erstellen der Szene und Zugriff auf den Wurzelknoten

Scene initialisiert sich automatisch mit einem Wurzelknoten namens "RootNode":

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

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

Hinzufügen von Kindknoten

Call createChildNode() auf einem beliebigen Knoten, um ein Kind hinzuzufügen. Die Methode hat drei häufig verwendete Überladungen:

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

Um einen separat konstruierten Knoten anzuhängen, verwenden Sie addChildNode():

Node detached = new Node("standalone");
root.addChildNode(detached);

Abfragen von Kindknoten

Finden Sie ein direktes Kind nach Name oder Index, oder iterieren Sie über alle direkten Kinder:

// 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) sucht nur direkte Kinder, nicht den gesamten Unterbaum. Verwenden accept() um den gesamten Baum zu durchsuchen.

Durchlaufen des gesamten Baums

node.accept(NodeVisitor) durchläuft einen Knoten und alle seine Nachkommen in Tiefensuche. Der Besucher gibt zurück true um fortzusetzen oder false um frühzeitig zu stoppen:

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 ist ein Single-Method-Interface, daher akzeptiert es ein Lambda in Java 8+.

Steuerung der Sichtbarkeit und des Exports‑Ausschlusses

Knoten können ausgeblendet oder vom Export ausgeschlossen werden, ohne aus der Hierarchie entfernt zu werden:

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) ist ein Anzeigehinweis. setExcluded(true) verhindert, dass der Knoten in exportierten Dateien erscheint, unabhängig vom Format.

Mehrere Entitäten an einem Knoten anhängen

Ein Knoten hat ein primäres Entität (getEntity() / setEntity()), kann jedoch zusätzliche Entitäten über addEntity(). Dies ist nützlich, wenn verschiedene Mesh‑Teile eine einzige Transformation teilen:

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

Knoten zusammenführen

merge() verschiebt alle Kinder, Entitäten und Materialien von einem Quellknoten in den Zielknoten. Der Quellknoten bleibt leer:

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

Nächste Schritte

Transformationen anwenden — positionieren, rotieren und skalieren Sie jeden Knoten mit seiner Transform
Erstellen und Arbeiten mit Meshes — Polygongeometrie erstellen und an Knoten anhängen

API‑Kurzreferenz

Mitglied	Beschreibung
`scene.getRootNode()`	Wurzel des Szenenbaums; immer vorhanden nach `new Scene()`
`node.createChildNode(name)`	Erstelle einen benannten Kindknoten ohne Entität
`node.createChildNode(name, entity)`	Erstelle einen benannten Kindknoten mit einer Entität
`node.createChildNode(name, entity, material)`	Erstelle einen benannten Kindknoten mit entity und material
`node.addChildNode(node)`	Füge ein separat konstruiertes an `Node`
`node.getChild(name)`	Finde ein direktes Kind nach Namen; gibt zurück `null` falls nicht gefunden
`node.getChild(index)`	Erhalte das direkte Kind an einem angegebenen Index
`node.getChildNodes()`	`List<Node>` von allen direkten Kindern
`node.accept(visitor)`	Durchlaufe diesen Knoten und alle Nachkommen in Tiefensuche
`node.addEntity(entity)`	Füge dem Knoten ein zusätzliches entity hinzu
`node.getEntities()`	`List<Entity>` von allen entities auf diesem Knoten
`node.setVisible(bool)`	Zeige oder verberge den Knoten
`node.setExcluded(bool)`	Schließe den Knoten in den Export ein oder aus
`node.merge(other)`	Verschiebe alle Kinder und Entitäten von `other` in diesen Knoten