Soporte de formatos

Aspose.3D FOSS for Python puede leer y escribir siete formatos 3D usando una única representación de escena en memoria. La biblioteca traduce cada formato a un objeto Scene común al cargar y serializa ese objeto de nuevo al formato de destino al guardar. Esto significa que una escena cargada desde OBJ puede guardarse directamente en glTF sin pasos intermedios de conversión.

Formatos compatibles

Formato OBJ

Wavefront OBJ es el formato de intercambio más ampliamente soportado para mallas estáticas. Aspose.3D FOSS carga la geometría (vértices, normales, coordenadas UV y caras poligonales) y, opcionalmente, el archivo de material complementario .mtl.

ObjLoadOptions

Cargando un archivo 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)}")

Guardando en OBJ

scene.save("output.obj")

La exportación OBJ escribe posiciones de vértices y caras de polígonos. Si la escena contiene objetos LambertMaterial o PhongMaterial, la biblioteca escribe automáticamente un archivo complementario .mtl.

Formato STL

STL (STereoLithography) almacena mallas de triángulos como una lista no indexada de facetas. Tanto las variantes binarias como ASCII son compatibles para la lectura; la biblioteca usa binario por defecto al guardar.

StlSaveOptions

StlSaveOptions no tiene campos obligatorios. Instáncialo para pasarlo a scene.save():

from aspose.threed.formats import StlSaveOptions

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

Ejemplo de ida y vuelta

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 almacena solo geometría de triángulos, sin normales más allá de la normal de la faceta, sin coordenadas UV, sin materiales y sin jerarquía. Si tu escena contiene cuadriláteros o polígonos de orden superior, se triangulan automáticamente al guardar.

glTF / GLB Formato

glTF 2.0 es el formato recomendado para el intercambio 3D moderno. Preserva el grafo de escena completo (jerarquía de nodos, nodos con nombre, transformaciones), materiales (LambertMaterial, PhongMaterial → conversión a PBR) y clips de animación. GLB es la variante de contenedor binario de un solo archivo.

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

Soporte de material

Los materiales FOSS de Aspose.3D se asignan a glTF pbrMetallicRoughness al exportar:

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

Verificando la salida 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', []))}")

Formato COLLADA

COLLADA (.dae) es un formato basado en XML que admite jerarquías de escena, materiales, múltiples canales UV y animación esquelética. Aspose.3D FOSS lee y escribe el árbol de nodos completo y las definiciones de materiales.

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 es una buena opción cuando necesitas hacer un round‑trip de jerarquías con nodos nombrados y materiales sin pérdida de datos.

3MF Formato

3MF (Formato de Fabricación 3D) está dirigido a flujos de trabajo de fabricación aditiva (impresión 3D). Almacena la geometría de triángulos, el color y los metadatos específicos de impresión en un contenedor basado en ZIP.

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 es el formato de exportación recomendado al dirigirse a software de laminado (Cura, PrusaSlicer, Bambu Studio, etc.).

Formato FBX

Estado: en progreso (no listo para producción).

El soporte de FBX (.fbx) en Aspose.3D FOSS está actualmente en la etapa de tokenizador. El tokenizador binario de FBX puede analizar la estructura del archivo, pero el analizador completo de nodos, mallas y materiales tiene errores conocidos y no está completo. Los resultados de lectura de FBX deben considerarse experimentales.

No use FBX en pipelines de producción con esta versión. Si sus datos de origen están en FBX, conviértalos a glTF u OBJ primero usando Blender o FBX Review antes de cargarlos con Aspose.3D FOSS.

La escritura de FBX no es compatible.

Detección automática de formato

Scene.from_file() y scene.open() detectan el formato automáticamente usando la extensión del archivo y, cuando está disponible, los bytes mágicos en el encabezado del archivo:

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 la extensión está ausente o es ambigua, la biblioteca recurre a la inspección de encabezados (bytes mágicos). Los archivos no compatibles o no reconocidos generan un IOError con un mensaje descriptivo.

Consejos y Mejores Prácticas

• Use glTF o GLB para pipelines modernos. glTF preserva el grafo completo de la escena, los materiales y los datos de animación. Es el formato más completo para el intercambio con motores de juego y visores web.
• Use OBJ para máxima compatibilidad. OBJ es compatible con prácticamente todas las herramientas 3D. Está limitado a mallas estáticas pero es extremadamente portátil.
• Use 3MF para impresión. 3MF lleva color, indicaciones de orientación y configuraciones de impresión que STL no puede expresar.
• Evite FBX hasta que esté listo para producción. Consulte las notas de la versión para saber en qué versión el análisis completo de FBX está completo.
• Haga coincidir la extensión de guardado con el formato. No pase una extensión .gltf cuando desee GLB binario; use .glb explícitamente. La extensión determina qué serializador se utiliza.
• Verifique la compatibilidad de polígonos. STL y 3MF requieren triángulos. Los cuádruplos y N‑gons se triangulan automáticamente al guardar, pero el recuento de vértices aumentará. Si necesita controlar la triangulación, llame a mesh.triangulate() antes de guardar.