Arbejde med scenegrafen

Hver 3D-scene i Aspose.3D for Java er organiseret som et træ af Node objekter. Scene leverer en enkelt rod — getRootNode() — og hvert stykke geometri, materiale og transformation lever under den rod som et barn‑ eller efterkommernode.

Oprettelse af scenen og adgang til rotnoden

Scene initialiseres automatisk med en rodnode ved navn "RootNode":

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

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

Tilføjelse af underknuder

Kald createChildNode() på en hvilken som helst node for at tilføje et barn. Metoden har tre almindeligt brugte overloads:

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

For at vedhæfte en node, der blev konstrueret separat, brug addChildNode():

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

Forespørgsel på underknuder

Find en direkte undernode efter navn eller indeks, eller iterer over alle direkte underknuder:

// 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) søger kun direkte børn, ikke hele undertræet. Brug accept() for at søge i hele træet.

Gennemløb af hele træet

node.accept(NodeVisitor) går igennem en node og alle dens efterkommere i dybde‑først rækkefølge. Besøgeren returnerer true for at fortsætte eller false for at stoppe tidligt:

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 er et enkelt‑metode interface, så det accepterer en lambda i Java 8+.

Styring af synlighed og eksklusion ved eksport

Noder kan skjules eller udelukkes fra eksport uden at blive fjernet fra hierarkiet:

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) er et visningshint. setExcluded(true) forhindrer noden i at vises i eksporterede filer uanset format.

Tilknytning af flere entiteter til én node

En node har en primær enhed (getEntity() / setEntity()), men kan indeholde yderligere enheder gennem addEntity(). Dette er nyttigt, når forskellige mesh‑stykker deler en enkelt transformation:

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

Fletning af noder

merge() flytter alle børn, enheder og materialer fra en kilde‑node til mål‑node. Kilde‑node forbliver tom:

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æste trin

Anvendelse af transformationer — positionere, rotere og skalere enhver node ved hjælp af dens Transform
Oprettelse og arbejde med mesh‑objekter — opbyg polygongeometri og vedhæft den til noder

API‑hurtigreference

Medlem	Beskrivelse
`scene.getRootNode()`	Roden af scenetræet; altid til stede efter `new Scene()`
`node.createChildNode(name)`	Opret en navngivet undernode uden enhed
`node.createChildNode(name, entity)`	Opret en navngivet undernode med en enhed
`node.createChildNode(name, entity, material)`	Opret en navngivet undernode med enhed og materiale
`node.addChildNode(node)`	Vedhæft en separat konstrueret `Node`
`node.getChild(name)`	Find et direkte barn efter navn; returnerer `null` hvis ikke fundet
`node.getChild(index)`	Hent det direkte barn ved et givet indeks
`node.getChildNodes()`	`List<Node>` af alle direkte børn
`node.accept(visitor)`	Gå igennem denne node og alle efterkommere i dybde‑først rækkefølge
`node.addEntity(entity)`	Tilføj en ekstra enhed til noden
`node.getEntities()`	`List<Entity>` af alle enheder på denne node
`node.setVisible(bool)`	Vis eller skjul noden
`node.setExcluded(bool)`	Inkluder eller ekskluder noden fra eksport
`node.merge(other)`	Flyt alle underordnede og enheder fra `other` ind i denne node