Kľúčové funkcie Aspose.3D FOSS pre Java

V úvodnom príspevku, sme pokryli, čo je Aspose.3D FOSS pre Java a ako začať. Tento príspevok sa hlbšie venuje kľúčovým funkciám, ktoré tvoria knižnicu, s príkladmi kódu pre každú oblasť.

Všetky príklady predpokladajú nasledujúci import:

import com.aspose.threed.*;

A Maven závislosť:

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

API grafu scény

Scénový graf je základom Aspose.3D FOSS pre Java. Každý 3D model – či už načítaný zo súboru, alebo vytvorený programovo – je reprezentovaný ako strom uzlov zakorenený v Scene objekte.

Scéna

Trieda Scene je vstupným bodom pre všetky operácie. Môžete vytvoriť prázdnu scénu alebo načítať jednu zo súboru:

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

Koreň stromu uzlov je prístupný cez getRootNode().

Uzol

A Node predstavuje pomenovanú pozíciu v stromu scény. Uzly môžu mať deti, čím vytvárajú hierarchiu. Každý uzol nesie lokálny Transform a vypočítaný 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");

Môžete tiež konštruovať uzly nezávisle a pripojiť ich neskôr:

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

Entita a Mesh

An Entity je abstraktnou základnou triedou pre čokoľvek, čo môže byť pripojené k uzlu – geometria, kamery a svetlá. Najbežnejším typom entity je Mesh, ktorý obsahuje polygonálnu geometriu (vrcholy, plochy a normály).

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ú entity, ktoré sa pripájajú k uzlom:

Scene scene = new Scene();

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

Poznámka: The Camera class v edícii Java je minimálny stub len s konštruktormi. Entity kamier pripojené k uzlom sú nie je zapísané pri exporte do glTF alebo akéhokoľvek iného formátu — glTF exportér spracováva iba Mesh entity. Nespoliehajte sa na to, že dáta kamier budú zachované v exportovaných súboroch.

Poznámka: The Light trieda nie je k dispozícii v edícii Java. Dáta osvetlenia scény z importovaných súborov sú uložené ako generické Entity objekty.

Načítanie a ukladanie nezávislé od formátu

Jednou z predností knižnice je, že graf scény je nezávislý od formátu. Načítate z akéhokoľvek podporovaného formátu, manipulujete so scénou prostredníctvom jedinej API a uložíte do akéhokoľvek podporovaného formátu.

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

Formát sa určuje podľa prípony súboru. Môžete tiež odovzdať explicitné možnosti ukladania na kontrolu výstupu:

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

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

Materiály

Aspose.3D FOSS pre Java poskytuje PBR (Physically Based Rendering) model materiálu prostredníctvom PbrMaterial. Toto je jediná konkrétna trieda materiálu v edícii Java.

PbrMaterial

Materiál založený na fyzikálne založenom renderovaní, ktorý používa parametre albedo, metalicity a drsnosti. Toto je štandardný model materiálu pre glTF a moderné real‑time enginy.

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

Zachovanie materiálu medzi formátmi závisí od možností cieľového formátu. PBR materiály sa prirodzene mapujú na výstup glTF a GLB.

Transformácia a priestor

Každý Node v grafu scény má Transform ktorý definuje jeho pozíciu, rotáciu a mierku vzhľadom na jeho rodiča.

Lokálna transformácia

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

Globálna transformácia

The GlobalTransform je vypočítaná transformácia vo svetovom priestore, berúca do úvahy celý reťazec rodičov. Je len na čítanie a aktualizuje sa automaticky.

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

Toto dedenie transformácií rodič-dieťa nasleduje štandardný vzor grafu scény používaný 3D enginami a DCC nástrojmi.

Matematické nástroje

Knižnica obsahuje základné matematické typy pre 3D operácie.

Vector3

Trojsložkový vektor používaný pre pozície, smerovanie, normály a farby.

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

4x4 transformačná matica na kombinovanie translácie, rotácie a mierky do jednej operácie.

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

Quaternion

Reprezentácia rotácie, ktorá zabraňuje gimbal locku a interpoluje plynulo. Quaterniony sa používajú interne systémom transformácií.

BoundingBox

Axis-aligned BoundingBox pre priestorové dotazy, kontrolu kolízií a analýzu scény.

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

Poznámka: Node.getBoundingBox() a Entity.getBoundingBox() ešte nie sú implementované. Obe vracajú prázdny BoundingBox (s sentinel Double.MAX_VALUE / Double.MIN_VALUE hodnotami) bez ohľadu na geometriu siete. Nepoužívajte tieto metódy na výpočet skutočných geometrických hraníc v tejto verzii.

Známe obmedzenia

Stojí za zmienku, že Scene.render() je nie je podporované v edícii FOSS. Volaním to vyvolá UnsupportedOperationException.Knižnica je navrhnutá pre súborovo založené 3D spracovanie – načítanie, transformáciu a ukladanie – namiesto renderovania v reálnom čase.

Zhrnutie

Kľúčové funkcie Aspose.3D FOSS pre Java sa rozdeľujú do piatich oblastí:

V nasledujúcom príspevku prejdeme praktickými tutoriálmi formát po formáte, ktoré pokrývajú OBJ, STL, glTF a FBX s podrobnými možnosťami načítania a ukladania.