How to Load 3D Models in .NET

Aspose.3D.Converter for .NET provides a straightforward API for opening 3D files without native dependencies. After loading a file into a Scene object you can walk the node hierarchy and read geometry data for every mesh.

Step-by-Step Guide

Step 1: Install the Package

Add the NuGet package to your project:

dotnet add package Aspose.3D.Converter --version 1.0.0

Verify:

using Aspose.ThreeD;
Console.WriteLine("Aspose.3D.Converter loaded.");

Step 2: Import the Scene Class

The Scene class is the top-level container for all 3D data. Import the namespace:

using Aspose.ThreeD;
using Aspose.ThreeD.Formats;

Step 3: Load a File

Use Scene.Open() to load any supported format. The library detects the format from the file extension:

var scene = new Scene();
scene.Open("model.obj");

Or use the static factory:

var scene = Scene.FromFile("model.obj");

Both support OBJ, STL, glTF 2.0 / GLB, FBX, COLLADA, PLY, and 3MF.

Step 4: Traverse Scene Nodes

A loaded scene is a tree of Node objects rooted at scene.RootNode:

void Walk(Node node, int depth = 0)
{
    var indent = new string(' ', depth * 2);
    Console.WriteLine($"{indent}Node: {node.Name}");
    foreach (var child in node.ChildNodes)
        Walk(child, depth + 1);
}

Walk(scene.RootNode);

Each Node may carry an Entity (mesh, camera, light). Check node.Entity before accessing.

Step 5: Access Vertex and Polygon Data

Cast a node’s entity to Mesh and read its control points and polygons:

using Aspose.ThreeD.Entities;

foreach (var node in scene.RootNode.ChildNodes)
{
    if (node.Entity is Mesh mesh)
    {
        Console.WriteLine($"Mesh '{node.Name}': " +
            $"{mesh.ControlPoints.Count} vertices, " +
            $"{mesh.PolygonCount} polygons");

        if (mesh.ControlPoints.Count > 0)
        {
            var v = mesh.ControlPoints[0];
            Console.WriteLine($"  First vertex: ({v.X:F4}, {v.Y:F4}, {v.Z:F4})");
        }
    }
}

Step 6: Apply Format-Specific Load Options

For fine-grained control, pass a LoadOptions subclass:

var options = new ObjLoadOptions
{
    FlipCoordinateSystem = true,
    Scale = 0.01,
    EnableMaterials = true
};

var scene = new Scene();
scene.Open("model.obj", options);

Other option classes: FbxLoadOptions, GltfLoadOptions, StlLoadOptions, ColladaLoadOptions, PlyLoadOptions.

Common Issues and Fixes

ImportException when calling Scene.Open()

The file may be corrupted or in an unsupported format variant. Verify the file opens in a 3D viewer and that the format is in the supported list.

Missing materials after OBJ load

Place the .mtl file alongside the .obj file and ensure ObjLoadOptions.EnableMaterials = true.

Coordinate system mismatch (model appears rotated)

Set ObjLoadOptions.FlipCoordinateSystem = true or apply a rotation to the root node’s Transform.

NullReferenceException accessing node.Entity

Not every node carries geometry. Always check if (node.Entity is Mesh mesh) before accessing mesh properties.

Frequently Asked Questions (FAQ)

Which 3D formats can I load?

OBJ, STL (binary and ASCII), glTF 2.0 / GLB, FBX, COLLADA (DAE), PLY, and 3MF.

Can I load from a stream?

Yes. Scene.Open() accepts a Stream:

using var stream = File.OpenRead("model.glb");
scene.Open(stream);

How do I get surface normals?

After loading, call mesh.GetElement(VertexElementType.Normal) to access the VertexElementNormal layer.

Is the library thread-safe?

Each Scene instance is independent. Loading separate files into separate Scene instances from separate threads is safe.