Caratteristiche principali di Aspose.3D FOSS per Java

Nel post introduttivo, abbiamo coperto cosa è Aspose.3D FOSS per Java e come iniziare. Questo post approfondisce le funzionalità chiave che compongono la libreria, con esempi di codice per ogni area.

Tutti gli esempi presumono la seguente importazione:

import com.aspose.threed.*;

E la dipendenza Maven:

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

API del grafo della scena

Il grafo della scena è la base di Aspose.3D FOSS per Java. Ogni modello 3D – sia caricato da un file sia costruito programmaticamente – è rappresentato come un albero di nodi radicato in un Scene oggetto.

Scena

La Scene classe è il punto di ingresso per tutte le operazioni. Puoi creare una scena vuota o caricarne una da un file:

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

La radice dell’albero dei nodi è accessibile tramite getRootNode().

Nodo

Un Node rappresenta una posizione nominata nell’albero della scena. I nodi possono avere figli, formando una gerarchia. Ogni nodo possiede un locale Transform e un calcolato 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");

Puoi anche costruire nodi in modo indipendente e collegarli in seguito:

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

Entità e Mesh

Un Entity è una classe base astratta per qualsiasi cosa possa essere allegata a un nodo – geometria, telecamere e luci. Il tipo di entità più comune è Mesh, che contiene geometria poligonale (vertici, facce e normali).

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

Le camere sono entità che si collegano ai nodi:

Scene scene = new Scene();

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

Le definizioni delle camere vengono preservate durante l’esportazione in formati che le supportano (come glTF).

Nota: Il Light la classe non è disponibile nell’edizione Java. I dati di illuminazione della scena provenienti da file importati sono memorizzati come generici Entity oggetti.

Caricamento e Salvataggio Indipendenti dal Formato

Una delle forze della libreria è che il grafo della scena è indipendente dal formato. Carichi da qualsiasi formato supportato, manipoli la scena attraverso una singola API e salvi in qualsiasi formato supportato.

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

Il formato è determinato dall’estensione del file. Puoi anche passare opzioni di salvataggio esplicite per controllare l’output:

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

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

Materiali

Aspose.3D FOSS per Java fornisce un modello di materiale PBR (Physically Based Rendering) tramite PbrMaterial. Questa è l’unica classe di materiale concreta nell’edizione Java.

PbrMaterial

Un materiale di rendering basato fisicamente che utilizza i parametri albedo, metalness e roughness. Questo è il modello di materiale standard per glTF e i moderni motori in tempo reale.

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

La conservazione dei materiali tra i formati dipende dalle capacità del formato di destinazione. I materiali PBR si mappano naturalmente verso l’output glTF e GLB.

Transform e Spatial

Ogni Node nel grafo della scena ha un Transform che definisce la sua posizione, rotazione e scala rispetto al genitore.

Transform Locale

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 Globale

Il GlobalTransform è la trasformazione nello spazio mondiale calcolata, tenendo conto dell’intera catena dei genitori. È di sola lettura e si aggiorna automaticamente.

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

Questa eredità di trasformazione genitore-figlio segue il modello standard del grafo della scena utilizzato dai motori 3D e dagli strumenti DCC.

Utility Matematiche

La libreria include i tipi matematici di base per le operazioni 3D.

Vector3

Un vettore a tre componenti usato per posizioni, direzioni, normali e colori.

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

Una matrice di trasformazione 4x4 per combinare traslazione, rotazione e scala in un’unica operazione.

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

Quaternion

Una rappresentazione della rotazione che evita il gimbal lock e interpola in modo fluido. I quaternioni sono usati internamente dal sistema di trasformazione.

BoundingBox

Un bounding box allineato agli assi per query spaziali, controlli di collisione e analisi della scena.

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

Limitazioni note

Vale la pena notare che Scene.render() è non supportato nella versione FOSS. Chiamarlo genererà un UnsupportedOperationException. La libreria è progettata per l’elaborazione 3D basata su file — caricamento, trasformazione e salvataggio — piuttosto che per il rendering in tempo reale.

Riepilogo

Le caratteristiche principali di Aspose.3D FOSS per Java si suddividono in cinque aree:

Nel prossimo post, percorreremo tutorial pratici formato per formato che coprono OBJ, STL, glTF e FBX con opzioni dettagliate di caricamento e salvataggio.