Come caricare modelli 3D in Python

Aspose.3D FOSS for Python fornisce un’API semplice per aprire file 3D senza dipendenze native. Dopo aver caricato un file in un oggetto Scene, è possibile attraversare la gerarchia dei nodi e leggere i dati di geometria grezzi per ogni mesh nella scena.

Guida passo-passo

pip install aspose-3d-foss

from aspose.threed import Scene
from aspose.threed.formats import ObjLoadOptions

##Automatic format detection
scene = Scene.from_file("model.obj")

scene = Scene()
scene.open("model.obj")

from aspose.threed import Scene, Node

scene = Scene.from_file("model.obj")

def walk(node: Node, depth: int = 0) -> None:
    indent = "  " * depth
    print(f"{indent}Node: {node.name!r}")
    for child in node.child_nodes:
        walk(child, depth + 1)

walk(scene.root_node)

from aspose.threed import Scene
from aspose.threed.entities import Mesh

scene = Scene.from_file("model.obj")

for node in scene.root_node.child_nodes:
    for entity in node.entities:
        if isinstance(entity, Mesh):
            mesh: Mesh = entity
            print(f"Mesh '{node.name}': "
                  f"{len(mesh.control_points)} vertices, "
                  f"{len(mesh.polygons)} polygons")

            # First vertex position
            if mesh.control_points:
                v = mesh.control_points[0]
                print(f"  First vertex: ({v.x:.4f}, {v.y:.4f}, {v.z:.4f})")

            # First polygon face (list of control-point indices)
            if mesh.polygons:
                print(f"  First polygon: {mesh.polygons[0]}")

from aspose.threed import Scene
from aspose.threed.formats import ObjLoadOptions

options = ObjLoadOptions()
options.flip_coordinate_system = True   # Convert right-hand Y-up to Z-up
options.scale = 0.01                    # Convert centimetres to metres
options.enable_materials = True         # Load .mtl material file
options.normalize_normal = True         # Normalize all normals to unit length

scene = Scene()
scene.open("model.obj", options)

Problemi comuni e soluzioni

FileNotFoundError quando si chiama Scene.from_file()

Il percorso deve essere assoluto o corretto relativo alla directory di lavoro al runtime. Usa pathlib.Path per costruire percorsi affidabili:

from pathlib import Path
from aspose.threed import Scene

path = Path(__file__).parent / "assets" / "model.obj"
scene = Scene.from_file(str(path))

mesh.polygons è vuoto dopo il caricamento di un file STL

I file STL memorizzano i triangoli come faccette grezze, non come una mesh indicizzata. Dopo il caricamento, i poligoni vengono sintetizzati da quelle faccette. Se polygons appare vuoto, controlla len(mesh.control_points); se il conteggio è un multiplo di 3 la geometria è memorizzata in forma non indicizzata e ogni tripla consecutiva di vertici forma un triangolo.

Discrepanza del sistema di coordinate (il modello appare ruotato o specchiato)

Strumenti diversi usano convenzioni diverse (Y‑up vs Z‑up, mano sinistra vs mano destra). Imposta ObjLoadOptions.flip_coordinate_system = True o applica una rotazione al Transform del nodo radice dopo il caricamento.

AttributeError: 'NoneType' object has no attribute 'polygons'

L’elenco delle entità di un nodo può contenere entità non mesh (telecamere, luci). Proteggi sempre con isinstance(entity, Mesh) prima del cast.

Domande Frequenti (FAQ)

Quali formati 3D posso caricare?

OBJ (Wavefront), STL (binario e ASCII), glTF 2.0 / GLB, COLLADA (DAE) e 3MF. La tokenizzazione dei file FBX è parzialmente supportata, ma l’analisi completa non è ancora terminata.

Caricare un file OBJ carica anche il materiale .mtl?

Sì, quando ObjLoadOptions.enable_materials = True (il valore predefinito). La libreria cerca il file .mtl nella stessa directory del file .obj. Se il .mtl è mancante, la geometria viene comunque caricata e viene emesso un avviso.

Posso caricare un file da un flusso di byte invece di un percorso?

Sì. scene.open() accetta qualsiasi oggetto simile a un file con un metodo .read() oltre a una stringa di percorso file. Passa direttamente un flusso binario aperto (ad es., io.BytesIO). Scene.from_file() accetta solo una stringa di percorso file.

Come ottengo le normali di superficie?

Dopo il caricamento, controlla mesh.get_element(VertexElementType.NORMAL). Questo restituisce un VertexElementNormal la cui lista data contiene un vettore normale per riferimento, mappato secondo mapping_mode e reference_mode.

from aspose.threed.entities import Mesh, VertexElementType

normals = mesh.get_element(VertexElementType.NORMAL)
if normals:
    print(normals.data[0])  # First normal vector

La libreria è thread‑safe per il caricamento di più file contemporaneamente?

Ogni oggetto Scene è indipendente. Caricare file separati in istanze separate di Scene da thread separati è sicuro purché non si condivida un singolo Scene tra i thread senza un blocco esterno.