Podpora formátů

Aspose.3D FOSS pro Python dokáže číst a zapisovat sedm 3D formátů pomocí jediné reprezentace scény v paměti. Knihovna převádí každý formát do společného Scene objektu při načtení a serializuje tento objekt zpět do cílového formátu při uložení. To znamená, že scéna načtená z OBJ může být uložena přímo do glTF bez jakýchkoli mezikroků konverze.

Podporované formáty

Formát OBJ

Wavefront OBJ je nejrozšířenější formát pro výměnu statických sítí. Aspose.3D FOSS načítá geometrii (vrcholy, normály, UV souřadnice a polygonální plochy) a volitelně také doprovodný .mtl soubor materiálu.

ObjLoadOptions

Načítání souboru 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)}")

Ukládání do OBJ

scene.save("output.obj")

Export OBJ zapisuje pozice vrcholů a polygonové plochy. Pokud scéna obsahuje LambertMaterial nebo PhongMaterial objekty, knihovna zapíše doprovodný .mtl soubor automaticky.

Formát STL

STL (STereoLithography) ukládá trojúhelníkové sítě jako neindexovaný seznam faset. Pro čtení jsou podporovány jak binární, tak ASCII varianty; knihovna při ukládání standardně používá binární formát.

StlSaveOptions

StlSaveOptions nemá žádná povinná pole. Vytvořte jej, abyste jej předali do scene.save():

from aspose.threed.formats import StlSaveOptions

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

Příklad 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 ukládá pouze trojúhelníkovou geometrii, bez normál kromě normály fasety, bez UV souřadnic, bez materiálů a bez hierarchie. Pokud vaše scéna obsahuje čtyřúhelníky nebo polygonální tvary vyššího řádu, jsou při ukládání automaticky triangulovány.

Formát glTF / GLB

glTF 2.0 je doporučený formát pro moderní výměnu 3D dat. Zachovává kompletní graf scény (hierarchii uzlů, pojmenované uzly, transformace), materiály (LambertMaterial, PhongMaterial → převod na PBR), a animační klipy. GLB je varianta jednosouborového binárního kontejneru.

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

Podpora materiálů

Aspose.3D FOSS materiály jsou mapovány na glTF pbrMetallicRoughness při exportu:

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

Ověřování výstupu 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', []))}")

Formát COLLADA

COLLADA (.dae) je formát založený na XML, který podporuje hierarchie scén, materiály, více UV kanálů a skeletální animaci. Aspose.3D FOSS čte a zapisuje celý strom uzlů a definice materiálů.

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 je dobrá volba, když potřebujete provádět round‑trip hierarchie s pojmenovanými uzly a materiály bez jakékoli ztráty dat.

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

Formát FBX

Stav: ve vývoji (není připraveno pro produkci).

FBX (.fbx) podpora v Aspose.3D FOSS je v současné době ve fázi tokenizéru. Binární tokenizér FBX dokáže analyzovat strukturu souboru, ale kompletní parser uzlů, sítí a materiálů má známé chyby a není kompletní. Výsledky čtení FBX by měly být považovány za experimentální.

Nepoužívejte FBX v produkčních pipelinech s tímto vydáním. Pokud jsou vaše zdrojová data ve formátu FBX, nejprve je převeďte na glTF nebo OBJ pomocí Blenderu nebo FBX Review, než je načtete pomocí Aspose.3D FOSS.

Zápis FBX není podporován.

Automatické rozpoznávání formátu

Scene.from_file() a scene.open() detekuje formát automaticky pomocí přípony souboru a, pokud je k dispozici, magických bajtů v hlavičce souboru:

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

Pokud chybí přípona nebo je nejednoznačná, knihovna se vrátí k inspekci hlavičky (magické bajty). Nepodporované nebo nerozpoznané soubory vyvolají IOError s popisnou zprávou.

Tipy a osvědčené postupy

• Použijte glTF nebo GLB pro moderní pipeliney. glTF zachovává kompletní graf scén, materiály a animační data. Je to nejkompletnější formát pro výměnu s herními enginy a webovými prohlížeči.
• Použijte OBJ pro maximální kompatibilitu. OBJ je podporován prakticky každým 3D nástrojem. Je omezen na statické sítě, ale je mimořádně přenosný.
• Použijte 3MF pro tisk. 3MF carries colour, orientation hints, and print settings that STL cannot express.
• Vyhněte se FBX, dokud nebude připravený pro produkci. Zkontrolujte poznámky k vydání pro verzi, ve které je úplné parsování FBX dokončeno.
• Přizpůsobte příponu souboru formátu. Nezadejte .gltf příponu, když chcete binární GLB; použijte .glb explicitně. Přípona určuje, který serializér se použije.
• Zkontrolujte kompatibilitu polygonů. STL a 3MF vyžadují trojúhelníky. Čtyřúhelníky a N-gony jsou při uložení automaticky triangulovány, ale počet vrcholů se zvýší. Pokud potřebujete řídit triangulaci, zavolejte mesh.triangulate() před uložením.