ویژگی‌های کلیدی Aspose.3D FOSS برای Java

در پست معرفی,، ما بررسی کردیم که Aspose.3D FOSS برای Java چیست و چگونه شروع کنیم. این پست عمیق‌تر به ویژگی‌های کلیدی که کتابخانه را تشکیل می‌دهند می‌پردازد، همراه با مثال‌های کد برای هر بخش.

تمام مثال‌ها فرض می‌کنند که وارد کردن زیر استفاده شده است:

import com.aspose.threed.*;

و وابستگی Maven:

<dependency>
    <groupId>com.aspose</groupId>
    <artifactId>aspose-3d-foss</artifactId>
    <version>26.1.0</version>
</dependency>

API گراف صحنه

گراف صحنه پایه Aspose.3D FOSS برای Java است. هر مدل 3D – چه از یک فایل بارگذاری شده باشد و چه به‌صورت برنامه‌نویسی ساخته شده – به‌صورت درختی از گره‌ها که ریشه در یک Scene شیء.

صحنه

این Scene کلاس نقطه ورود برای تمام عملیات است. می‌توانید یک صحنه خالی ایجاد کنید یا یکی را از یک فایل بارگذاری کنید:

// Empty scene
Scene scene = new Scene();

// Load from file
Scene loaded = Scene.fromFile("model.obj");

// Load with explicit options
Scene fromStl = Scene.fromFile("part.stl", new StlLoadOptions());

ریشه درخت گره‌ها از طریق getRootNode().

گره

یک Node نمایانگر یک موقعیت نام‌گذاری شده در درخت صحنه است. گره‌ها می‌توانند فرزندان داشته باشند و یک سلسله‌مراتب تشکیل می‌دهند. هر گره یک محلی Transform و یک محاسبه‌شده GlobalTransform.

Scene scene = new Scene();

// Create a child node under the root
Node box = scene.getRootNode().createChildNode("Box");

// Create a nested hierarchy
Node arm = scene.getRootNode().createChildNode("Arm");
Node hand = arm.createChildNode("Hand");
Node finger = hand.createChildNode("Finger");

همچنین می‌توانید گره‌ها را به‌صورت مستقل ساخته و بعداً به آن‌ها وصل کنید:

Node standalone = new Node("Standalone");
scene.getRootNode().getChildNodes().add(standalone);

Entity و Mesh

یک Entity یک کلاس پایهٔ انتزاعی برای هر چیزی است که می‌تواند به یک گره متصل شود – هندسه، دوربین‌ها و نورها. رایج‌ترین نوع موجودیت Mesh,، که هندسهٔ چندضلعی (رئوس، سطح‌ها و نرمال‌ها) را نگه می‌دارد.

Scene scene = Scene.fromFile("cube.obj");

// Traverse nodes and inspect entities
for (Node child : scene.getRootNode().getChildNodes()) {
    Entity entity = child.getEntity();
    if (entity instanceof Mesh) {
        Mesh mesh = (Mesh) entity;
        System.out.println("Node: " + child.getName());
        System.out.println("  Vertices: " + mesh.getControlPoints().size());
    }
}

دوربین

دوربین‌ها Entityهایی هستند که به گره‌ها متصل می‌شوند:

Scene scene = new Scene();

Node cameraNode = scene.getRootNode().createChildNode("MainCamera");
// Camera entity can be assigned to the node

توجه: کلاس Camera در نسخهٔ Java تنها یک استاب حداقل با سازنده‌ها است. موجودیت‌های دوربین متصل به گره‌ها نوشته نمی‌شوند هنگام خروجی‌گیری به glTF یا هر فرمت دیگری — خروجی‌گیر glTF فقط پردازش می‌کند Mesh موجودیت‌ها. به حفظ داده‌های دوربین در فایل‌های خروجی اعتماد نکنید.

توجه: این Light کلاس در نسخه Java موجود نیست. داده‌های نورپردازی صحنه از فایل‌های وارد شده به‌صورت عمومی Entity اشیاء.

بارگذاری و ذخیره‌سازی بدون وابستگی به فرمت

یکی از نقاط قوت کتابخانه این است که گراف صحنه مستقل از فرمت است. شما می‌توانید از هر فرمت پشتیبانی‌شده‌ای بارگذاری کنید، صحنه را از طریق یک API واحد دستکاری کنید و به هر فرمت پشتیبانی‌شده‌ای ذخیره کنید.

// Load OBJ, save as glTF
Scene scene = Scene.fromFile("input.obj");
scene.save("output.gltf");

// Load FBX, save as STL (FBX is import only)
Scene scene2 = Scene.fromFile("character.fbx");
scene2.save("character.stl");

// Load STL, save as GLB
Scene scene3 = Scene.fromFile("part.stl", new StlLoadOptions());
GltfSaveOptions opts = new GltfSaveOptions();
opts.setContentType(FileContentType.BINARY);
scene3.save("part.glb", opts);

فرمت توسط پسوند فایل تعیین می‌شود. همچنین می‌توانید گزینه‌های ذخیره‌سازی صریح را برای کنترل خروجی پاس دهید:

GltfSaveOptions opts = new GltfSaveOptions();
opts.setFlipCoordinateSystem(true);
opts.setPrettyPrint(true);

scene.save("output.gltf", opts);

متریال‌ها

Aspose.3D FOSS برای Java یک مدل ماده PBR (Physically Based Rendering) را از طریق PbrMaterial. این تنها کلاس مادهٔ ملموس در نسخه Java است.

PbrMaterial

یک متریال رندر مبتنی بر فیزیک که از پارامترهای آلوبدو، فلزی بودن و زبری استفاده می‌کند. این مدل متریال استاندارد برای glTF و موتورهای زمان واقعی مدرن است.

PbrMaterial pbr = new PbrMaterial();
pbr.setAlbedo(new Vector4(0.8, 0.2, 0.2, 1.0)); // Red-ish base color
pbr.setMetallicFactor(0.0);  // Non-metallic
pbr.setRoughnessFactor(0.5); // Medium roughness

حفظ متریال‌ها بین فرمت‌ها بستگی به قابلیت‌های فرمت هدف دارد. متریال‌های PBR به‌طور طبیعی به خروجی glTF و GLB نگاشت می‌شوند.

تبدیل و فضایی

هر Node در گراف صحنه یک Transform که موقعیت، چرخش و مقیاس آن را نسبت به والد تعریف می‌کند.

تبدیل محلی

Scene scene = new Scene();
Node node = scene.getRootNode().createChildNode("TestNode");

Transform t = node.getTransform();
t.setTranslation(1, 2, 3);       // Position
t.setScale(2, 2, 2);             // Uniform scale
t.setEulerAngles(0, 45, 0);      // Euler rotation in degrees

تبدیل سراسری

این GlobalTransform محول تبدیل فضای جهانی محاسبه‌شده است که زنجیره والدین کامل را در نظر می‌گیرد. این فقط‑خواندنی است و به‌صورت خودکار به‌روز می‌شود.

Node parent = scene.getRootNode().createChildNode("Parent");
parent.getTransform().setTranslation(10, 0, 0);

Node child = parent.createChildNode("Child");
child.getTransform().setTranslation(5, 0, 0);

// Child's global position is (15, 0, 0)
GlobalTransform global = child.getGlobalTransform();

این وراثت تبدیل والد‑فرزند الگوی استاندارد گراف صحنه‌ای است که توسط موتورهای 3D و ابزارهای DCC استفاده می‌شود.

ابزارهای ریاضی

این کتابخانه شامل انواع ریاضی اصلی برای عملیات‌های سه‌بعدی است.

Vector3

یک بردار سه‌جزئیه که برای موقعیت‌ها، جهت‌ها، نرمال‌ها و رنگ‌ها استفاده می‌شود.

Vector3 a = new Vector3(1, 0, 0);
Vector3 b = new Vector3(0, 1, 0);

// Addition
Vector3 sum = Vector3.add(a, b); // (1, 1, 0)

Matrix4

یک ماتریس تبدیل ۴×۴ برای ترکیب انتقال، چرخش و مقیاس در یک عملیات واحد.

Matrix4 mat = new Matrix4();
// Matrix4 is used internally by transforms
// and can be retrieved from GlobalTransform

Quaternion

یک نمایش چرخش که از قفل گیمبال جلوگیری می‌کند و به‌صورت صاف درون‌خطی می‌شود. Quaternionها به‌صورت داخلی توسط سیستم تبدیل استفاده می‌شوند.

BoundingBox

یک جعبه محدود‌کننده محور-محور برای پرس‌وجوهای فضایی، بررسی‌های برخورد و تحلیل صحنه.

BoundingBox bbox = new BoundingBox();
// BoundingBox can be constructed directly with min/max Vector3 values

توجه: Node.getBoundingBox() و Entity.getBoundingBox() هنوز پیاده‌سازی نشده‌اند. هر دو یک مقدار خالی برمی‌گردانند BoundingBox (با مقادیر پیش‌نشانگر Double.MAX_VALUE / Double.MIN_VALUE مقدارها) صرف‌نظر از هندسه مش. از این متدها برای محاسبه مرزهای واقعی هندسه در این نسخه استفاده نکنید.

محدودیت‌های شناخته‌شده

قابل ذکر است که Scene.render() است پشتیبانی نمی‌شود در نسخهٔ FOSS. فراخوانی آن یک UnsupportedOperationException. کتابخانه برای پردازش سه‌بعدی مبتنی بر فایل طراحی شده است – بارگذاری، تبدیل و ذخیره‌سازی – نه برای رندرینگ زمان واقعی.

خلاصه

ویژگی‌های کلیدی Aspose.3D FOSS برای Java به پنج حوزه تقسیم می‌شوند:

در پست بعدی، ما آموزش‌های عملی قالب به قالب را که شامل OBJ، STL، glTF و FBX هستند و گزینه‌های بارگذاری و ذخیره‌سازی دقیق را پوشش می‌دهند، مرور خواهیم کرد.