کار با فرمت‌های فایل 3D در Java با استفاده از Aspose.3D FOSS

Aspose.3D FOSS برای Java از پنج فرمت فایل 3D پشتیبانی می‌کند: 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

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

• تبادل داده‌های مش بین ابزارهای مختلف 3D.
• وارد کردن مدل‌ها از کتابخانه‌های دارایی که در قالب 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 نمی‌کند به‌صورت خودکار مثلث‌بندی نمی‌کند. STL باینری فقط سه راس اول هر سطح چندضلعی را می‌نویسد؛ سطوح چهارضلعی و n‑گون به‌صورت ساکن کوتاه می‌شوند. STL متنی تمام ایندکس‌های راس را برای هر سطح می‌نویسد و برای سطوح غیرمثلثی خروجی خراب تولید می‌کند. همیشه هنگام خروجی به STL از مش‌های پیش‌مثلث‌بندی‌شده (تمام سطوح مثلثی) استفاده کنید.
• STL باینری برای مدل‌های بزرگ به‌مرات کوچکتر از STL ASCII است.
• STL فرمت مورد ترجیح است وقتی هدف یک چاپگر سه‌بعدی یا نرم‌افزار برش (slicer) باشد.

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 در دسترس نیست.

فقط FBX باینری. واردکننده FBX فقط فایل‌های FBX باینری را می‌خواند. ارسال یک فایل FBX ASCII باعث بروز 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، مش‌ها باید کاملاً از سطوح مثلثی تشکیل شوند. STL باینری به‌صورت ساکن چهره‌های چهارضلعی و n‑gon را به سه راس اولشان کوتاه می‌کند؛ STL ASCII خروجی خراب برای چهره‌های غیر‑مثلثی تولید می‌کند.
• متریال‌ها به‌طور بهترین بین صحنه‌های وارد شده از 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 برای Java یک API سازگار در چندین فرمت به شما می‌دهد. نکات کلیدی:

• OBJ – تبادل مش ساده با متریال‌های پایه.
• STL – فرمت فقط هندسی برای خطوط لوله چاپ سه‌بعدی.
• glTF / GLB – فرمت مدرن سازگار با PBR برای استفاده در وب و زمان واقعی. استفاده کنید GltfSaveOptions با setContentType(FileContentType.BINARY) برای خروجی GLB.
• FBX – فقط برای وارد کردن؛ فرمت غنی برای بارگذاری دارایی‌ها از موتورهای بازی و ابزارهای DCC.

از کلاس‌های گزینه بارگذاری و ذخیره‌سازی مخصوص فرمت استفاده کنید (ObjLoadOptions, StlLoadOptions, StlSaveOptions, GltfLoadOptions, GltfSaveOptions, FbxLoadOptions).

برای جزئیات بیشتر، به Aspose.3D مستندات یا منبع را در GitHub.