Общие сведения о пакете SDK среды выполнения

В этом разделе представлен общий обзор пакета SDK среды выполнения привязок объектов, который используется для обнаружения объектов с помощью модели объектных привязок. Вы получите знания о том, каким образом представляется объект и для чего используются различные его компоненты.

Все типы, описанные ниже, можно найти в одном из следующих пространств имен: Microsoft.Azure.ObjectAnchors, Microsoft.Azure.ObjectAnchors.Diagnostics и Microsoft.Azure.ObjectAnchors.SpatialGraph.

Типы

ObjectModel

ObjectModel представляет геометрию физического объекта и кодирует необходимые параметры для обнаружения и оценки положения. Ее необходимо создать с помощью службы "Объектные привязки". Затем приложение может загрузить созданный файл модели с помощью API привязок объектов и запросить сетку, внедренную в эту модель для визуализации.

ObjectSearchArea

Тип ObjectSearchArea указывает местоположение для поиска одного или нескольких объектов. Он определяется идентификатором узла пространственного графа и пространственными границами в системе координат, представленной идентификатором узла пространственного графа. Пакет SDK среды выполнения объектных привязок поддерживает четыре типа границ, а именно: поле зрения, ограничивающий прямоугольник, сфераи расположение.

AccountInformation

AccountInformation сохраняет идентификатор, ключ и домен для учетной записи Объектных привязок Azure.

ObjectAnchorsSession

ObjectAnchorsSession представляет сеанс Объектных привязок Azure, который используется для создания экземпляров ObjectObserver, применяемых для обнаружения объектов в физическом мире.

ObjectObserver

ObjectObserver загружает объектные модели, обнаруживает их экземпляры и сообщает положение в 6 степенях свободы каждого экземпляра в системе координат HoloLens.

Хотя любая объектная модель или экземпляр создается из наблюдателя, их время существования взаимно независимо. Приложение может ликвидировать наблюдатель и продолжать использовать объектную модель или экземпляр.

Objectquery

ObjectQuery сообщает наблюдателю объекта о том, как найти объекты данной модели. Он предоставляет следующие настраиваемые параметры, значения по умолчанию которых можно получить из объектной модели.

MinSurfaceCoverage

Свойство MinSurfaceCoverage указывает значение, которое будет рассматриваться как экземпляр при обнаружении.

Для каждого кандидата объекта наблюдатель рассчитывает отношение перекрывающихся поверхностей между преобразованной объектной моделью и сценой, а затем сообщает об этом кандидате приложению только в случае, если коэффициент покрытия превышает заданное пороговое значение.

IsExpectedToBeStandingOnGroundPlane

Свойство IsExpectedToBeStandingOnGroundPlane указывает, ожидается ли целевой объект на плоскости основания.

Плоскость основания — это наименьшее горизонтальное основание в области поиска. Он предоставляет хорошее ограничение для возможных положений объектов. Включение этого флага поможет наблюдателю оценить положение в ограниченном пространстве и улучшить точность. Этот параметр будет пропущен, если модель не должна находиться на плоскости основания.

ExpectedMaxVerticalOrientationInDegrees

Свойство ExpectedMaxVerticalOrientationInDegrees указывает ожидаемый максимальный угол в градусах между направлением вверх экземпляра объекта и силой притяжения.

Этот параметр предоставляет другое ограничение в направлении вверх для оцениваемого положения. Например, если объект находится в положении "вертикально", этот параметр может иметь значение 0. Подразумевается, что объектные привязки не должны обнаруживать объекты, которые отличаются от модели. Если модель стоит в вертикальном положении, то они не будут обнаруживать экземпляры, лежащие на боку. Для макета, лежащего на боковой стороне, будет использоваться новая модель. То же правило применяется для артикуляции.

MaxScaleChange

Свойство MaxScaleChange указывает максимальное изменение масштаба объекта (в пределах между 0 и 1) относительно пространственного сопоставления. Оценочный масштаб применяется к преобразованным вершинам объектов, центрированным по источнику и выровненным по осям. Оценочный масштаб не может быть фактическим масштабом между моделью САПР и ее физическим представлением, но набором значений, позволяющих приложению визуализировать объектную модель близко к пространственному сопоставлению физического объекта.

SearchAreas

Свойство SearchAreas указывает массив пространственных границ, где можно найти объект (-ы).

Наблюдатель будет искать объекты в объединенном пространстве всех областей поиска, указанных в запросе. В этом выпуске мы будем возвращать не более одного объекта с наивысшей достоверностью, чтобы сократить задержку.

ObjectInstance

ObjectInstance представляет гипотетическую позицию, в которой экземпляр данной модели может находиться в системе координат HoloLens. Каждый экземпляр поставляется со свойством SurfaceCoverage, указывающим, насколько достоверна оценка положения.

Экземпляр создается путем вызова метода ObjectObserver.DetectAsync, который затем обновляется автоматически в фоновом режиме, когда активен. Приложение может прослушивать событие изменения состояния в определенном экземпляре или изменить режим отслеживания, чтобы приостановить или возобновить обновление. При потере отслеживания экземпляр будет автоматически удален из наблюдателя.

ObjectDiagnosticsSession

ObjectDiagnosticsSession записывает сведения о диагностике и записывает данные в архив.

Архив диагностики включает облако точек сцены, состояние наблюдателя и сведения о моделях. Эти сведения полезны для обнаружения возможных проблем во время выполнения. Дополнительные сведения см. в разделе Часто задаваемые вопросы.

Использование и сведения о пакете SDK среды выполнения

В этом разделе приводятся основные сведения об использовании пакета SDK среды выполнения. Он должен предоставить достаточный контекст для просмотра примеров приложений, чтобы вы могли увидеть, как используются объектные привязки в глобальном порядке.

Инициализация

Приложения должны вызывать API ObjectObserver.IsSupported(), чтобы определить, поддерживаются ли привязки объектов на устройстве перед его использованием. Если API ObjectObserver.IsSupported() возвращает false, убедитесь, что приложение включило возможность spatialPerception и/или версия ОС HoloLens является последней.

using Microsoft.Azure.ObjectAnchors;

if (!ObjectObserver.IsSupported())
{
    // Handle the error
}

// This call should grant the access we need.
ObjectObserverAccessStatus status = await ObjectObserver.RequestAccessAsync();
if (status != ObjectObserverAccessStatus.Allowed)
{
    // Handle the error
}

Затем приложение создает наблюдатель объектов и загружает необходимые модели, созданные службой преобразования модели объектных привязок.

using Microsoft.Azure.ObjectAnchors;

// Note that you need to provide the Id, Key and Domain for your Azure Object
// Anchors account.
Guid accountId = new Guid("[your account id]");
string accountKey = "[your account key]";
string accountDomain = "[your account domain]";

AccountInformation accountInformation = new AccountInformation(accountId, accountKey, accountDomain);
ObjectAnchorsSession session = new ObjectAnchorsSession(accountInformation);
ObjectObserver observer = session.CreateObjectObserver();

// Load a model into a byte array. The model could be a file, an embedded
// resource, or a network stream.
byte[] modelAsBytes;
ObjectModel model = await observer.LoadObjectModelAsync(modelAsBytes);

// Note that after a model is loaded, its vertices and normals are transformed
// into a centered coordinate system for the ease of computing the object pose.
// The rigid transform can be retrieved through the `OriginToCenterTransform`
// property.

Приложение создает запрос для обнаружения экземпляров этой модели в пространстве.

#if WINDOWS_UWP || DOTNETWINRT_PRESENT
#define SPATIALCOORDINATESYSTEM_API_PRESENT
#endif

using Microsoft.Azure.ObjectAnchors;
using Microsoft.Azure.ObjectAnchors.SpatialGraph;
using Microsoft.Azure.ObjectAnchors.Unity;
using UnityEngine;

// Get the coordinate system.
SpatialGraphCoordinateSystem? coordinateSystem = null;

#if SPATIALCOORDINATESYSTEM_API_PRESENT
SpatialCoordinateSystem worldOrigin = ObjectAnchorsWorldManager.WorldOrigin;
if (worldOrigin != null)
{
    coordinateSystem = await Task.Run(() => worldOrigin.TryToSpatialGraph());
}
#endif

if (!coordinateSystem.HasValue)
{
    Debug.LogError("no coordinate system?");
    return;
}

// Get the search area.
SpatialFieldOfView fieldOfView = new SpatialFieldOfView
{
    Position = Camera.main.transform.position.ToSystem(),
    Orientation = Camera.main.transform.rotation.ToSystem(),
    FarDistance = 4.0f, // Far distance in meters of object search frustum.
    HorizontalFieldOfViewInDegrees = 75.0f, // Horizontal field of view in
                                            // degrees of object search frustum.
    AspectRatio = 1.0f // Aspect ratio (horizontal / vertical) of object search
                       // frustum.
};

ObjectSearchArea searchArea = ObjectSearchArea.FromFieldOfView(coordinateSystem.Value, fieldOfView);

// Optionally change the parameters, otherwise use the default values embedded
// in the model.
ObjectQuery query = new ObjectQuery(model);
query.MinSurfaceCoverage = 0.2f;
query.ExpectedMaxVerticalOrientationInDegrees = 1.5f;
query.MaxScaleChange = 0.1f;
query.SearchAreas.Add(searchArea);

// Detection could take a while, so we run it in a background thread.
IReadOnlyList<ObjectInstance> detectedObjects = await observer.DetectAsync(query);

По умолчанию каждый обнаруженный экземпляр будет автоматически отслеживаться наблюдателем. При необходимости можно манипулировать этими экземплярами, изменив режим отслеживания или прослушивая события изменения состояния.

using Microsoft.Azure.ObjectAnchors;

foreach (ObjectInstance instance in detectedObjects)
{
    // Supported modes:
    // "LowLatencyCoarsePosition"    - Consumes less CPU cycles thus fast to
    //                                 update the state.
    // "HighLatencyAccuratePosition" - Uses the device's camera and consumes more CPU
    //                                 cycles thus potentially taking longer
    //                                 time to update the state.
    // "Paused"                      - Stops to update the state until mode
    //                                 changed to low or high.
    instance.Mode = ObjectInstanceTrackingMode.LowLatencyCoarsePosition;

    // Listen to state changed event on this instance.
    instance.Changed += InstanceChangedHandler;

    // Optionally dispose an instance if not interested in it.
    // instance.Dispose();
}

В событии изменения состояния можно запросить последнее состояние или ликвидировать экземпляр, если он потерял отслеживание.

using Microsoft.Azure.ObjectAnchors;

void InstanceChangedHandler(object sender, ObjectInstanceChangedEventArgs args)
{
    // Try to query the current instance state.
    ObjectInstanceState state = sender.TryGetCurrentState();

    if (state != null)
    {
        // Process latest state.
        // An object pose includes rotation and translation, applied in
        // the same order to the object model in the centered coordinate system.
    }
    else
    {
        // This object instance is lost for tracking, and will never be recovered.
        // The caller can detach the Changed event handler from this instance
        // and dispose it.
    }
}

Кроме того, приложение может дополнительно записать один или несколько сеансов диагностики для автономной отладки.

using Microsoft.Azure.ObjectAnchors;
using Microsoft.Azure.ObjectAnchors.Diagnostics;

string diagnosticsFolderPath = Windows.Storage.ApplicationData.Current.TemporaryFolder.Path;
const uint maxSessionSizeInMegaBytes = uint.MaxValue;

// Recording starts on the creation of a diagnostics session.
ObjectDiagnosticsSession diagnostics = new ObjectDiagnosticsSession(observer, maxSessionSizeInMegaBytes);

// Wait for the observer to do a job.

// Application can report some **pseudo ground-truth** pose for an instance
// acquired from other means.
diagnostics.ReportActualInstanceLocation(instance, coordinateSystem, Vector3.Zero, Quaternion.Identity);

// Close a session and write the diagnostics into an archive at specified location.
await diagnostics.CloseAsync(System.IO.Path.Combine(diagnosticsFolderPath, "diagnostics.zip"));

Наконец, мы выпускаем ресурсы путем удаления всех объектов.

using Microsoft.Azure.ObjectAnchors;

foreach (ObjectInstance instance in activeInstances)
{
    instance.Changed -= InstanceChangedHandler;
    instance.Dispose();
}

model.Dispose();
observer.Dispose();