Nøkkelfunksjoner i Aspose.3D FOSS for Java

I introduksjonsinnlegg, vi dekket hva Aspose.3D FOSS for Java er og hvordan man kommer i gang. Dette innlegget går dypere inn i nøkkelfunksjonene som utgjør biblioteket, med kodeeksempler for hvert område.

Alle eksempler forutsetter følgende import:

import com.aspose.threed.*;

Og Maven‑avhengigheten:

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

Scene Graph API

Scenegrafen er grunnlaget for Aspose.3D FOSS for Java. Hver 3D-modell – enten den er lastet fra en fil eller bygget programmatisk – er representert som et tre av noder med rot i en Scene objekt.

Scene

Klassen Scene er inngangspunktet for alle operasjoner. Du kan opprette en tom scene eller laste inn 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øtten til nodetreet nås via getRootNode().

Node

En Node representerer en navngitt posisjon i scenetreet. Noder kan ha barn, og danner et hierarki. Hver node har 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 uavhengig og feste dem senere:

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

Entity og Mesh

En Entity er en abstrakt basisklasse for alt som kan festes til en node – geometri, kameraer og lys. Den mest vanlige entitetstypen er Mesh, som inneholder polygonal geometri (vertikser, flater 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 som festes til noder:

Scene scene = new Scene();

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

Merk: Den Camera klassen i Java-utgaven er en minimal stub med kun konstruktører. Kameraenheter festet til noder er ikke skrevet ved eksport til glTF eller et annet format — glTF-eksportøren behandler kun Mesh enheter. Ikke stol på at kameradata blir bevart i eksporterte filer.

Merk: Den Light klassen er ikke tilgjengelig i Java-utgaven. Scene-belysningsdata fra importerte filer lagres som generisk Entity objekter.

Format-agnostisk lasting og lagring

En av styrkene til biblioteket er at scenegrafen er format-uavhengig. Du kan laste fra ethvert støttet format, manipulere scenen gjennom ett enkelt API, og lagre til ethvert stø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 av filendelsen. Du kan også sende eksplisitte lagringsalternativer for å kontrollere outputen:

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

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

Materialer

Aspose.3D FOSS for Java tilbyr en PBR (Physically Based Rendering) materialmodell via PbrMaterial.Dette er den eneste konkrete materialklassen i Java-utgaven.

PbrMaterial

Et fysisk basert renderingsmateriale som bruker albedo-, metall- og ruhetsparametere. Dette er standard materialmodell for glTF og moderne sanntidsmotorer.

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

Bevaring av materialer på tvers av formater avhenger av målformatets muligheter. PBR-materialer kartlegges naturlig til glTF- og GLB-output.

Transform og Spatial

Hver Node i scene‑grafen har en Transform som definerer posisjonen, rotasjonen og skalaen i forhold til sin forelder.

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 verdensromtransformasjonen, som tar hele foreldre‑kjeden i betraktning. Denne er skrivebeskyttet og oppdateres 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 forelder-barn-transformasjonsarv følger det standard scenegraf-mønsteret som brukes av 3D-motorer og DCC-verktøy.

Matematikkverktøy

Biblioteket inneholder grunnleggende matematiske typer for 3D-operasjoner.

Vector3

En tre‑komponent vektor som brukes for posisjoner, retninger, normaler og farger.

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 transformasjonsmatrise for å kombinere translasjon, rotasjon og skalering i en enkelt operasjon.

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

Quaternion

En rotasjonsrepresentasjon som unngår gimbal lock og interpolerer jevnt. Quaternioner brukes internt av transformasjonssystemet.

BoundingBox

En aksejustert avgrensningsboks for romlige spørringer, kollisjonskontroller og scenanalyse.

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

Merk: Node.getBoundingBox() og Entity.getBoundingBox() er ennå ikke implementert. Begge returnerer en tom BoundingBox (med sentinel Double.MAX_VALUE / Double.MIN_VALUE verdier) uavhengig av mesh‑geometrien. Ikke bruk disse metodene til å beregne faktiske geometrigrenser i denne versjonen.

Kjente begrensninger

Det er verdt å merke seg at Scene.render() er ikke støttet i FOSS-utgaven. Å kalle den vil kaste en UnsupportedOperationException.Biblioteket er designet for filbasert 3D-behandling – lasting, transformering og lagring – snarere enn sanntidsrendering.

Oppsummering

Hovedfunksjonene i Aspose.3D FOSS for Java deles inn i fem områder:

I neste innlegg vil vi gå gjennom praktiske format‑for‑format‑opplæringer som dekker OBJ, STL, glTF og FBX med detaljerte inn‑ og lagringsalternativer.