الميزات الرئيسية لـ 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>

واجهة برمجة تطبيقات رسم المشهد

مخطط المشهد هو الأساس لـ Aspose.3D FOSS لـ Java. كل نموذج ثلاثي الأبعاد – سواء تم تحميله من ملف أو تم بناؤه برمجياً – يُمثَّل كشجرة من العقد الجذرية في 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);

الكيان و 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());
    }
}

الكاميرا

الكاميرات هي كيانات تُرفق بالعقد:

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 كائنات.

تحميل وحفظ غير معتمد على الصيغة

إحدى نقاط القوة في المكتبة هي أن مخطط المشهد غير معتمد على الصيغة. يمكنك التحميل من أي صيغة مدعومة، تعديل المشهد عبر واجهة برمجة تطبيقات واحدة، ثم الحفظ إلى أي صيغة مدعومة.

// 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

مادة تعتمد على الإضاءة الفيزيائية وتستخدم معلمات albedo و metalness و roughness. هذا هو نموذج المادة القياسي لـ 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

مصفوفة تحويل 4×4 لدمج الإزاحة، الدوران، والقياس في عملية واحدة.

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

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 مع خيارات تحميل وحفظ مفصلة.