العمل مع صيغ ملفات 3D في Java باستخدام Aspose.3D FOSS

Aspose.3D FOSS لـ Java يدعم خمسة صيغ ملفات ثلاثية الأبعاد: OBJ, STL, glTF, GLB,، و FBX (استيراد فقط).

جميع الأمثلة تستخدم com.aspose.threed.* الحزمة:

import com.aspose.threed.*;

اعتماد Maven:

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

منظور الصيغ

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

تدعم OBJ و STL و glTF و GLB كلًا من الاستيراد والتصدير. يتم دعم FBX لـ الاستيراد فقط. يتم إنتاج GLB (binary glTF) عبر GltfSaveOptions مع setContentType(FileContentType.BINARY).

OBJ: Wavefront Object

OBJ هو أحد أكثر صيغ الشبكات ثلاثية الأبعاد دعمًا. يخزن الهندسة كنص عادي، مع خيار اختياري .mtl ملف مرفق للمواد.

تحميل ملفات OBJ

أبسط طريقة هي تمرير مسار الملف مباشرةً:

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

للمزيد من التحكم، استخدم ObjLoadOptions:

ObjLoadOptions opts = new ObjLoadOptions();
Scene scene = Scene.fromFile("model.obj", opts);

عند إشارة ملف OBJ إلى ملف MTL (عبر mtllib التوجيه)، ستحاول المكتبة تحميل تعريفات المواد منه تلقائيًا. يجب أن يكون ملف MTL في نفس الدليل الذي يوجد فيه ملف OBJ أو في المسار المحدد في التوجيه.

حفظ كـ OBJ

Scene scene = Scene.fromFile("input.fbx");
scene.save("output.obj");

حالات استخدام OBJ

• تبادل بيانات الشبكة بين أدوات ثلاثية الأبعاد مختلفة.
• استيراد النماذج من مكتبات الأصول التي توزع بصيغة OBJ.
• فحص سريع للجيومتري دون هياكل مشهد معقدة.

STL: سيتيروليثوغرافي

STL هو الصيغة القياسية للطباعة ثلاثية الأبعاد. يمثل جيومتريًا مثلثيًا خامًا دون مواد أو ألوان أو هيكل مشهد. ملفات STL تأتي بنوعين: ASCII (قابل للقراءة البشرية) و binary (مضغوط).

تحميل ملفات STL

// Simple load
Scene scene = Scene.fromFile("part.stl");

// With explicit options
StlLoadOptions opts = new StlLoadOptions();
Scene scene = Scene.fromFile("part.stl", opts);

حفظ كـ STL

Scene scene = Scene.fromFile("model.obj");
scene.save("output.stl");

للتحكم في الإخراج، استخدم StlSaveOptions:

StlSaveOptions opts = new StlSaveOptions();
scene.save("output.stl", opts);

اعتبارات STL

• STL يخزن فقط جيومتري المثلثات. المواد والملمسيات وهيكل المشهد غير مدعومة وتُحذف عند التصدير.
• تصدير STL يقوم بـ ليس Binary STL يكتب فقط الثلاث رؤوس الأولى لكل وجه من مضلع؛ يتم قطع الوجوه رباعية الأضلاع و n‑gon بصمت. ASCII STL يكتب جميع مؤشرات الرؤوس لكل وجه، مما ينتج إخراجًا مشوّهًا للوجوه غير المثلثية. استخدم دائمًا شبكات مُثَلَّثَة مسبقًا (وجوه مثلثية بالكامل) عند التصدير إلى STL.
• Binary STL أصغر حجمًا بشكل ملحوظ من ASCII STL للنماذج الكبيرة.
• STL هو الصيغة المفضلة عندما يكون الهدف طابعة ثلاثية الأبعاد أو برنامج تقطيع.

glTF: تنسيق نقل GL

glTF هو صيغة حديثة صُممت لنقل وتحميل محتوى ثلاثي الأبعاد بكفاءة، خاصة على الويب وفي التطبيقات الفورية. يدعم مواد PBR، وهياكل المشهد، والرسوم المتحركة.

تحميل ملفات glTF

Scene scene = Scene.fromFile("scene.gltf");

// With options
GltfLoadOptions opts = new GltfLoadOptions();
Scene scene = Scene.fromFile("scene.gltf", opts);

حفظ كـ glTF

يستخدم الحفظ الأساسي امتداد الملف لتحديد الصيغة:

scene.save("output.gltf");

لتحكم مفصل، استخدم GltfSaveOptions:

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

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

تفاصيل GltfSaveOptions

حالات استخدام glTF

• عارضات 3D على الويب (three.js، Babylon.js).
• تطبيقات الوقت الحقيقي ومحركات الألعاب.
• الحفاظ على تعريفات المواد PBR عبر الأدوات.

FBX: Filmbox (استيراد فقط)

FBX هو تنسيق مملوك من Autodesk يُستخدم على نطاق واسع في تطوير الألعاب وإنشاء المحتوى الرقمي. Aspose. يدعم 3D FOSS لـ Java تنسيق FBX لـ استيراد فقط — التصدير إلى FBX غير متوفر.

Binary FBX فقط. يقوم مستورد FBX بقراءة ملفات Binary FBX فقط. تمرير ملف ASCII FBX يؤدي إلى ImportException("ASCII FBX format not yet supported - only binary FBX is supported"). هيكل العقد واستخراج المواد من FBX غير مُتحقق منه بالكامل؛ قد لا يتم تحميل مشاهد FBX المعقدة بالكامل. الرسوم المتحركة والتركيب العظمي غير مُنفّذة.

تحميل ملفات FBX

Scene scene = Scene.fromFile("character.fbx");

// With options
FbxLoadOptions opts = new FbxLoadOptions();
Scene scene = Scene.fromFile("character.fbx", opts);

تحويل FBX إلى صيغ أخرى

نظرًا لعدم دعم تصدير FBX، قم بتحويل مشاهد FBX المستوردة إلى glTF أو GLB أو OBJ أو STL:

Scene scene = Scene.fromFile("character.fbx");

// Save as GLB
GltfSaveOptions opts = new GltfSaveOptions();
opts.setContentType(FileContentType.BINARY);
scene.save("character.glb", opts);

حالات استخدام FBX

• استيراد أصول الشبكة الساكنة من أدوات Autodesk (Maya، 3ds Max) وتحويلها إلى صيغ أخرى.
• تحميل هندسة FBX الثنائية وإعادة تصديرها إلى glTF/GLB أو OBJ أو STL.

تحويل دفعي

سير عمل شائع هو تحويل دليل كامل من الملفات من صيغة إلى أخرى. إليك نمط للتحويل الدفعي:

import com.aspose.threed.*;
import java.io.File;

public class BatchConvert {
    public static void main(String[] args) throws Exception {
        File inputDir = new File("models/obj");
        File outputDir = new File("models/gltf");
        outputDir.mkdirs();

        GltfSaveOptions saveOpts = new GltfSaveOptions();
        saveOpts.setPrettyPrint(true);

        File[] objFiles = inputDir.listFiles(
            (dir, name) -> name.toLowerCase().endsWith(".obj")
        );

        if (objFiles == null) return;

        for (File objFile : objFiles) {
            String baseName = objFile.getName()
                .replaceFirst("\\.obj$", "");

            Scene scene = Scene.fromFile(objFile.getAbsolutePath());
            String outPath = new File(outputDir, baseName + ".gltf")
                .getAbsolutePath();

            scene.save(outPath, saveOpts);
            System.out.println("Converted: " + objFile.getName()
                + " -> " + baseName + ".gltf");
        }
    }
}

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

مرجع التحويل عبر الصيغ

الجدول التالي يوضح ما يمكن توقعه عند التحويل بين الصيغ.

إرشادات التحويل العامة

• الهندسة عادةً ما يتم الحفاظ على الهندسة عبر أزواج الصيغ، مع استثناء مهم واحد: عند التصدير إلى STL، يجب أن تتكون الشبكات بالكامل من وجوه مثلثية. يقوم Binary STL بقص وجوه الـ quad والـ n‑gon صامتًا إلى أول 3 رؤوس لها؛ بينما ينتج ASCII STL مخرجات مشوهة للوجوه غير المثلثية.
• المواد تُحافظ على أفضل حال بين مشاهد glTF ومشاهد FBX المستوردة التي تتضمن بيانات المواد. التحويل إلى STL يزيل المواد دائمًا. التحويل إلى OBJ يبسط المواد إلى نموذج MTL الأساسي.
• هيكلية المشهد يتم الحفاظ عليها بين ملفات بصيغة glTF. ينتج OBJ و STL هياكل مسطحة. لم يتم التحقق بالكامل من هيكلية FBX واستخراج المواد في هذا الإصدار.

تجميع كل شيء معًا

إليك مثال كامل يقوم بتحميل ملف OBJ، يفحص عقده، ويصدّر إلى كل من glTF و GLB:

import com.aspose.threed.*;

public class FormatWorkflow {
    public static void main(String[] args) throws Exception {
        // Load
        Scene scene = Scene.fromFile("input.obj");

        // Inspect
        System.out.println("Nodes in scene:");
        for (Node child : scene.getRootNode().getChildNodes()) {
            System.out.println("  " + child.getName());
            Transform t = child.getTransform();
            System.out.println("    Translation: "
                + t.getTranslation());
        }

        // Export to glTF with options
        GltfSaveOptions gltfOpts = new GltfSaveOptions();
        gltfOpts.setPrettyPrint(true);
        scene.save("output.gltf", gltfOpts);

        // Export to GLB (binary glTF)
        GltfSaveOptions glbOpts = new GltfSaveOptions();
        glbOpts.setContentType(FileContentType.BINARY);
        scene.save("output.glb", glbOpts);

        System.out.println("Export complete.");
    }
}

ملخص

Aspose.3D FOSS for Java يمنحك واجهة برمجة تطبيقات متسقة عبر صيغ متعددة. النقاط الرئيسية:

• OBJ – تبادل شبكات بسيط مع مواد أساسية.
• STL – تنسيق يقتصر على الهندسة لسلاسل طباعة ثلاثية الأبعاد.
• glTF / GLB – تنسيق حديث يدعم PBR للاستخدام على الويب وفي الوقت الفعلي. استخدم GltfSaveOptions مع setContentType(FileContentType.BINARY) لإخراج GLB.
• FBX – استيراد فقط؛ تنسيق غني لتحميل الأصول من محركات الألعاب وأدوات DCC.

استخدم فئات خيارات التحميل والحفظ الخاصة بالتنسيق (ObjLoadOptions, StlLoadOptions, StlSaveOptions, GltfLoadOptions, GltfSaveOptions, FbxLoadOptions) عندما تحتاج إلى تحكم دقيق في عملية الاستيراد أو التصدير.

لمزيد من التفاصيل، زر وثائق Aspose.3D أو تصفح المصدر على GitHub.