Suporte a Formatos

Aspose.3D FOSS para Python pode ler e gravar sete formatos 3D usando uma única representação de cena em memória. A biblioteca traduz cada formato para um objeto comum Scene ao carregar e serializa esse objeto de volta ao formato de destino ao salvar. Isso significa que uma cena carregada a partir de OBJ pode ser salva diretamente em glTF sem quaisquer etapas de conversão intermediárias.

Formatos Suportados

Formato OBJ

Wavefront OBJ é o formato de intercâmbio mais amplamente suportado para malhas estáticas. Aspose.3D FOSS carrega geometria (vértices, normais, coordenadas UV e faces poligonais) e, opcionalmente, o arquivo companheiro .mtl arquivo de material.

ObjLoadOptions

Carregando um arquivo 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)}")

Salvando em OBJ

scene.save("output.obj")

A exportação OBJ grava posições de vértices e faces de polígonos. Se a cena contiver LambertMaterial ou PhongMaterial objetos, a biblioteca grava um arquivo complementar .mtl arquivo automaticamente.

Formato STL

STL (STereoLithography) armazena malhas de triângulos como uma lista não indexada de facetas. Ambas as variantes binária e ASCII são suportadas para leitura; a biblioteca usa binário por padrão ao salvar.

StlSaveOptions

StlSaveOptions não tem campos obrigatórios. Instancie-o para passar para scene.save():

from aspose.threed.formats import StlSaveOptions

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

Exemplo de ida e volta

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 armazena apenas geometria de triângulos, sem normais além da normal da faceta, sem coordenadas UV, sem materiais e sem hierarquia. Se a sua cena contiver quads ou polígonos de ordem superior, eles são triangulados automaticamente ao salvar.

Formato glTF / GLB

glTF 2.0 é o formato recomendado para a troca moderna de 3D. Ele preserva o grafo completo da cena (hierarquia de nós, nós nomeados, transformações), materiais (LambertMaterial, PhongMaterial → conversão PBR), e clipes de animação. GLB é a variante de contêiner binário de arquivo único.

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

Suporte a materiais

Os materiais Aspose.3D FOSS são mapeados para glTF pbrMetallicRoughness na exportação:

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 a saída do 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) é um formato baseado em XML que suporta hierarquias de cena, materiais, múltiplos canais UV e animação esquelética. Aspose.3D FOSS lê e grava a árvore completa de nós e as definições de material.

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 é uma boa escolha quando você precisa fazer round‑trip de hierarquias com nós nomeados e materiais sem perda de dados.

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

Formato FBX

Status: em andamento (não pronto para produção).

FBX (.fbx) o suporte em Aspose.3D FOSS está atualmente na fase de tokenizador. O tokenizador binário FBX pode analisar a estrutura do arquivo, mas o analisador completo de nós, malhas e materiais tem bugs conhecidos e não está completo. Os resultados de leitura de FBX devem ser tratados como experimentais.

Não use FBX em pipelines de produção com esta versão. Se seus dados de origem estiverem em FBX, converta-os para glTF ou OBJ primeiro usando Blender ou FBX Review antes de carregá-los com Aspose.3D FOSS.

A gravação de FBX não é suportada.

Detecção automática de formato

Scene.from_file() e scene.open() detecta o formato automaticamente usando a extensão do arquivo e, quando disponível, os bytes mágicos no cabeçalho do arquivo:

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

Se a extensão estiver ausente ou ambígua, a biblioteca recorre à inspeção de cabeçalho (bytes mágicos). Arquivos não suportados ou não reconhecidos geram um IOError com uma mensagem descritiva.

Dicas e boas práticas

• Use glTF ou GLB para pipelines modernos. glTF preserva o grafo completo da cena, materiais e dados de animação. É o formato mais completo para intercâmbio com motores de jogo e visualizadores web.
• Use OBJ para máxima compatibilidade. OBJ é suportado por praticamente todas as ferramentas 3D. É limitado a malhas estáticas, mas é extremamente portátil.
• Use 3MF para impressão. 3MF carries colour, orientation hints, and print settings that STL cannot express.
• Evite FBX até que esteja pronto para produção. Verifique as notas de lançamento da versão em que o parsing completo de FBX está concluído.
• Combine a extensão de salvamento com o formato. Não passe um .gltf extensão quando você quer GLB binário; use .glb explicitamente. A extensão determina qual serialiser é usado.
• Verifique a compatibilidade de polígonos. STL e 3MF exigem triângulos. Quads e N-gons são triangulados automaticamente ao salvar, mas a contagem de vértices aumentará. Se precisar controlar a triangulação, chame mesh.triangulate() antes de salvar.