Nøglefunktioner i Aspose.3D FOSS for Java

I introduktionsindlæg, vi dækkede hvad Aspose.3D FOSS for Java er, og hvordan man kommer i gang. Dette indlæg går dybere ind i de vigtigste funktioner, der udgør biblioteket, med kodeeksempler for hvert område.

Alle eksempler antager følgende import:

import com.aspose.threed.*;

Og Maven-afhængigheden:

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

Scene Graph API

Scenegrafen er grundlaget for Aspose.3D FOSS for Java. Hver 3D-model – uanset om den er indlæst fra en fil eller bygget programmatisk – repræsenteres som et træ af noder med rod i en Scene objekt.

Scene

Klassen Scene klassen er indgangspunktet for alle operationer. Du kan oprette en tom scene eller indlæse en fra 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());

Rød​en af nodetræet tilgås via getRootNode().

Node

En Node repræsenterer en navngivet position i scenetræet. Noder kan have børn, der danner et hierarki. Hver node bærer en lokal Transform og en beregnet 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 også konstruere noder uafhængigt og vedhæfte dem senere:

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

Entity and Mesh

En Entity er en abstrakt grundklasse for alt, der kan vedhæftes en node – geometri, kameraer og lys. Den mest almindelige entitetstype er Mesh, som indeholder polygonal geometri (vertexer, flader og 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

Kameraer er entiteter, der vedhæftes noder:

Scene scene = new Scene();

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

Bemærk: Den Camera klassen i Java-udgaven er en minimal stub med kun konstruktører. Kameraenheder, der er knyttet til noder, er ikke skrevet ved eksport til glTF eller et andet format — glTF-eksportøren behandler kun Mesh enheder. Stol ikke på, at kameradata bevares i eksporterede filer.

Bemærk: Den Light klassen er ikke tilgængelig i Java udgaven. Scene-belysningsdata fra importerede filer gemmes som generiske Entity objekter.

Format-agnostisk indlæsning og gemning

En af bibliotekets styrker er, at scenegrafen er format-uafhængig. Du indlæser fra ethvert understøttet format, manipulerer scenen gennem en enkelt API og gemmer til ethvert understøttet 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);

Formatet bestemmes af filendelsen. Du kan også angive eksplicitte gemmeindstillinger for at styre outputtet:

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

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

Materialer

Aspose.3D FOSS for Java leverer en PBR (Physically Based Rendering) materialmodel via PbrMaterial. Dette er den eneste konkrete materialklasse i Java udgaven.

PbrMaterial

Et fysisk baseret renderingsmateriale, der bruger albedo-, metalness- og roughness-parametre. Dette er den standard materialmodel for glTF og moderne 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

Bevarelse af materialer på tværs af formater afhænger af målformatets muligheder. PBR-materialer kortlægges naturligt til glTF- og GLB-output.

Transform og Spatial

Hver Node i scenegrafen har en Transform som definerer dens position, rotation og skala i forhold til dens overordnede.

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 er den beregnede verdensrumstransformation, der tager hele forældre‑kæden i betragtning. Den er skrivebeskyttet og opdateres automatisk.

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

Denne forælder-barn transformarv følger det standard scene-graph-mønster, der anvendes af 3D-motorer og DCC-værktøjer.

Matematikværktøjer

Biblioteket inkluderer kerne-matematiktyper til 3D-operationer.

Vector3

En tre-komponent vektor, der bruges til positioner, retninger, normaler og farver.

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 transformationsmatrix til at kombinere translation, rotation og skalering i en enkelt operation.

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

Quaternion

En rotationsrepræsentation, der undgår gimbal lock og interpolerer glat. Quaternions bruges internt af transformsystemet.

BoundingBox

En aksejusteret begrænsningsboks til rumlige forespørgsler, kollisionskontrol og scenanalyse.

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

Bemærk: Node.getBoundingBox() og Entity.getBoundingBox() er endnu ikke implementeret. Begge returnerer en tom BoundingBox (med sentinel Double.MAX_VALUE / Double.MIN_VALUE værdier) uanset mesh-geometrien. Brug ikke disse metoder til at beregne faktiske geometrigrænser i denne version.

Kendte begrænsninger

Det er værd at bemærke, at Scene.render() er ikke understøttet i FOSS-udgaven. At kalde den vil kaste en UnsupportedOperationException. Biblioteket er designet til filbaseret 3D-behandling – indlæsning, transformation og lagring – snarere end realtidsrendering.

Opsummering

De vigtigste funktioner i Aspose.3D FOSS for Java kan opdeles i fem områder:

I det næste indlæg vil vi gennemgå praktiske format‑for‑format‑tutorials, der dækker OBJ, STL, glTF og FBX med detaljerede indlæsnings‑ og gemme‑muligheder.