Hauptmerkmale von Aspose.3D FOSS für Java

Im Einführungsbeitrag, wir haben behandelt, was Aspose.3D FOSS für Java ist und wie man anfängt. Dieser Beitrag geht tiefer auf die wichtigsten Funktionen ein, aus denen die Bibliothek besteht, mit Codebeispielen für jeden Bereich.

Alle Beispiele gehen von folgendem Import aus:

import com.aspose.threed.*;

Und die Maven-Abhängigkeit:

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

Scene-Graph-API

Der Szenengraph ist die Grundlage von Aspose.3D FOSS für Java. Jedes 3D‑Modell – egal, ob es aus einer Datei geladen oder programmgesteuert erstellt wird – wird als Baum von Knoten dargestellt, der in einem Scene Objekt.

Scene

Die Scene Klasse ist der Einstiegspunkt für alle Operationen. Sie können eine leere Szene erstellen oder eine aus einer Datei laden:

// 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());

Auf die Wurzel des Knotensbaums wird zugegriffen über getRootNode().

Node

Ein Node repräsentiert eine benannte Position im Szenenbaum. Knoten können Kinder haben und bilden eine Hierarchie. Jeder Knoten trägt ein lokales Transform und ein berechnetes 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");

Sie können Nodes auch unabhängig erstellen und später anhängen:

Node standalone = new Node("Standalone");
scene.getRootNode().getChildNodes().add(standalone);

Entity und Mesh

Ein Entity ist eine abstrakte Basisklasse für alles, was an einen Knoten angehängt werden kann – Geometrie, Kameras und Lichter. Der am häufigsten vorkommende Entitätstyp ist Mesh, das polygonale Geometrie (Scheitelpunkte, Flächen und Normalen) enthält.

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

Camera

Kameras sind Entitäten, die an Nodes angehängt werden:

Scene scene = new Scene();

Node cameraNode = scene.getRootNode().createChildNode("MainCamera");
// Camera entity can be assigned to the node

Hinweis: Die Camera Klasse in der Java Ausgabe ist ein Minimal‑Stub nur mit Konstruktoren. Kamera‑Entitäten, die an Knoten angehängt sind, sind nicht geschrieben beim Exportieren nach glTF oder einem anderen Format – der glTF‑Exporter verarbeitet nur Mesh Entitäten. Verlassen Sie sich nicht darauf, dass Kameradaten in exportierten Dateien erhalten bleiben.

Hinweis: Die Light Klasse ist in der Java Edition nicht verfügbar. Szenenbeleuchtungsdaten aus importierten Dateien werden als generisch gespeichert. Entity Objekte.

Formatunabhängiges Laden und Speichern

Eine der Stärken der Bibliothek ist, dass der Szenengraph formatunabhängig ist. Sie laden aus jedem unterstützten Format, manipulieren die Szene über eine einheitliche API und speichern in jedes unterstützte Format.

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

Das Format wird anhand der Dateierweiterung bestimmt. Sie können auch explizite Speicheroptionen übergeben, um die Ausgabe zu steuern:

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

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

Materialien

Aspose.3D FOSS für Java bietet ein PBR (Physically Based Rendering) Materialmodell über PbrMaterial. Dies ist die einzige konkrete Materialklasse in der Java Edition.

PbrMaterial

Ein physikalisch basiertes Rendering-Material, das Albedo-, Metallischkeits- und Rauheitsparameter verwendet. Dies ist das Standard-Materialmodell für glTF und moderne Echtzeit-Engines.

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

Die Materialerhaltung über Formate hinweg hängt von den Fähigkeiten des Zielformats ab. PBR-Materialien lassen sich natürlich auf glTF- und GLB-Ausgaben abbilden.

Transform und Spatial

Jedes Node im Szenengraphen hat ein Transform das seine Position, Rotation und Skalierung relativ zu seinem Elternteil definiert.

Lokales 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

Globales Transform

Der GlobalTransform ist die berechnete Welt-Raum-Transformation, die die gesamte Elternkette berücksichtigt. Sie ist schreibgeschützt und wird automatisch aktualisiert.

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();

Diese Eltern‑Kind‑Transformationsvererbung folgt dem standardmäßigen Szenengraph‑Muster, das von 3D‑Engines und DCC‑Tools verwendet wird.

Mathe‑Hilfsfunktionen

Die Bibliothek enthält Kern‑Mathematiktypen für 3D‑Operationen.

Vector3

Ein Vektor mit drei Komponenten, der für Positionen, Richtungen, Normalen und Farben verwendet wird.

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

Eine 4x4‑Transformationsmatrix zum Kombinieren von Translation, Rotation und Skalierung in einem einzigen Vorgang.

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

Quaternion

Eine Rotationsdarstellung, die Gimbal‑Lock vermeidet und glatt interpoliert. Quaternionen werden intern vom Transformationssystem verwendet.

BoundingBox

Eine achsenorientierte BoundingBox für räumliche Abfragen, Kollisionsprüfungen und Szenenanalyse.

BoundingBox bbox = new BoundingBox();
// BoundingBox can be constructed directly with min/max Vector3 values

Hinweis: Node.getBoundingBox() und Entity.getBoundingBox() sind noch nicht implementiert. Beide geben ein leeres BoundingBox (mit Sentinel Double.MAX_VALUE / Double.MIN_VALUE Werte) unabhängig von der Mesh-Geometrie zurück. Verwenden Sie diese Methoden nicht, um tatsächliche Geometriegrenzen in dieser Version zu berechnen.

Bekannte Einschränkungen

Es ist zu beachten, dass Scene.render() ist nicht unterstützt in der FOSS-Edition. Ein Aufruf wird einen UnsupportedOperationException. Die Bibliothek ist für dateibasierte 3D-Verarbeitung konzipiert – Laden, Transformieren und Speichern – und nicht für Echtzeit-Rendering.

Zusammenfassung

Die wichtigsten Funktionen von Aspose.3D FOSS für Java lassen sich in fünf Bereiche gliedern:

Im nächsten Beitrag gehen wir praktische, formatweise Tutorials zu OBJ, STL, glTF und FBX durch, inklusive detaillierter Lade‑ und Speicheroptionen.