Aspose.3D FOSS
Python
Przewodnik programisty
Obsługa formatów

Obsługa formatów

Aspose.3D FOSS dla Python może odczytywać i zapisywać siedem formatów 3D przy użyciu jednej reprezentacji sceny w pamięci. Biblioteka tłumaczy każdy format na wspólny Scene obiekt przy ładowaniu i serializuje ten obiekt z powrotem do docelowego formatu przy zapisie. Oznacza to, że scena załadowana z OBJ może być zapisana bezpośrednio do glTF bez żadnych pośrednich kroków konwersji.

Obsługiwane formaty

FormatRozszerzenieOdczytZapisKlasa opcjiUwagi
Wavefront OBJ.objTakTakObjLoadOptions.mtl obsługa ładowania materiału
STL (binarny).stlTakTakStlSaveOptionsOdczyt binarny i ASCII; zapisywanie domyślnie w trybie binarnym
STL (ASCII).stlTakTakStlSaveOptionsZweryfikowano pełny cykl
glTF 2.0.gltfTakTakGltfSaveOptionsPełny graf sceny, materiały i animacje zachowane
GLB (binary glTF).glbTakTakGltfSaveOptionsJednoplikowy kontener binarny
COLLADA.daeTakTakColladaLoadOptions / ColladaSaveOptionsHierarchia sceny i materiały
3MF.3mfTakTakThreeMfSaveOptionsFormat produkcji przyrostowej
FBX.fbxCzęściowyNieN/ATokenizer działa; pełny parser jest w trakcie tworzenia (nie gotowy do produkcji)

Format OBJ

Wavefront OBJ jest najpowszechniej wspieranym formatem wymiany dla statycznych siatek. Aspose.3D FOSS wczytuje geometrię (wierzchołki, normalne, współrzędne UV oraz wielokątne twarze) i opcjonalnie towarzyszący .mtl plik materiałowy.

ObjLoadOptions

WłaściwośćTypDomyślneOpis
enable_materialsboolTrueParsuj .mtl plik odwoływany przez nagłówek OBJ
flip_coordinate_systemboolFalseKonwertuj z Y-up prawoskrętnego na Z-up prawoskrętny
normalize_normalboolTrueZnormalizuj wszystkie zaimportowane wektory normalne powierzchni do długości jednostkowej
scalefloat1.0Jednolity współczynnik skalowania zastosowany do wszystkich pozycji wierzchołków

Ładowanie pliku 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)}")

Zapisywanie do OBJ 

scene.save("output.obj")

Eksport OBJ zapisuje pozycje wierzchołków i ściany wielokątne. Jeśli scena zawiera LambertMaterial lub PhongMaterial obiekty, biblioteka zapisuje towarzyszący .mtl plik automatycznie.

Format STL

STL (STereoLithography) przechowuje siatki trójkątne jako nieindeksowaną listę faset. Obsługiwane są zarówno wersje binarne, jak i ASCII przy odczycie; biblioteka domyślnie zapisuje w formacie binarnym.

StlSaveOptions

StlSaveOptions nie ma obowiązkowych pól. Utwórz jego instancję, aby przekazać do scene.save():

from aspose.threed.formats import StlSaveOptions

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

Przykład round‑trip 

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 przechowuje wyłącznie geometrię trójkątów, bez normalnych poza normalną fasety, bez współrzędnych UV, bez materiałów i bez hierarchii. Jeśli twoja scena zawiera czworokąty lub wielokąty wyższego rzędu, są one automatycznie triangulowane przy zapisie.

Format glTF / GLB

glTF 2.0 jest zalecanym formatem dla nowoczesnej wymiany 3D. Zachowuje pełny graf sceny (hierarchię węzłów, nazwane węzły, przekształcenia), materiały (LambertMaterial, PhongMaterial → konwersja PBR), oraz klipy animacji. GLB jest jednoplikową binarną wersją kontenera.

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

Obsługa materiałów

Materiały Aspose.3D FOSS są mapowane na glTF pbrMetallicRoughness przy eksporcie:

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

Weryfikacja wyjścia 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', []))}")

Format COLLADA

COLLADA (.dae) jest formatem opartym na XML, który obsługuje hierarchie scen, materiały, wiele kanałów UV oraz animację szkieletową. Aspose.3D FOSS odczytuje i zapisuje pełne drzewo węzłów oraz definicje materiałów.

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 jest dobrym wyborem, gdy potrzebujesz dwukierunkowego przenoszenia hierarchii z nazwanymi węzłami i materiałami bez utraty danych.

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

Format FBX

Status: w trakcie (nie gotowy do produkcji).

FBX (.fbx) wsparcie w Aspose.3D FOSS znajduje się obecnie w fazie tokenizera. Binarny tokenizator FBX potrafi parsować strukturę pliku, ale pełny parser węzłów, siatek i materiałów ma znane błędy i nie jest kompletny. Wyniki odczytu FBX należy traktować jako eksperymentalne.

Nie używaj FBX w produkcyjnych pipeline’ach w tej wersji. Jeśli Twoje dane źródłowe są w formacie FBX, najpierw skonwertuj je do glTF lub OBJ przy użyciu Blendera lub FBX Review przed załadowaniem do Aspose.3D FOSS.

Zapisywanie w formacie FBX nie jest obsługiwane.

Automatyczne wykrywanie formatu

Scene.from_file() i scene.open() automatycznie wykrywa format przy użyciu rozszerzenia pliku oraz, jeśli dostępne, magicznych bajtów w nagłówku pliku:

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

Jeśli rozszerzenie jest nieobecne lub niejednoznaczne, biblioteka przechodzi do inspekcji nagłówka (magic bytes). Nieobsługiwane lub nierozpoznane pliki generują IOError z opisowym komunikatem.

Wskazówki i najlepsze praktyki

  • Używaj glTF lub GLB w nowoczesnych pipeline’ach. glTF zachowuje pełny graf sceny, materiały i dane animacji. Jest to najbardziej kompletny format wymiany z silnikami gier i przeglądarkami internetowymi.
  • Użyj OBJ dla maksymalnej kompatybilności. OBJ jest obsługiwany praktycznie przez każde narzędzie 3D. Jest ograniczony do statycznych siatek, ale jest niezwykle przenośny.
  • Użyj 3MF do druku. 3MF carries colour, orientation hints, and print settings that STL cannot express.
  • Unikaj FBX, dopóki nie będzie gotowy do produkcji. Sprawdź notatki wydania, aby dowiedzieć się, w której wersji pełne parsowanie FBX jest zakończone.
  • Dopasuj rozszerzenie zapisu do formatu. Nie przekazuj a .gltf rozszerzenie, gdy chcesz binarny GLB; użyj .glb jawnie. Rozszerzenie określa, który serialiser jest używany.
  • Sprawdź kompatybilność wielokątów. STL i 3MF wymagają trójkątów. Czworokąty i N‑gony są automatycznie triangulowane przy zapisie, ale liczba wierzchołków wzrośnie. Jeśli potrzebujesz kontrolować triangulację, wywołaj mesh.triangulate() przed zapisem.
 Polski