Key Features of Aspose.3D FOSS for Java

In the introduction post, we covered what Aspose.3D FOSS for Java is and how to get started. This post goes deeper into the key features that make up the library, with code examples for each area.

All examples assume the following import:

import com.aspose.threed.*;

And the Maven dependency:

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

Scene Graph API

The scene graph is the foundation of Aspose.3D FOSS for Java. Every 3D model – whether loaded from a file or built programmatically – is represented as a tree of nodes rooted in a Scene object.

Scene

The Scene class is the entry point for all operations. You can create an empty scene or load one from a 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());

The root of the node tree is accessed via getRootNode().

Node

A Node represents a named position in the scene tree. Nodes can have children, forming a hierarchy. Each node carries a local Transform and a computed 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");

You can also construct nodes independently and attach them later:

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

Entity and Mesh

An Entity is an abstract base class for anything that can be attached to a node – geometry, cameras, and lights. The most common entity type is Mesh, which holds polygonal geometry (vertices, faces, and normals).

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

Cameras are entities that attach to nodes:

Scene scene = new Scene();

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

Camera definitions are preserved when exporting to formats that support them (such as glTF).

Note: The Light class is not available in the Java edition. Scene lighting data from imported files is stored as generic Entity objects.

Format-Agnostic Load and Save

One of the strengths of the library is that the scene graph is format-independent. You load from any supported format, manipulate the scene through a single API, and save to any supported 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);

The format is determined by the file extension. You can also pass explicit save options to control the output:

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

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

Materials

Aspose.3D FOSS for Java provides a PBR (Physically Based Rendering) material model via PbrMaterial. This is the only concrete material class in the Java edition.

PbrMaterial

A physically based rendering material that uses albedo, metalness, and roughness parameters. This is the standard material model for glTF and modern real-time engines.

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

Material preservation across formats depends on the capabilities of the target format. PBR materials map naturally to glTF and GLB output.

Transform and Spatial

Every Node in the scene graph has a Transform that defines its position, rotation, and scale relative to its parent.

Local 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

The GlobalTransform is the computed world-space transform, taking the entire parent chain into account. This is read-only and updates automatically.

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

This parent-child transform inheritance follows the standard scene-graph pattern used by 3D engines and DCC tools.

Math Utilities

The library includes core math types for 3D operations.

Vector3

A three-component vector used for positions, directions, normals, and colors.

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

A 4x4 transformation matrix for combining translation, rotation, and scale into a single operation.

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

Quaternion

A rotation representation that avoids gimbal lock and interpolates smoothly. Quaternions are used internally by the transform system.

BoundingBox

An axis-aligned bounding box for spatial queries, collision checks, and scene analysis.

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

Known Limitations

It is worth noting that Scene.render() is not supported in the FOSS edition. Calling it will throw an UnsupportedOperationException. The library is designed for file-based 3D processing – loading, transforming, and saving – rather than real-time rendering.

Summary

The key features of Aspose.3D FOSS for Java break down into five areas:

In the next post, we will walk through practical format-by-format tutorials covering OBJ, STL, glTF, and FBX with detailed load and save options.