How to Load 3D Models in Python

Aspose.3D FOSS for Python provides a straightforward API for opening 3D files without any native dependencies. After loading a file into a Scene object, you can walk the node hierarchy and read raw geometry data for every mesh in the scene.

Step-by-Step Guide

pip install aspose-3d-foss

import aspose.threed
print(aspose.threed.__version__)  # e.g. 26.1.0

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)

Common Issues and Fixes

FileNotFoundError when calling Scene.from_file()

The path must be absolute or correct relative to the working directory at runtime. Use pathlib.Path to build reliable paths:

from pathlib import Path
from aspose.threed import Scene

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

mesh.polygons is empty after loading an STL file

STL files store triangles as raw facets, not an indexed mesh. After loading, polygons are synthesised from those facets. If polygons appears empty, check len(mesh.control_points); if the count is a multiple of 3 the geometry is stored in unindexed form and each consecutive triple of vertices forms one triangle.

Coordinate system mismatch (model appears rotated or mirrored)

Different tools use different conventions (Y-up vs Z-up, left-hand vs right-hand). Set ObjLoadOptions.flip_coordinate_system = True or apply a rotation to the root node’s Transform after loading.

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

A node’s entity list may contain non-mesh entities (cameras, lights). Always guard with isinstance(entity, Mesh) before casting.

Frequently Asked Questions (FAQ)

Which 3D formats can I load?

OBJ (Wavefront), STL (binary and ASCII), glTF 2.0 / GLB, COLLADA (DAE), and 3MF. FBX file tokenization is partially supported but full parsing is not yet complete.

Does loading an OBJ file also load the .mtl material?

Yes, when ObjLoadOptions.enable_materials = True (the default). The library looks for the .mtl file in the same directory as the .obj file. If the .mtl is missing, geometry is still loaded and a warning is emitted.

Can I load a file from a byte stream instead of a path?

Scene.open() accepts a file path string. Loading from an in-memory stream is not exposed in the current API; write the bytes to a temporary file first.

How do I get surface normals?

After loading, check mesh.get_element(VertexElementType.NORMAL). This returns a VertexElementNormal whose data list contains one normal vector per reference, mapped according to mapping_mode and reference_mode.

from aspose.threed.entities import Mesh, VertexElementType

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

Is the library thread-safe for loading multiple files concurrently?

Each Scene object is independent. Loading separate files into separate Scene instances from separate threads is safe as long as you do not share a single Scene across threads without external locking.