Ключевые особенности Aspose.3D FOSS для Java

В вводный пост, мы рассмотрели, что такое Aspose.3D FOSS для Java и как начать. Этот пост более подробно рассматривает ключевые возможности, составляющие библиотеку, с примерами кода для каждой области.

Все примеры предполагают следующий импорт:

import com.aspose.threed.*;

А также зависимость Maven:

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

API графа сцены

Граф сцены является основой Aspose.3D FOSS для Java. Каждый 3D‑модель — будь то загруженная из файла или построенная программно — представлена в виде дерева узлов, корневого в Scene объекте.

Scene

Этот Scene class является точкой входа для всех операций. Вы можете создать пустую сцену или загрузить её из файла:

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

Корень дерева узлов доступен через getRootNode().

Node

A Node представляет именованную позицию в дереве сцены. Узлы могут иметь дочерние элементы, образуя иерархию. Каждый узел несёт локальный Transform и вычисляемый 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");

Вы также можете создавать узлы независимо и присоединять их позже:

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

Entity и Mesh

An Entity является абстрактным базовым классом для всего, что может быть присоединено к узлу – геометрии, камер и источников света. Наиболее распространённый тип сущности — Mesh, который содержит полигональную геометрию (вершины, грани и нормали).

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

Камеры — это сущности, которые присоединяются к узлам:

Scene scene = new Scene();

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

Примечание: Класс Camera класс в издании Java является минимальной заглушкой, содержащей только конструкторы. Сущности камер, присоединённые к узлам, являются не записываются при экспорте в glTF или любой другой формат — экспортер glTF обрабатывает только Mesh объекты. Не полагайтесь на то, что данные камеры сохранятся в экспортированных файлах.

Примечание: Этот Light класс недоступен в издании Java. Данные освещения сцены из импортированных файлов хранятся как общие Entity объекты.

Загрузка и сохранение без привязки к формату

Одним из преимуществ библиотеки является то, что граф сцены не зависит от формата. Вы загружаете из любого поддерживаемого формата, манипулируете сценой через единый API и сохраняете в любой поддерживаемый формат.

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

Формат определяется расширением файла. Вы также можете передать явные параметры сохранения для управления выводом:

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

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

Материалы

Aspose.3D FOSS для Java предоставляет модель материала PBR (Physically Based Rendering) через PbrMaterial. Это единственный конкретный класс материала в издании Java.

PbrMaterial

Материал физически основанного рендеринга, использующий параметры альбедо, металлическость и шероховатость. Это стандартная модель материала для glTF и современных движков реального времени.

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

Сохранение материалов при конвертации между форматами зависит от возможностей целевого формата. PBR-материалы естественно сопоставляются с выводом в glTF и GLB.

Трансформ и Пространство

Каждый Node в графе сцены имеет 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

Глобальный трансформ

Этот GlobalTransform является вычисленным трансформом в мировом пространстве, учитывающим всю цепочку родителей. Это только для чтения и обновляется автоматически.

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

Это наследование трансформов родитель‑дитя следует стандартному паттерну графа сцены, используемому 3D‑движками и DCC‑инструментами.

Математические утилиты

Библиотека включает базовые математические типы для 3D‑операций.

Vector3

Вектор из трёх компонентов, используемый для позиций, направлений, нормалей и цветов.

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

Матрица преобразования 4×4, объединяющая перемещение, вращение и масштаб в одну операцию.

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

Quaternion

Представление вращения, которое избегает эффекта «запирания кардана» и обеспечивает плавную интерполяцию. Кватернионы используются внутри системы трансформаций.

BoundingBox

Ось‑выравненный BoundingBox для пространственных запросов, проверок столкновений и анализа сцены.

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

Примечание: Node.getBoundingBox() и Entity.getBoundingBox() ещё не реализованы. Оба возвращают пустой BoundingBox (с sentinel Double.MAX_VALUE / Double.MIN_VALUE значения) независимо от геометрии сетки. Не используйте эти методы для вычисления реальных границ геометрии в этой версии.

Известные ограничения

Стоит отметить, что Scene.render() является не поддерживается в версии FOSS. Вызов приведёт к выбросу UnsupportedOperationException. Библиотека предназначена для файловой 3D обработки – загрузки, преобразования и сохранения – а не для рендеринга в реальном времени.

Итоги

Ключевые возможности Aspose.3D FOSS для Java делятся на пять областей:

В следующем посте мы пройдём практические пошаговые руководства по каждому формату, охватывающие OBJ, STL, glTF и FBX, с подробными опциями загрузки и сохранения.