Principais recursos de Aspose.3D FOSS para Java

No post de introdução, abordamos o que Aspose.3D FOSS for Java é e como começar. Este post aprofunda os recursos principais que compõem a biblioteca, com exemplos de código para cada área.

Todos os exemplos assumem a seguinte importação:

import com.aspose.threed.*;

E a dependência Maven:

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

API de Grafo de Cena

O grafo de cena é a base do Aspose.3D FOSS for Java. Cada modelo 3D — seja carregado de um arquivo ou construído programaticamente — é representado como uma árvore de nós enraizada em um Scene objeto.

Cena

A Scene classe é o ponto de entrada para todas as operações. Você pode criar uma cena vazia ou carregar uma a partir de um arquivo:

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

A raiz da árvore de nós é acessada via getRootNode().

Nó

Um Node representa uma posição nomeada na árvore de cena. Nós podem ter filhos, formando uma hierarquia. Cada nó carrega um local Transform e um calculado 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");

Você também pode construir nós de forma independente e anexá‑los posteriormente:

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

Entidade e Malha

Um Entity é uma classe base abstrata para qualquer coisa que possa ser anexada a um nó – geometria, câmeras e luzes. O tipo de entidade mais comum é Mesh, que contém geometria poligonal (vértices, faces e normais).

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

Câmera

Câmeras são entidades que se anexam a nós:

Scene scene = new Scene();

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

As definições de câmera são preservadas ao exportar para formatos que as suportam (como glTF).

Nota: O Light classe não está disponível na edição Java. Dados de iluminação da cena de arquivos importados são armazenados como genéricos Entity objetos.

Carregamento e Salvamento Independentes de Formato

Uma das forças da biblioteca é que o grafo de cena é independente de formato. Você carrega de qualquer formato suportado, manipula a cena através de uma única API e salva em qualquer formato suportado.

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

O formato é determinado pela extensão do arquivo. Você também pode passar opções de salvamento explícitas para controlar a saída:

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

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

Materiais

Aspose.3D FOSS para Java fornece um modelo de material PBR (Physically Based Rendering) via PbrMaterial. Esta é a única classe de material concreta na edição Java.

PbrMaterial

Um material de renderização baseada em física que usa parâmetros de albedo, metalicidade e rugosidade. Este é o modelo de material padrão para glTF e motores modernos em tempo real.

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

A preservação de materiais entre formatos depende das capacidades do formato de destino. Materiais PBR mapeiam naturalmente para a saída glTF e GLB.

Transform e Spatial

Cada Node no grafo de cena tem um Transform que define sua posição, rotação e escala em relação ao seu pai.

Transformação Local

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

Transformação Global

O GlobalTransform é a transformação calculada no espaço mundial, levando em conta toda a cadeia de pais. Isso é somente leitura e é atualizado 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();

Essa herança de transformações pai‑filho segue o padrão de grafo de cena usado por motores 3D e ferramentas DCC.

Utilitários Matemáticos

A biblioteca inclui tipos matemáticos essenciais para operações 3D.

Vector3

Um vetor de três componentes usado para posições, direções, normais e cores.

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

Uma matriz de transformação 4x4 para combinar translação, rotação e escala em uma única operação.

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

Quaternion

Uma representação de rotação que evita o gimbal lock e interpola suavemente. Quaternions são usados internamente pelo sistema de transformações.

BoundingBox

Uma caixa delimitadora alinhada aos eixos para consultas espaciais, verificações de colisão e análise de cena.

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

Limitações Conhecidas

Vale notar que Scene.render() é não suportado na edição FOSS. Chamá‑lo lançará um UnsupportedOperationException. A biblioteca foi projetada para processamento 3D baseado em arquivos — carregamento, transformação e salvamento — em vez de renderização em tempo real.

Resumo

Os principais recursos de Aspose.3D FOSS para Java se dividem em cinco áreas:

No próximo post, percorreremos tutoriais práticos formato a formato cobrindo OBJ, STL, glTF e FBX com opções detalhadas de carregamento e salvamento.