Підтримка форматів

Aspose.3D FOSS для Python може читати та записувати сім 3D‑форматів, використовуючи єдине представлення сцени в пам’яті. Бібліотека перетворює кожен формат у спільний Scene об’єкт під час завантаження і серіалізує цей об’єкт назад у цільовий формат під час збереження. Це означає, що сцена, завантажена з OBJ, може бути збережена безпосередньо у glTF без будь‑яких проміжних кроків конвертації.

Підтримувані формати

Формат OBJ

Wavefront OBJ — найширше підтримуваний формат обміну для статичних сіток. Aspose.3D FOSS завантажує геометрію (вершини, нормалі, UV‑координати та полігональні грані) і, за потреби, супровідний .mtl файл матеріалу.

ObjLoadOptions

Завантаження файлу OBJ

from aspose.threed import Scene
from aspose.threed.formats import ObjLoadOptions

options = ObjLoadOptions()
options.enable_materials = True
options.flip_coordinate_system = False
options.scale = 1.0

scene = Scene()
scene.open("model.obj", options)

print(f"Top-level nodes: {len(scene.root_node.child_nodes)}")

Збереження у OBJ

scene.save("output.obj")

Експорт у формат OBJ записує позиції вершин та полігональні грані. Якщо сцена містить LambertMaterial або PhongMaterial об’єкти, бібліотека автоматично створює супутній .mtl файл автоматично.

Формат STL

STL (STereoLithography) зберігає трикутні сітки як неіндексований список граней. Підтримуються як бінарні, так і ASCII варіанти для читання; при збереженні бібліотека за замовчуванням використовує бінарний формат.

StlSaveOptions

StlSaveOptions не має обов’язкових полів. Створіть його, щоб передати до scene.save():

from aspose.threed.formats import StlSaveOptions

opts = StlSaveOptions()
scene.save("output.stl", opts)

Приклад кругового проходу

from aspose.threed import Scene

##Load
scene = Scene.from_file("model.stl")

##Inspect
for node in scene.root_node.child_nodes:
    if node.entity:
        print(f"{node.name}: {len(node.entity.control_points)} vertices")

##Save
scene.save("roundtrip.stl")

STL зберігає лише трикутну геометрію, без нормалей, окрім нормалі грані, без UV‑координат, без матеріалів і без ієрархії. Якщо ваша сцена містить квадрати або полігони вищого порядку, вони автоматично триангуляються під час збереження.

Формат glTF / GLB

glTF 2.0 — це рекомендований формат для сучасного обміну 3D-даними. Він зберігає повний граф сцени (ієрархію вузлів, іменовані вузли, трансформації), матеріали (LambertMaterial, PhongMaterial → конверсія PBR), та анімаційні кліпи. GLB — це варіант однорядкового бінарного контейнера.

GltfSaveOptions

from aspose.threed.formats import GltfSaveOptions

opts = GltfSaveOptions()
scene.save("output.gltf", opts)   # JSON + external .bin
scene.save("output.glb",  opts)   # Self-contained binary

Підтримка матеріалів

Aspose.3D FOSS матеріали відображаються у glTF pbrMetallicRoughness при експорті:

from aspose.threed import Scene
from aspose.threed.shading import PhongMaterial
from aspose.threed.utilities import Vector3

scene = Scene()
node = scene.root_node.create_child_node("object")

mat = PhongMaterial()
mat.diffuse_color  = Vector3(0.8, 0.2, 0.2)   # red
mat.specular_color = Vector3(1.0, 1.0, 1.0)
mat.shininess = 50.0
node.material = mat

scene.save("colored.gltf")

Перевірка вихідного glTF

import json

with open("output.gltf") as f:
    data = json.load(f)

print(f"Asset version : {data['asset']['version']}")
print(f"Nodes         : {len(data.get('nodes', []))}")
print(f"Meshes        : {len(data.get('meshes', []))}")

Формат COLLADA

COLLADA (.dae) є форматом на основі XML, який підтримує ієрархії сцен, матеріали, кілька UV‑каналів та скелетну анімацію. Aspose.3D FOSS читає і записує повне дерево вузлів та визначення матеріалів.

from aspose.threed import Scene

##Load a COLLADA file
scene = Scene.from_file("model.dae")

##Inspect top-level nodes
for node in scene.root_node.child_nodes:
    print(f"  {node.name}")

##Save back to COLLADA
scene.save("output.dae")

COLLADA — хороший вибір, коли вам потрібно здійснювати круговий обмін ієрархіями з іменованими вузлами та матеріалами без будь‑якої втрати даних.

3MF Format

3MF (3D Manufacturing Format) targets additive manufacturing (3D printing) workflows. It stores triangle geometry, colour, and print-specific metadata in a ZIP-based container.

from aspose.threed import Scene
from aspose.threed.formats import ThreeMfSaveOptions

scene = Scene.from_file("part.stl")   # Load from STL
opts  = ThreeMfSaveOptions()
scene.save("part.3mf", opts)          # Write as 3MF

3MF is the recommended export format when targeting slicer software (Cura, PrusaSlicer, Bambu Studio, etc.).

Формат FBX

Статус: у процесі (не готовий до продакшну).

FBX (.fbx) підтримка у Aspose.3D FOSS наразі знаходиться на етапі токенізатора. Бінарний токенізатор FBX може розбирати структуру файлу, але повний парсер вузлів, сіток та матеріалів має відомі помилки і не завершений. Результати читання FBX слід розглядати як експериментальні.

Не використовуйте FBX у виробничих конвеєрах з цим випуском. Якщо ваші вихідні дані у форматі FBX, спочатку конвертуйте їх у glTF або OBJ за допомогою Blender або FBX Review перед завантаженням у Aspose.3D FOSS.

Запис у FBX не підтримується.

Автоматичне визначення формату

Scene.from_file() і scene.open() виявляє формат автоматично, використовуючи розширення файлу та, за наявності, магічні байти у заголовку файлу:

from aspose.threed import Scene

##The library detects each format without being told explicitly
scene_obj  = Scene.from_file("model.obj")
scene_glb  = Scene.from_file("model.glb")
scene_stl  = Scene.from_file("model.stl")
scene_dae  = Scene.from_file("model.dae")
scene_3mf  = Scene.from_file("model.3mf")

Якщо розширення відсутнє або неоднозначне, бібліотека переходить до перевірки заголовка (магічні байти). Непідтримувані або нерозпізнані файли викликають an IOError з описовим повідомленням.

Поради та найкращі практики

• Використовуйте glTF або GLB для сучасних конвеєрів. glTF зберігає повний граф сцени, матеріали та дані анімації. Це найповніший формат для обміну з ігровими рушіями та веб‑переглядачами.
• Використовуйте OBJ для максимальної сумісності. OBJ підтримується практично будь-яким 3D‑інструментом. Він обмежений статичними сітками, але надзвичайно портативний.
• Використовуйте 3MF для друку. 3MF carries colour, orientation hints, and print settings that STL cannot express.
• Уникайте FBX, доки він не буде готовий до продакшну. Перевірте нотатки до випуску, щоб дізнатися, у якій версії повний парсинг FBX завершений.
• Підбирайте розширення файлу до формату. Не передавайте .gltf розширення, коли потрібен бінарний GLB; використовуйте .glb явно. Розширення визначає, який серіалізатор використовується.
• Перевірте сумісність полігонів. STL та 3MF вимагають трикутників. Четвертогранники та N‑грони автоматично триангуються під час збереження, але кількість вершин збільшується. Якщо потрібно контролювати триангуляцію, викличте mesh.triangulate() перед збереженням.