Nyckelfunktioner i Aspose.3D FOSS för Java

I introduktionsinlägg, vi täckte vad Aspose.3D FOSS för Java är och hur man kommer igång. Detta inlägg går djupare in på nyckelfunktionerna som utgör biblioteket, med kodexempel för varje område.

Alla exempel förutsätter följande import:

import com.aspose.threed.*;

Och Maven‑beroendet:

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

Scene Graph API

Scengrafen är grunden för Aspose.3D FOSS för Java. Varje 3D-modell – oavsett om den laddas från en fil eller byggs programmässigt – representeras som ett träd av noder med rot i en Scene objekt.

Scene

Klassen Scene klass är ingångspunkten för alla operationer. Du kan skapa en tom scen eller ladda en från en fil:

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

Roten av nodträdet nås via getRootNode().

Node

En Node representerar en namngiven position i scengrädet. Noder kan ha barn, vilket bildar en hierarki. Varje nod bär en lokal Transform och en beräknad 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");

Du kan också konstruera noder oberoende och fästa dem senare:

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

Entity och Mesh

En Entity är en abstrakt basklass för allt som kan fästas på en nod – geometri, kameror och ljus. Den vanligaste entitetstypen är Mesh, som innehåller polygonal geometri (vertexar, ytor och normaler).

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

Kameror är entiteter som fästs på noder:

Scene scene = new Scene();

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

Obs: Det Camera class i Java-utgåvan är en minimal stub med endast konstruktorer. Camera entities attached to nodes are inte skriven vid export till glTF eller något annat format — glTF-exportören bearbetar endast Mesh entities. Lita inte på att kameradata bevaras i exporterade filer.

Obs: Den Light klassen är inte tillgänglig i Java-utgåvan. Scenbelysningsdata från importerade filer lagras som generiska Entity objekt.

Formatoberoende inläsning och sparning

En av bibliotekets styrkor är att scengrafen är formatoberoende. Du laddar från vilket stödjande format som helst, manipulerar scenen via ett enda API och sparar till vilket stödjande format som helst.

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

Formatet bestäms av filändelsen. Du kan också skicka explicita sparalternativ för att styra utdata:

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

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

Material

Aspose.3D FOSS för Java tillhandahåller en PBR (Physically Based Rendering) materialmodell via PbrMaterial. Detta är den enda konkreta materialklassen i Java-utgåvan.

PbrMaterial

Ett fysiskt baserat renderingsmaterial som använder albedo-, metalness- och roughness-parametrar. Detta är den standardmaterialmodell som används för glTF och moderna realtidsmotorer.

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

Materialbevarande över format beror på målformatets möjligheter. PBR-material mappar naturligt till glTF- och GLB-utdata.

Transform och Spatial

Varje Node i scengrafen har en Transform som definierar dess position, rotation och skala relativt dess förälder.

Lokal 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

Global Transform

Den GlobalTransform är den beräknade världsrumstransformen, som tar hänsyn till hela föräldrakedjan. Den är skrivskyddad och uppdateras automatiskt.

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

Denna förälder-barn-transformarv följer det standardmönster för scengraf som används av 3D-motorer och DCC-verktyg.

Matematikverktyg

Biblioteket inkluderar grundläggande matematiska typer för 3D-operationer.

Vector3

En trekomponentsvektor som används för positioner, riktningar, normaler och färger.

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

En 4x4 transformationsmatris för att kombinera translation, rotation och skalning i en enda operation.

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

Quaternion

En rotationsrepresentation som undviker gimbal lock och interpolerar mjukt. Quaternions används internt av transformsystemet.

BoundingBox

En axeljusterad BoundingBox för rumsliga frågor, kollisionskontroller och scenanalys.

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

Obs: Node.getBoundingBox() och Entity.getBoundingBox() är ännu inte implementerade. Båda returnerar en tom BoundingBox (med sentinel Double.MAX_VALUE / Double.MIN_VALUE värden) oavsett mesh-geometri. Använd inte dessa metoder för att beräkna faktiska geometrigränser i denna version.

Kända begränsningar

Det är värt att notera att Scene.render() är stöds inte i FOSS-utgåvan. Att anropa den kommer att kasta ett UnsupportedOperationException. Biblioteket är utformat för filbaserad 3D-behandling – inläsning, transformering och sparande – snarare än realtidsrendering.

Sammanfattning

De viktigaste funktionerna i Aspose.3D FOSS för Java kan delas in i fem områden:

I nästa inlägg kommer vi att gå igenom praktiska format-för-format-handledningar som täcker OBJ, STL, glTF och FBX med detaljerade inläsnings- och sparalternativ.