Einführung Aspose.3D FOSS für Java

Wir freuen uns, die Verfügbarkeit von Aspose.3D FOSS for Java – eine kostenlose, Open-Source-Bibliothek zum Arbeiten mit 3D-Dateiformaten in Java-Anwendungen. Entwickelt als reine Java-Lösung ohne native Abhängigkeiten, läuft die Bibliothek auf Java 21 und später, was sie für ein breites Spektrum von Projekten und Umgebungen zugänglich macht.

Dieser Beitrag führt durch das, was die Bibliothek bietet, wie man loslegt und wohin es von hier aus geht.

Was ist Aspose.3D FOSS für Java?

Aspose.3D FOSS for Java ist eine leichtgewichtige 3D-Dateiverarbeitungsbibliothek, die veröffentlicht wurde unter der MIT-Lizenz. Sie bietet eine Szenengraph-API, die es Ihnen ermöglicht, 3D-Modelle zu laden, zu inspizieren, zu transformieren und in mehreren weit verbreiteten Formaten zu speichern. Die Bibliothek ist vollständig in Java geschrieben und erfordert keine externen nativen Binärdateien oder plattformspezifischen Konfigurationen.

Der Quellcode ist auf GitHub verfügbar: https://github.com/aspose-3d-foss/Aspose.3D-FOSS-for-Java

Wichtige Highlights

• Rein Java – kein JNI, keine nativen Bibliotheken, keine Plattformbeschränkungen.
• Java 21+ kompatibel.
• MIT-lizenziert – verwenden Sie es in persönlichen, kommerziellen oder proprietären Projekten ohne Einschränkungen.
• Szenengraph-Architektur – ein vertrauter Baum von Knoten, Meshes, Kameras und Materialien.
• Mehrformatunterstützung – lesen und schreiben von OBJ-, STL-, glTF 2.0- und GLB-Dateien; FBX-Dateien lesen.

Schnellstart

Maven-Installation

Fügen Sie die folgende Abhängigkeit zu Ihrem pom.xml:

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

Ihre erste Konvertierung

Der einfachste Anwendungsfall besteht darin, eine 3D-Datei in einem Format zu laden und in einem anderen zu speichern. Hier ist eine zweizeilige Konvertierung von OBJ nach STL:

import com.aspose.threed.*;

public class QuickConvert {
    public static void main(String[] args) throws Exception {
        Scene scene = Scene.fromFile("cube.obj");
        scene.save("output.stl");
    }
}

Der Scene Klasse ist der zentrale Einstiegspunkt. Aufrufen Scene.fromFile() mit einem Dateipfad, um ein Modell zu laden, dann aufrufen save() mit dem Zielpfad. Die Bibliothek ermittelt das Format anhand der Dateierweiterung.

Erstellen einer Szene von Grund auf

Sie können Szenen auch programmgesteuert erstellen:

import com.aspose.threed.*;

public class BuildScene {
    public static void main(String[] args) throws Exception {
        Scene scene = new Scene();
        Node node = scene.getRootNode().createChildNode("Box");

        Transform t = node.getTransform();
        t.setTranslation(1, 2, 3);

        scene.save("scene.gltf");
    }
}

Dies erstellt eine neue Szene, fügt unter dem Root-Knoten einen Kindknoten mit dem Namen “Box” hinzu, positioniert ihn bei den Koordinaten (1, 2, 3) und exportiert das Ergebnis als glTF-Datei.

Laden mit formatabhängigen Optionen

Wenn Sie eine feinere Kontrolle über den Ladevorgang benötigen, stellt jedes Format eine eigene Optionsklasse bereit. Zum Beispiel das Laden einer STL‑Datei mit expliziten Optionen:

import com.aspose.threed.*;

public class LoadWithOptions {
    public static void main(String[] args) throws Exception {
        StlLoadOptions opts = new StlLoadOptions();
        Scene scene = Scene.fromFile("part.stl", opts);

        // Inspect the loaded scene
        System.out.println("Root children: "
            + scene.getRootNode().getChildNodes().size());

        // Re-export as OBJ
        scene.save("part.obj");
    }
}

Der Scene.fromFile() static method akzeptiert jede der Ladeoptionstypen: ObjLoadOptions, StlLoadOptions, GltfLoadOptions, oder FbxLoadOptions.

Durchlaufen des Szenengraphen

Sobald eine Szene geladen ist, können Sie den Knotbaum durchlaufen, um deren Inhalt zu inspizieren oder zu modifizieren:

import com.aspose.threed.*;

public class TraverseScene {
    public static void main(String[] args) throws Exception {
        Scene scene = Scene.fromFile("model.gltf");

        for (Node child : scene.getRootNode().getChildNodes()) {
            System.out.println("Node: " + child.getName());

            Transform t = child.getTransform();
            System.out.println("  Translation: " + t.getTranslation());

            Entity entity = child.getEntity();
            if (entity instanceof Mesh) {
                Mesh mesh = (Mesh) entity;
                System.out.println("  Vertices: "
                    + mesh.getControlPoints().size());
            }
        }
    }
}

Dieses Muster ist nützlich zum Debuggen, zum Erstellen von Berichten über den Modellinhalt oder zum selektiven Ändern von Teilen einer Szene vor dem erneuten Export.

Anwenden von Transformationen

Die Positionierung von Knoten im 3D-Raum erfolgt über die Transform Objekt auf jedem Node:

import com.aspose.threed.*;

public class TransformExample {
    public static void main(String[] args) throws Exception {
        Scene scene = new Scene();

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

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

        // Child's world position is (15, 0, 0) due to
        // parent-child transform inheritance

        scene.save("transformed.gltf");
    }
}

Transformationen folgen dem standardmäßigen Eltern‑Kind‑Vererbungsmodell: Die Weltposition eines Kindes ist die Kombination seiner lokalen Transformation und aller Vorfahren‑Transformationen bis zur Wurzel.

Was enthalten ist

Die Bibliothek wird mit einem fokussierten Satz von Funktionen geliefert, die um das 3D‑Szenengraph‑Modell herum konzipiert sind.

Szenengraph

Der Szenengraph ist das Rückgrat der API. Jede 3D‑Datei wird als Baumstruktur dargestellt:

Materialien

Die Bibliothek stellt ein PBR‑(Physically Based Rendering) Materialmodell bereit:

• PbrMaterial – physikalisch basiertes Rendering-Material mit Albedo, Metallizität, Rauheit, Emissionsfarbe und Transparenz. Dies ist die einzige konkrete Materialklasse, die in der Java-Edition verfügbar ist.

Mathe-Utilities

Der com.aspose.threed Paket enthält wesentliche mathematische Primitive:

• Vector3 – 3-Komponenten-Vektor für Positionen, Richtungen und Farben.
• Matrix4 – 4x4 Transformationsmatrix.
• Quaternion – Rotationsdarstellung.
• BoundingBox – achsenorientierte Bounding-Box für räumliche Abfragen.

Vector3 a = new Vector3(1, 0, 0);
Vector3 b = new Vector3(0, 1, 0);
Vector3 c = Vector3.add(a, b); // (1, 1, 0)

Lade- und Speicheroptionen

Jedes Format verfügt über eigene Optionsklassen, mit denen Sie das Import‑ und Exportverhalten steuern können:

Zum Beispiel, um glTF mit schön formatiertem JSON und einem umgekehrten Koordinatensystem zu exportieren:

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

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

Unterstützte Formate

Die folgende Tabelle fasst die Formate zusammen, die Aspose.3D FOSS für Java lesen und schreiben kann.

OBJ, STL, glTF und GLB unterstützen sowohl das Laden als auch das Speichern. FBX wird nur für den Import unterstützt.

Leitfaden zur Formatwahl

Die Wahl des richtigen Formats hängt von Ihrem Anwendungsfall ab:

• OBJ ist ideal, wenn Sie maximale Kompatibilität über 3D‑Tools hinweg benötigen. Fast jede Modellierungsanwendung kann OBJ lesen und schreiben. Es eignet sich gut für den Austausch von Mesh‑Daten, überträgt jedoch nur grundlegende Materialinformationen über Begleit‑MTL‑Dateien.
• STL ist das bevorzugte Format für 3D‑Druck‑Workflows. Es speichert rohe triangulierte Geometrie ohne Materialien oder Szenenhierarchie, was genau das ist, was Slicer‑Software erwartet. Wenn Ihre Pipeline bei einem 3D‑Drucker endet, ist STL die unkomplizierte Wahl.
• glTF ist der moderne Standard für Web‑ und Echtzeit‑3D. Es unterstützt PBR‑Materialien, vollständige Szenenhierarchien und ist für effiziente Übertragung ausgelegt. Verwenden Sie glTF, wenn Sie webbasierte Viewer erstellen, mit three.js oder Babylon.js arbeiten oder irgendeine Echtzeit‑Rendering‑Pipeline anvisieren.
• FBX ist tief in die Spielentwicklung und die Arbeitsabläufe zur Erstellung digitaler Inhalte integriert. Es unterstützt umfangreiche Szenendaten, einschließlich Hierarchien und Materialien. Aspose. 3D FOSS für Java unterstützt FBX nur Import – verwenden Sie es, um FBX-Assets zu laden und in andere Formate zu konvertieren.

Bekannte Einschränkungen

Es ist wichtig zu beachten, dass Scene.render() ist nicht unterstützt in der FOSS-Edition. Der Aufruf dieser Methode löst eine UnsupportedOperationException. Die Bibliothek ist für dateibasierte 3D-Verarbeitung konzipiert – Laden, Manipulieren, Transformieren und Speichern von Modellen – und nicht für Echtzeit-Rendering auf einem Display.

Open Source und Lizenzierung

Aspose.3D FOSS für Java wird unter der MIT-Lizenz. Das bedeutet, dass Sie frei sind, zu:

• Die Bibliothek in kommerziellen und proprietären Anwendungen verwenden.
• Den Quellcode an Ihre Bedürfnisse anpassen.
• Verteilen Sie die Bibliothek als Teil Ihrer eigenen Software.

Es gibt keine Lizenzgebühren, keine Nutzungslimits und keine Namensnennungsanforderungen über das hinaus, was die MIT-Lizenz vorsieht.

Der vollständige Quellcode ist auf GitHub gehostet, und Beiträge sind willkommen: https://github.com/aspose-3d-foss/Aspose.3D-FOSS-for-Java

Systemanforderungen

Erste Schritte

Hier sind die Ressourcen, die Ihnen den Einstieg erleichtern:

• Dokumentation – umfassende Leitfäden und API‑Durchläufe sind auf der Aspose.3D Dokumentationsseite.
• Wissensdatenbank – praktische Anleitungen und Fehlersuch‑Tipps in der Aspose.3D KB.
• API-Referenz – detaillierte Klassen‑ und Methodenreferenz bei der Aspose.3D API-Referenz.
• Quellcode – durchsuchen und beitragen auf GitHub.
• Maven Central – das Paket wird veröffentlicht als com.aspose:aspose-3d-foss auf Maven Central.

Häufige Anwendungsfälle

Hier sind einige praktische Szenarien, in denen Aspose.3D FOSS für Java gut passt:

Formatkonvertierungs-Pipelines

Viele Teams erhalten 3D-Assets in einem Format, benötigen sie jedoch in einem anderen. Ein Designteam arbeitet möglicherweise mit FBX, während das Webteam glTF benötigt. Die Bibliothek ermöglicht den Aufbau automatisierter Konvertierungspipelines:

// Convert all incoming FBX assets to GLB for the web team
Scene scene = Scene.fromFile("asset.fbx");

GltfSaveOptions opts = new GltfSaveOptions();
opts.setContentType(FileContentType.BINARY);

scene.save("asset.glb", opts);

3D Model Inspection and Validation

Bevor Sie ein 3D-Asset in Ihre Anwendung integrieren, möchten Sie möglicherweise dessen Inhalt validieren – die Knotenzahl prüfen, die Geometrie verifizieren oder bestätigen, dass die erwarteten Elemente vorhanden sind:

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

int nodeCount = scene.getRootNode().getChildNodes().size();
System.out.println("Top-level nodes: " + nodeCount);

for (Node child : scene.getRootNode().getChildNodes()) {
    if (child.getEntity() instanceof Mesh) {
        Mesh mesh = (Mesh) child.getEntity();
        System.out.println(child.getName() + ": "
            + mesh.getControlPoints().size() + " vertices");
    }
}

Szenenassemblage

Sie können mehrere Modelle laden und sie zu einer einzigen Szene kombinieren:

Scene scene = new Scene();

Scene part1 = Scene.fromFile("chassis.obj");
Scene part2 = Scene.fromFile("wheels.obj");

// Add nodes from each part into the combined scene
for (Node child : part1.getRootNode().getChildNodes()) {
    scene.getRootNode().getChildNodes().add(child);
}
for (Node child : part2.getRootNode().getChildNodes()) {
    scene.getRootNode().getChildNodes().add(child);
}

scene.save("assembled.gltf");

Was kommt als Nächstes

In den kommenden Beiträgen werden wir behandeln:

• Ein tiefer Einblick in die wichtigsten Funktionen der scene-graph API, Materialien und mathematischen Hilfsprogramme.
• Ein praktischer Leitfaden zur Arbeit mit jedem unterstützten 3D-Format – OBJ, STL, glTF und FBX – einschließlich Lade-/Speicheroptionen und Muster für die Batch-Konvertierung.

Bleiben Sie dran, und fühlen Sie sich frei, die Bibliothek zu erkunden und Ihr Feedback auf GitHub zu teilen.