Aspose.3D FOSS
.NET
Как загружать 3D‑модели в .NET

Как загружать 3D‑модели в .NET

Aspose.3D for .NET предоставляет простой API для открытия 3D‑файлов без нативных зависимостей. После загрузки файла в объект Scene вы можете пройти иерархию узлов и прочитать геометрические данные каждого меша.

Пошаговое руководство

Шаг 1: Установить пакет

Добавьте пакет NuGet в ваш проект:

dotnet add package Aspose.3D --version 26.1.0

Проверьте:

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

Шаг 2: Импортировать класс Scene

Класс Scene является контейнером верхнего уровня для всех 3D‑данных. Импортируйте пространство имён:

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

Шаг 3: Загрузить файл

Используйте Scene.Open() для загрузки любого поддерживаемого формата. Библиотека определяет формат по расширению файла:

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

Или используйте статическую фабрику:

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

Оба поддерживают OBJ, STL, glTF 2.0 / GLB, FBX, COLLADA, PLY и 3MF.

Шаг 4: Обход узлов сцены

Загруженная сцена представляет собой дерево объектов Node, корневым элементом которого является 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);

Каждый Node может содержать Entity (mesh, camera, light). Проверьте node.Entity перед доступом.

Шаг 5: Доступ к данным вершин и полигонов

Приведите сущность узла к Mesh и прочитайте её контрольные точки и полигоны:

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

Шаг 6: Применить параметры загрузки, специфичные для формата

Для точного управления передайте подкласс LoadOptions:

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

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

Другие классы опций: FbxLoadOptions, GltfLoadOptions, StlLoadOptions, ColladaLoadOptions, PlyLoadOptions.

Распространённые проблемы и решения

ImportException при вызове Scene.Open()

Файл может быть повреждён или находится в неподдерживаемом варианте формата. Убедитесь, что файл открывается в 3D‑просмотрщике и что формат входит в список поддерживаемых.

Отсутствующие материалы после загрузки OBJ

Поместите файл .mtl рядом с файлом .obj и убедитесь, что ObjLoadOptions.EnableMaterials = true.

Несоответствие системы координат (модель выглядит повернутой)

Установите ObjLoadOptions.FlipCoordinateSystem = true или примените вращение к Transform корневого узла.

NullReferenceException доступ к node.Entity

Не каждый узел содержит геометрию. Всегда проверяйте if (node.Entity is Mesh mesh) перед доступом к свойствам сетки.

Часто задаваемые вопросы (FAQ)

Какие 3D форматы я могу загрузить?

OBJ, STL (бинарный и ASCII), glTF 2.0 / GLB, FBX, COLLADA (DAE), PLY и 3MF.

Могу ли я загрузить из потока?

Да. Scene.Open() принимает Stream:

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

Как получить нормали поверхности?

После загрузки вызовите mesh.GetElement(VertexElementType.Normal), чтобы получить доступ к слою VertexElementNormal.

Является ли библиотека потокобезопасной?

Каждый Scene экземпляр независим. Загрузка отдельных файлов в отдельные Scene экземпляры из разных потоков безопасна.

 Русский