Kluczowe funkcje Aspose.3D FOSS dla Java

W poście wprowadzającym, omówiliśmy, czym jest Aspose.3D FOSS dla Java i jak rozpocząć. Ten post zagłębia się w kluczowe funkcje tworzące bibliotekę, z przykładami kodu dla każdego obszaru.

Wszystkie przykłady zakładają następujący import:

import com.aspose.threed.*;

Oraz zależność Maven:

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

API grafu scen

Graf sceny jest podstawą Aspose.3D FOSS dla Java. Każdy model 3D — niezależnie od tego, czy został wczytany z pliku, czy zbudowany programowo — jest reprezentowany jako drzewo węzłów z korzeniem w Scene obiekcie.

Scena

Klasa Scene jest punktem wejścia dla wszystkich operacji. Możesz utworzyć pustą scenę lub wczytać ją z pliku:

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

Korzeń drzewa węzłów jest dostępny przez getRootNode().

Węzeł

A Node reprezentuje nazwane położenie w drzewie sceny. Węzły mogą mieć dzieci, tworząc hierarchię. Każdy węzeł posiada lokalny Transform oraz obliczony 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");

Możesz także tworzyć węzły niezależnie i podłączać je później:

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

Entity i Mesh

Jedna Entity jest abstrakcyjną klasą bazową dla wszystkiego, co może być dołączone do węzła – geometria, kamery i światła. Najbardziej powszechnym typem encji jest Mesh, który przechowuje geometrię wielokątową (wierzchołki, ściany i wektory normalne).

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

Kamera

Kamery są encjami, które podłączają się do węzłów:

Scene scene = new Scene();

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

Definicje kamer są zachowywane przy eksportowaniu do formatów, które je obsługują (takich jak glTF).

Uwaga: Klasa Light klasa nie jest dostępna w edycji Java. Dane oświetlenia sceny z zaimportowanych plików są przechowywane jako ogólne Entity obiekty.

Ładowanie i zapisywanie niezależne od formatu

Jedną z zalet biblioteki jest to, że graf sceny jest niezależny od formatu. Ładujesz z dowolnego obsługiwanego formatu, manipulujesz sceną za pomocą jednego API i zapisujesz do dowolnego obsługiwanego formatu.

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

Format jest określany na podstawie rozszerzenia pliku. Możesz także przekazać explicite opcje zapisu, aby kontrolować wynik:

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

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

Materiały

Aspose.3D FOSS dla Java zapewnia model materiału PBR (Physically Based Rendering) za pośrednictwem PbrMaterial. To jedyna konkretna klasa materiału w edycji Java.

PbrMaterial

Materiał renderingu opartego na fizyce, który używa parametrów albedo, metaliczności i szorstkości. To standardowy model materiału dla glTF i nowoczesnych silników czasu rzeczywistego.

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

Zachowanie materiałów pomiędzy formatami zależy od możliwości docelowego formatu. Materiały PBR naturalnie mapują się na wyjście glTF i GLB.

Transform i Spatial

Każdy Node w grafie sceny ma Transform który definiuje jego pozycję, rotację i skalę względem rodzica.

Transform lokalny

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

Transform globalny

Ten GlobalTransform jest obliczonym przekształceniem w przestrzeni światowej, uwzględniającym cały łańcuch rodziców. Jest to tylko do odczytu i aktualizuje się automatycznie.

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

To dziedziczenie transformacji rodzic-dziecko podąża za standardowym wzorcem grafu sceny używanym przez silniki 3D i narzędzia DCC.

Narzędzia matematyczne

Biblioteka zawiera podstawowe typy matematyczne do operacji 3D.

Vector3

Wektor trójskładnikowy używany do pozycji, kierunków, normalnych i kolorów.

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

Macierz transformacji 4x4 służąca do łączenia translacji, rotacji i skalowania w jedną operację.

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

Quaternion

Reprezentacja rotacji, która unika gimbal lock i interpoluje płynnie. Kwaterniony są używane wewnętrznie przez system transformacji.

BoundingBox

Prostopadłościan ograniczający wyrównany do osi, używany do zapytań przestrzennych, sprawdzania kolizji i analizy sceny.

BoundingBox bbox = new BoundingBox();
// BoundingBox can be computed from mesh geometry

Znane ograniczenia

Warto zauważyć, że Scene.render() jest nie jest obsługiwane w edycji FOSS. Wywołanie tego spowoduje wyrzucenie UnsupportedOperationException. Biblioteka jest zaprojektowana do przetwarzania 3D opartego na plikach — ładowania, przekształcania i zapisywania — zamiast renderowania w czasie rzeczywistym.

Podsumowanie

Kluczowe funkcje Aspose.3D FOSS dla Java dzielą się na pięć obszarów:

W następnym poście przeprowadzimy praktyczne samouczki format po formacie, obejmujące OBJ, STL, glTF i FBX, z szczegółowymi opcjami ładowania i zapisywania.