Wie man 3D-Modelle in Python lädt

Aspose.3D FOSS for Python bietet eine unkomplizierte API zum Öffnen von 3D-Dateien ohne native Abhängigkeiten. Nachdem Sie eine Datei in ein Scene‑Objekt geladen haben, können Sie die Knotenhierarchie durchlaufen und Rohgeometriedaten für jedes Mesh in der Szene lesen.

Schritt-für-Schritt-Anleitung

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)

Häufige Probleme und Lösungen

FileNotFoundError beim Aufrufen von Scene.from_file()

Der Pfad muss absolut oder korrekt relativ zum Arbeitsverzeichnis zur Laufzeit sein. Verwenden Sie pathlib.Path, um zuverlässige Pfade zu erstellen:

from pathlib import Path
from aspose.threed import Scene

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

mesh.polygons ist nach dem Laden einer STL-Datei leer

STL-Dateien speichern Dreiecke als rohe Facetten, nicht als indiziertes Mesh. Nach dem Laden werden Polygone aus diesen Facetten synthetisiert. Wenn polygons leer erscheint, prüfen Sie len(mesh.control_points); ist die Anzahl ein Vielfaches von 3, wird die Geometrie in unindizierter Form gespeichert und jedes aufeinanderfolgende Triple von Scheitelpunkten bildet ein Dreieck.

Koordinatensystem-Fehlanpassung (Modell erscheint rotiert oder gespiegelt)

Verschiedene Werkzeuge verwenden unterschiedliche Konventionen (Y‑up vs Z‑up, linkshändig vs rechtshändig). Setzen Sie ObjLoadOptions.flip_coordinate_system = True oder wenden Sie nach dem Laden eine Rotation auf das Transform des Wurzelknotens an.

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

Die Entitätsliste eines Knotens kann Nicht‑Mesh‑Entitäten (Kameras, Lichter) enthalten. Immer mit isinstance(entity, Mesh) prüfen, bevor Sie casten.

Häufig gestellte Fragen (FAQ)

Welche 3D-Formate kann ich laden?

OBJ (Wavefront), STL (binär und ASCII), glTF 2.0 / GLB, COLLADA (DAE) und 3MF. Die Tokenisierung von FBX-Dateien wird teilweise unterstützt, aber die vollständige Analyse ist noch nicht abgeschlossen.

Lädt das Laden einer OBJ-Datei auch das .mtl-Material?

Ja, wenn ObjLoadOptions.enable_materials = True (der Standard). Die Bibliothek sucht die .mtl‑Datei im selben Verzeichnis wie die .obj‑Datei. Wenn die .mtl fehlt, wird die Geometrie trotzdem geladen und es wird eine Warnung ausgegeben.

Kann ich eine Datei aus einem Bytestrom statt eines Pfads laden?

Ja. scene.open() akzeptiert jedes dateiähnliche Objekt mit einer .read()‑Methode zusätzlich zu einem Dateipfad‑String. Übergeben Sie einen offenen Binärstream (z. B. io.BytesIO) direkt. Scene.from_file() akzeptiert nur einen Dateipfad‑String.

Wie bekomme ich Oberflächennormalen?

Nach dem Laden prüfen Sie mesh.get_element(VertexElementType.NORMAL). Dies gibt ein VertexElementNormal zurück, dessen data‑Liste einen Normalenvektor pro Referenz enthält, gemappt gemäß mapping_mode und reference_mode.

from aspose.threed.entities import Mesh, VertexElementType

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

Ist die Bibliothek thread‑sicher beim gleichzeitigen Laden mehrerer Dateien?

Jedes Scene‑Objekt ist unabhängig. Das Laden separater Dateien in separate Scene‑Instanzen aus separaten Threads ist sicher, solange Sie kein einzelnes Scene über Threads hinweg ohne externe Sperrung teilen.