Ключові особливості 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 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().

Вузол

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

Сутність та сітка

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

Камера

Камери — це сутності, які приєднуються до вузлів:

Scene scene = new Scene();

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

Визначення камер зберігаються при експорті у формати, які їх підтримують (наприклад, glTF).

Примітка: Клас 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

Матриця трансформації 4x4, що об’єднує переміщення, обертання та масштаб в одну операцію.

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

Quaternion

Представлення обертання, яке уникає gimbal lock та плавно інтерполює. Кватерніони використовуються внутрішньо системою трансформації.

BoundingBox

Вісь-орієнтований обмежувальний короб для просторових запитів, перевірок колізій та аналізу сцени.

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

Відомі обмеження

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

Підсумок

Ключові особливості Aspose.3D FOSS для Java розбиваються на п’ять напрямків:

У наступному дописі ми пройдемо практичні покрокові підручники по кожному формату, охоплюючи OBJ, STL, glTF та FBX, з детальними параметрами завантаження та збереження.