Поддержка форматов

Aspose.3D FOSS для Python может читать и записывать семь 3D форматов, используя единственное представление сцены в памяти. Библиотека переводит каждый формат в общий Scene объект при загрузке и сериализует этот объект обратно в целевой формат при сохранении. Это означает, что сцена, загруженная из OBJ, может быть сохранена напрямую в glTF без каких-либо промежуточных шагов конвертации.

Поддерживаемые форматы

Формат	Расширение	Чтение	Запись	Класс параметров	Примечания
Wavefront OBJ	`.obj`	Да	Да	`ObjLoadOptions`	`.mtl` загрузка материалов поддерживается
STL (binary)	`.stl`	Да	Да	`StlSaveOptions`	Чтение в бинарном и ASCII; сохранение по умолчанию в бинарном
STL (ASCII)	`.stl`	Да	Да	`StlSaveOptions`	Круговой проход проверен
glTF 2.0	`.gltf`	Да	Да	`GltfSaveOptions`	Полный граф сцены, материалы и анимации сохранены
GLB (binary glTF)	`.glb`	Да	Да	`GltfSaveOptions`	Однофайловый бинарный контейнер
COLLADA	`.dae`	Да	Да	`ColladaLoadOptions` / `ColladaSaveOptions`	Иерархия сцены и материалы
3MF	`.3mf`	Да	Да	`ThreeMfSaveOptions`	Формат аддитивного производства
FBX	`.fbx`	Частичный	Нет	N/A	Токенизатор работает; полный парсер находится в разработке (не готов к продакшн)

Формат OBJ

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

ObjLoadOptions

Свойство	Тип	По умолчанию	Описание
`enable_materials`	`bool`	`True`	Разобрать `.mtl` файл, указанный в заголовке OBJ
`flip_coordinate_system`	`bool`	`False`	Преобразовать из правосторонней системы с осью Y‑вверх в правостороннюю систему с осью Z‑вверх
`normalize_normal`	`bool`	`True`	Нормализовать все импортированные нормали поверхностей до единичной длины
`scale`	`float`	`1.0`	Единый коэффициент масштабирования, применяемый ко всем позициям вершин

Загрузка файла 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 conversion), и анимационные клипы. 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")

Если расширение отсутствует или неоднозначно, библиотека переходит к проверке заголовка (магические байты). Неподдерживаемые или нераспознанные файлы вызывают 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() перед сохранением.