Arbeiten mit 3D-Dateiformaten in Java mit Aspose.3D FOSS

Aspose.3D FOSS für Java unterstützt fünf 3D-Dateiformate: OBJ, STL, glTF, GLB, und FBX (nur Import).

Alle Beispiele verwenden das com.aspose.threed.* Paket:

import com.aspose.threed.*;

Maven‑Abhängigkeit:

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

Formatübersicht

Bevor wir einsteigen, hier ein kurzer Überblick über die vier unterstützten Formate und ihre typischen Anwendungsfälle.

OBJ, STL, glTF und GLB unterstützen sowohl Import als auch Export. FBX wird unterstützt für nur Import. GLB (binary glTF) wird erzeugt über GltfSaveOptions mit setContentType(FileContentType.BINARY).

OBJ: Wavefront Object

OBJ ist eines der am weitesten unterstützten 3D-Mesh-Formate. Es speichert Geometrie als Klartext, mit einer optionalen .mtl Begleitdatei für Materialien.

Laden von OBJ-Dateien

Der einfachste Ansatz ist, den Dateipfad direkt zu übergeben:

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

Für mehr Kontrolle nutzen Sie ObjLoadOptions:

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

Wenn die OBJ-Datei eine MTL-Datei referenziert (über eine mtllib Direktive), versucht die Bibliothek, Materialdefinitionen automatisch daraus zu laden. Die MTL-Datei sollte sich im selben Verzeichnis wie die OBJ-Datei befinden oder an dem im Direktive angegebenen Pfad liegen.

Speichern als OBJ

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

OBJ‑Anwendungsfälle

• Austausch von Mesh‑Daten zwischen verschiedenen 3D‑Tools.
• Importieren von Modellen aus Asset-Bibliotheken, die im OBJ-Format bereitgestellt werden.
• Schnelle Inspektion der Geometrie ohne komplexe Szenenhierarchien.

STL: Stereolithografie

STL ist das Standardformat für den 3D-Druck. Es stellt rohe triangulierte Geometrie ohne Materialien, Farben oder Szenenhierarchie dar. STL-Dateien gibt es in zwei Varianten: ASCII (menschlich lesbar) und binär (kompakt).

Laden von STL-Dateien

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

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

Speichern als STL

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

Um die Ausgabe zu steuern, verwenden Sie StlSaveOptions:

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

STL-Überlegungen

• STL speichert nur Dreiecksgeometrie. Materialien, Texturen und Szenenhierarchie werden nicht unterstützt und beim Export verworfen.
• STL-Export macht nicht automatisch triangulieren. Binäres STL schreibt nur die ersten 3 Scheitelpunkte jeder Polygonfläche; Quad‑ und n‑Gon‑Flächen werden stillschweigend abgeschnitten. ASCII‑STL schreibt alle Scheitelpunktindizes pro Fläche, was zu fehlerhafter Ausgabe bei Nicht‑Dreieck‑Flächen führt. Verwenden Sie stets vortriangulierte Meshes (nur Dreieck‑Flächen), wenn Sie nach STL exportieren.
• Binäres STL ist bei großen Modellen deutlich kleiner als ASCII STL.
• STL ist das bevorzugte Format, wenn das Ziel ein 3D-Drucker oder eine Slicer-Software ist.

glTF: GL Transmission Format

glTF ist ein modernes Format, das für die effiziente Übertragung und das Laden von 3D-Inhalten entwickelt wurde, insbesondere im Web und in Echtzeitanwendungen. Es unterstützt PBR‑Materialien, Szenenhierarchien und Animationen.

Laden von glTF-Dateien

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

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

Speichern als glTF

Der grundlegende Speichervorgang verwendet die Dateierweiterung, um das Format zu bestimmen:

scene.save("output.gltf");

Für detaillierte Kontrolle verwenden Sie GltfSaveOptions:

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

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

GltfSaveOptions Details

glTF Anwendungsfälle

• Webbasierte 3D-Viewer (three.js, Babylon.js).
• Echtzeitanwendungen und Spiel-Engines.
• Erhaltung von PBR-Materialdefinitionen über verschiedene Werkzeuge hinweg.

FBX: Filmbox (Nur Import)

FBX ist ein proprietäres Format von Autodesk, das in der Spieleentwicklung und der digitalen Inhaltserstellung weit verbreitet ist. Aspose.3D FOSS für Java unterstützt FBX für nur Import — Export nach FBX ist nicht verfügbar.

Nur binäres FBX. Der FBX‑Importer liest nur binäre FBX‑Dateien. Das Übergeben einer ASCII‑FBX‑Datei wirft ImportException("ASCII FBX format not yet supported - only binary FBX is supported"). Die Knotenhierarchie und die Materialextraktion aus FBX sind nicht vollständig verifiziert; komplexe FBX‑Szenen werden möglicherweise nicht vollständig geladen. Animationen und Rigging sind nicht implementiert.

Laden von FBX-Dateien

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

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

Konvertieren von FBX in andere Formate

Da der FBX-Export nicht unterstützt wird, konvertieren Sie importierte FBX‑Szenen zu glTF, GLB, OBJ oder STL:

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

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

FBX Anwendungsfälle

• Import statischer Mesh-Assets aus Autodesk‑Werkzeugen (Maya, 3ds Max) und Konvertierung in andere Formate.
• Laden binärer FBX-Geometrie und erneutes Exportieren nach glTF/GLB, OBJ oder STL.

Stapelkonvertierung

Ein gängiger Arbeitsablauf besteht darin, ein ganzes Verzeichnis von Dateien von einem Format in ein anderes zu konvertieren. Hier ist ein Muster für die Stapelkonvertierung:

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

Dies lädt jede .obj Dies lädt jede Datei in einem Verzeichnis, konvertiert jede in glTF mit schön formatiertem Output und speichert die Ergebnisse. Sie können dieses Muster für jede Kombination von Quell- und Zielformat anpassen.

Referenz für konvertierung zwischen Formaten

Die folgende Tabelle zeigt, was Sie bei der Konvertierung zwischen Formaten erwarten können.

Allgemeine Konvertierungsrichtlinien

• Geometrie wird im Allgemeinen über Formatpaare hinweg erhalten, mit einer wichtigen Ausnahme: Beim Exportieren nach STL müssen Meshes ausschließlich aus Dreiecksflächen bestehen. Binary STL schneidet stillschweigend quad- und n-gon‑Flächen auf ihre ersten 3 Eckpunkte ab; ASCII STL erzeugt fehlerhafte Ausgaben für nicht‑dreieckige Flächen.
• Materialien überleben am besten zwischen glTF- und FBX‑importierten Szenen, die Materialdaten enthalten. Die Konvertierung nach STL verwirft immer Materialien. Die Konvertierung nach OBJ vereinfacht Materialien zum grundlegenden MTL‑Modell.
• Szenenhierarchie wird zwischen glTF‑Formatdateien erhalten. OBJ und STL erzeugen flache Strukturen. Die FBX‑Hierarchie und Materialextraktion sind in dieser Version nicht vollständig verifiziert.

Alles zusammenführen

Hier ist ein vollständiges Beispiel, das eine OBJ‑Datei lädt, ihre Knoten inspiziert und sowohl nach glTF als auch nach GLB exportiert:

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.");
    }
}

Zusammenfassung

Aspose.3D FOSS für Java bietet Ihnen eine konsistente API über mehrere Formate hinweg. Die wichtigsten Punkte:

• OBJ – einfacher Mesh‑Austausch mit grundlegenden Materialien.
• STL – Nur-Geometrie-Format für 3D-Druck-Pipelines.
• glTF / GLB – modernes, PBR-fähiges Format für Web- und Echtzeit-Anwendungen. Verwenden Sie GltfSaveOptions mit setContentType(FileContentType.BINARY) für GLB-Ausgabe.
• FBX – nur zum Import; umfangreiches Format zum Laden von Assets aus Spiel-Engines und DCC-Tools.

Verwenden Sie formatbezogene Lade- und Speicheroption‑Klassen (ObjLoadOptions, StlLoadOptions, StlSaveOptions, GltfLoadOptions, GltfSaveOptions, FbxLoadOptions) wenn Sie eine feinkörnige Kontrolle über den Import‑ oder Exportvorgang benötigen.

Für weitere Details besuchen Sie die Aspose.3D Dokumentation oder durchsuchen Sie den Quellcode auf GitHub.