کار با گراف صحنه

کار با گراف صحنه

هر صحنهٔ 3D در Aspose.3D برای Java به صورت یک درخت از Node اشیاء. Scene یک ریشهٔ واحد فراهم می‌کند — getRootNode() — و هر قطعهٔ هندسه، ماده و تبدیل زیر آن ریشه به عنوان گرهٔ فرزند یا نوادگان زندگی می‌کند.


ایجاد صحنه و دسترسی به گرهٔ ریشه

Scene به‌صورت خودکار با یک گرهٔ ریشه به نام "RootNode":

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

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

افزودن گره‌های فرزند

Call createChildNode() روی هر گره‌ای برای افزودن یک فرزند فراخوانی می‌شود. این متد سه overload معمولاً استفاده‌شده دارد:

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

برای الصاق گره‌ای که به‌صورت جداگانه ساخته شده است، از addChildNode():

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

پرس‌و‌جوی گره‌های فرزند

یک فرزند مستقیم را بر اساس نام یا ایندکس پیدا کنید، یا تمام فرزندان مستقیم را پیمایش کنید:

// 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) فقط جستجو می‌کند فرزندان مستقیم,، نه تمام زیر درخت. استفاده کنید accept() برای جستجوی کل درخت.


پیمایش کل درخت

node.accept(NodeVisitor) یک گره و تمام نوادگان آن را به ترتیب عمق‑اول می‌پیماید. بازدیدکننده برمی‌گرداند true برای ادامه یا false برای توقف زودهنگام:

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 یک رابط تک‑متد است، بنابراین یک لامبدا در Java 8+ می‌پذیرد.


کنترل قابلیت مشاهده و استثنا از خروجی

گره‌ها می‌توانند بدون حذف از سلسله‌مراتب، مخفی یا از خروجی حذف شوند:

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) یک راهنمای نمایش است. setExcluded(true) از ظاهر شدن گره در فایل‌های صادر شده صرف‌نظر از قالب جلوگیری می‌کند.


پیوست کردن چندین موجودیت به یک گره

یک گره دارای یک اصلی موجودیت (getEntity() / setEntity()), اما می‌تواند موجودیت‌های اضافی را از طریق addEntity(). این مفید است وقتی قطعات مش مختلف یک تبدیل واحد را به اشتراک می‌گذارند:

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

ادغام گره‌ها

merge() تمام فرزندان، موجودیت‌ها و مواد را از یک گره منبع به گره هدف منتقل می‌کند. گره منبع خالی می‌ماند:

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

مراحل بعدی


مرجع سریع API

عضوتوضیح
scene.getRootNode()ریشهٔ درخت صحنه؛ همیشه پس از آن موجود است new Scene()
node.createChildNode(name)یک گره فرزند نام‌دار بدون entity ایجاد کنید
node.createChildNode(name, entity)یک گره فرزند نام‌دار با یک entity ایجاد کنید
node.createChildNode(name, entity, material)یک گره فرزند نام‌دار با entity و material ایجاد کنید
node.addChildNode(node)یک مورد جداگانه ساخته شده را متصل کنید Node
node.getChild(name)یک فرزند مستقیم را بر اساس نام پیدا کنید؛ باز می‌گرداند null اگر یافت نشد
node.getChild(index)فرزند مستقیم را در ایندکس داده شده دریافت کنید
node.getChildNodes()List<Node> از تمام فرزندان مستقیم
node.accept(visitor)این گره و تمام نوادگان آن را به صورت عمق‌اول پیمایش کنید
node.addEntity(entity)یک موجودیت اضافی را به گره پیوست کنید
node.getEntities()List<Entity> از تمام موجودیت‌های موجود در این گره
node.setVisible(bool)نمایش یا مخفی‌سازی گره
node.setExcluded(bool)شامل یا حذف گره از خروجی
node.merge(other)انتقال تمام فرزندان و موجودیت‌ها از other به این گره
 فارسی