Prise en charge des formats

Aspose.3D FOSS pour Python peut lire et écrire sept formats 3D en utilisant une représentation de scène unique en mémoire. La bibliothèque traduit chaque format en un objet commun Scene lors du chargement et sérialise cet objet de nouveau vers le format cible lors de l’enregistrement. Cela signifie qu’une scène chargée depuis OBJ peut être enregistrée directement en glTF sans aucune étape de conversion intermédiaire.

Formats pris en charge

Format OBJ

Wavefront OBJ est le format d’échange le plus largement supporté pour les maillages statiques. Aspose.3D FOSS charge la géométrie (sommets, normales, coordonnées UV et faces polygonales) et éventuellement le compagnon .mtl fichier de matériau.

ObjLoadOptions

Chargement d’un fichier 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)}")

Enregistrement au format OBJ

scene.save("output.obj")

L’export OBJ écrit les positions des sommets et les faces polygonales. Si la scène contient LambertMaterial ou PhongMaterial objets, la bibliothèque écrit un fichier compagnon .mtl fichier automatiquement.

Format STL

STL (STereoLithography) stocke les maillages de triangles sous forme d’une liste non indexée de facettes. Les variantes binaire et ASCII sont toutes deux prises en charge en lecture ; la bibliothèque utilise le format binaire par défaut lors de l’enregistrement.

StlSaveOptions

StlSaveOptions n’a aucun champ obligatoire. Instanciez‑le pour le passer à scene.save():

from aspose.threed.formats import StlSaveOptions

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

Exemple de conversion aller-retour

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 ne stocke que la géométrie des triangles, sans normales autres que la normale de la facette, sans coordonnées UV, sans matériaux et sans hiérarchie. Si votre scène contient des quadrilatères ou des polygones de degré supérieur, ils sont automatiquement triangulés lors de l’enregistrement.

Format glTF / GLB

glTF 2.0 est le format recommandé pour l’échange 3D moderne. Il préserve le graphe complet de la scène (hiérarchie des nœuds, nœuds nommés, transformations), les matériaux (LambertMaterial, PhongMaterial → conversion PBR), et les clips d’animation. GLB est la variante du conteneur binaire à fichier unique.

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

Prise en charge des matériaux

Les matériaux Aspose.3D FOSS sont mappés à glTF pbrMetallicRoughness à l’exportation :

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

Vérification de la sortie 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) est un format basé sur XML qui prend en charge les hiérarchies de scène, les matériaux, plusieurs canaux UV et l’animation squelettique. Aspose.3D FOSS lit et écrit l’arborescence complète des nœuds ainsi que les définitions de matériaux.

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 est un bon choix lorsque vous devez effectuer un aller‑retour des hiérarchies avec des nœuds nommés et des matériaux sans aucune perte de données.

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

Statut : en cours (pas encore prêt pour la production).

FBX (.fbx) le support dans Aspose.3D FOSS est actuellement au stade du tokenizer. Le tokenizer binaire FBX peut analyser la structure du fichier, mais l’analyseur complet des nœuds, maillages et matériaux comporte des bugs connus et n’est pas complet. Les résultats de lecture FBX doivent être considérés comme expérimentaux.

N’utilisez pas le FBX dans les pipelines de production avec cette version. Si vos données sources sont au format FBX, convertissez‑les d’abord en glTF ou OBJ à l’aide de Blender ou de FBX Review avant de les charger avec Aspose.3D FOSS.

L’écriture FBX n’est pas prise en charge.

Détection automatique du format

Scene.from_file() et scene.open() détecte automatiquement le format en utilisant l’extension du fichier et, si disponible, les octets magiques dans l’en‑tête du fichier :

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

Si l’extension est absente ou ambiguë, la bibliothèque revient à l’inspection de l’en-tête (octets magiques). Les fichiers non pris en charge ou non reconnus lèvent une IOError avec un message descriptif.

Conseils et bonnes pratiques

• Utilisez glTF ou GLB pour les pipelines modernes. glTF préserve le graphe complet de la scène, les matériaux et les données d’animation. C’est le format le plus complet pour l’échange avec les moteurs de jeu et les visionneuses web.
• Utilisez OBJ pour une compatibilité maximale. OBJ est pris en charge par pratiquement tous les outils 3D. Il est limité aux maillages statiques mais est extrêmement portable.
• Utilisez 3MF pour l’impression. 3MF carries colour, orientation hints, and print settings that STL cannot express.
• Évitez FBX tant qu’il n’est pas prêt pour la production. Vérifiez les notes de version pour la version dans laquelle l’analyse complète de FBX est terminée.
• Faites correspondre l’extension de sauvegarde au format. Ne passez pas un .gltf extension lorsque vous voulez un GLB binaire; utilisez .glb explicitement. L’extension détermine quel sérialiseur est utilisé.
• Vérifiez la compatibilité des polygones. STL et 3MF nécessitent des triangles. Les quadrilatères et les N-gones sont triangulés automatiquement lors de l’enregistrement, mais le nombre de sommets augmentera. Si vous devez contrôler la triangulation, appelez mesh.triangulate() avant d’enregistrer.