Пространственные привязки Azure в Unreal

Пространственные привязки Azure — это служба Microsoft Mixed Reality, позволяющая устройствам дополненной реальности обнаруживать, публиковать и сохранять точки привязок в физическом мире. В документации ниже приведены инструкции по интеграции службы "Пространственные привязки Azure" в проект Unreal. Дополнительные сведения см. на странице службы "Пространственные привязки Azure".

Примечание

Unreal Engine 4.26 теперь включает подключаемые модули для поддержки ARKit и ARCore, если вы разрабатываете приложения для iOS или Android.

Важно!

Локальные привязки хранятся на устройстве, а пространственные привязки Azure сохраняются в облаке. Если вам нужно хранить привязки локально на устройстве, соответствующие инструкции приведены в документе по локальным пространственным привязкам. Обратите внимание, что вы можете использовать локальные привязки и привязки Azure в одном проекте без каких-либо конфликтов.

Предварительные условия

Для работы с этим руководством вам потребуются:

• Установленный подключаемый модуль Microsoft OpenXR, доступный в Unreal Marketplace или GitHub.
• Unreal 4.25 или более поздней версии;
• настройка проекта HoloLens 2 в Unreal;
• ознакомление с обзором пространственных привязок Azure;
• базовые знания C++ и Unreal.

Получение сведений об учетной записи службы "Пространственные привязки Azure"

Прежде чем вы сможете использовать Пространственные привязки Azure в своем проекте, сделайте следующее:

• Создайте ресурс пространственных привязок и скопируйте приведенные ниже поля учетной записи. Эти значения используются для аутентификации пользователей в учетной записи приложения:
  • идентификатор учетной записи;
  • ключ учетной записи.

Дополнительные сведения см. в документации по аутентификации в службе "Пространственные привязки Azure".

Примечание

Пространственные привязки Azure в Unreal 4.25 не поддерживают маркеры аутентификации Azure AD, но мы добавим поддержку такой функции в последующих выпусках.

Включение возможностей и расширений

HoloLens

Выберите Project Settings HoloLens (Параметры проекта > HoloLens) и включите возможность использования Интернет-клиента:

Android

Чтобы приложение Android отображало диалоговое окно разрешений и разрешило доступ к возможностям настройки расположения, необходимо вызвать функцию запроса разрешений Android, прежде чем запускать сеанс Пространственных привязок Azure:

Создайте локальную переменную для разрешений ввода и заполните ее следующим:

• android.permission.ACCESS_WIFI_STATE
• android.permission.CHANGE_WIFI_STATE
• android.permission.INTERNET
• android.permission.BLUETOOTH
• android.permission.BLUETOOTH_ADMIN
• android.permission.ACCESS_COARSE_LOCATION
• android.permission.ACCESS_FINE_LOCATION
• android.permission.CAMERA

Наконец, откройте Project Settings Android (Параметры проекта > Android) и задайте те же разрешения в поле Extra Permissions (Дополнительные разрешения) в разделе Advanced APK Packaging (Расширенная упаковка APK):

iOS

Чтобы создать приложение для iOS, вам потребуется использовать Unreal на Mac. Чтобы выполнить упаковку с помощью учетной записи разработчика Apple, откройте Project Settings iOS (Параметры проекта > iOS) и прокрутите вниз к разделу Build (Сборка). Установите флажок Automatic Signing (Автоматическое подписание) и укажите в поле IOS Team ID (Идентификатор команды IOS) свой идентификатор команды.

Вы можете найти свой идентификатор команды, войдя на сайт developer.apple.com, перейдя на вкладку Membership (Членство) и найдя значения Team ID (Идентификатор команды).

Чтобы отобразить диалоговое окно разрешений и разрешить устройству iOS доступ к сведения о расположении, необходимо вызвать функции инициализации служб расположения и запуска служб расположения до запуска сеанса Пространственных привязок Azure:

Добавление подключаемых модулей службы "Пространственные привязки Azure"

Совет

При использовании Пространственных привязок Azure для Unreal существует подключаемый модуль Пространственных привязок Azure и подключаемый модуль для конкретной платформы (WMR, ARKit, ARCore, OpenXR). Одновременно должен быть включен только один подключаемый модуль для конкретной платформы.

HoloLens

Включите подключаемые модули службы "Пространственные привязки Azure" в Unreal Editor, выполнив следующие действия:

1. Последовательно выберите элементы Edit Plugins (Правка > Подключаемые модули) и найдите модули Azure Spatial Anchors и Azure Spatial Anchors For WMR.
2. Установите флажок Enabled (Включен) для обоих модулей, чтобы разрешить доступ к библиотекам схем Пространственных привязок Azure в своем приложении.

После этого перезапустите Unreal Editor, чтобы изменения вступили в силу. Теперь проект готов к использованию Пространственных привязок Azure.

Android

Включите подключаемые модули службы "Пространственные привязки Azure" в Unreal Editor, выполнив следующие действия:

1. Последовательно выберите элементы Edit Plugins (Правка > Подключаемые модули) и найдите модули Azure Spatial Anchors и Azure Spatial Anchors For WMR.
2. Установите флажок Enabled (Включен) для обоих модулей, чтобы разрешить доступ к библиотекам схем Пространственных привязок Azure в своем приложении.

После этого перезапустите Unreal Editor, чтобы изменения вступили в силу. Теперь проект готов к использованию Пространственных привязок Azure.

iOS

Включите подключаемые модули службы "Пространственные привязки Azure" в Unreal Editor, выполнив следующие действия:

1. Последовательно выберите элементы Edit Plugins (Правка > Подключаемые модули) и найдите модули Azure Spatial Anchors и Azure Spatial Anchors For ARKit.
2. Установите флажок Enabled (Включен) для обоих модулей, чтобы разрешить доступ к библиотекам схем Пространственных привязок Azure в своем приложении.

3. Также выполните поиск функций Mobile Location Services (Службы расположения для мобильных устройств) и Mobile Location Services - IOS Implementation (Службы расположения для мобильных устройств — реализация в iOS).
4. Установите флажок Enabled (Включено) в обоих подключаемых модулях, чтобы разрешить устройству iOS доступ к текущему расположению.

После этого перезапустите Unreal Editor, чтобы изменения вступили в силу. Теперь проект готов к использованию Пространственных привязок Azure.

Запуск сеанса Пространственных привязок

Сеанс Пространственных привязок Azure позволяет клиентским приложениям взаимодействовать со службой "Пространственные привязки Azure". Вам нужно будет создать и запустить сеанс службы "Пространственные привязки Azure" для создания, сохранения и публикации пространственных привязок Azure:

1. Откройте схему для Pawn, используемого в приложении.
2. Добавьте две строковые переменные дляидентификатора учетной записи и ключа учетной записи. Назначьте соответствующие значения из учетной записи службы "Пространственные привязки Azure", чтобы аутентифицировать сеанс.

Запустите сеанс Пространственных привязок Azure, выполнив следующие действия:

1. Проверьте, что сеанс дополненной реальности запущен в приложении HoloLens, так как сеанс Пространственных привязок Azure не может запуститься без сеанса дополненной реальности. Если у вас нет единой настройки, создайте ресурс сеанса дополненной реальности.
2. Добавьте пользовательское событие Start Azure Spatial Anchors Session (Запуск сеанса Пространственных привязок Azure) и настройте его, как показано на снимке экрана ниже.
   • При создании сеанса он не будет запущен по умолчанию. Это позволяет настроить сеанс для аутентификации со службой "Пространственные привязки Azure".

3. Настройте сеанс Пространственных привязок Azure, чтобы предоставить идентификатор, ключ, домен учетной записи и параметры локализации курса. Все флажки должны быть установлены в параметрах локализации курса, чтобы служба Пространственных привязок Azure могла использовать данные с датчиков для размещения привязок.

4. Запустите сеанс Пространственных привязок Azure, разрешив приложению создавать и находить пространственные привязки Azure.

Рекомендуется очистить ресурсы Пространственных привязок Azure в схеме графа событий, если вы больше не используете службу:

1. Остановите сеанс Пространственных привязок Azure. Сеанс больше не будет выполняться, но связанные с ним ресурсы по-прежнему будут существовать в подключаемом модуле Пространственных привязок Azure.

2. Удалите сеанс Пространственных привязок Azure, чтобы очистить все его ресурсы, о которых еще известно подключаемому модулю Пространственных привязок Azure.

Схема графа событий должна выглядеть так, как показано на снимке экрана ниже:

Создание привязки

Пространственная привязка Azure — это точка физического мира в пространстве приложения дополненной реальности, которая связывает содержимое дополненной реальности с расположениями в физическом мире. Пространственные привязки Azure могут совместно использовать различные пользователи. Такой общий доступ позволяет размещать содержимое дополненной реальности, отображаемое на различных устройствах, в одном расположении физического мира.

Чтобы создать новую пространственную привязку Azure, выполните следующие действия:

1. Убедитесь, что сеанс Пространственных привязок Azure запущен. Приложение не сможет создать или сохранить пространственную привязку Azure, если сеанс Пространственных привязок Azure не запущен.

2. Создайте или получите компонент Scene (Сцена) Unreal, расположение которого должно быть сохранено.
   • На изображении ниже Scene Component Needing Anchor (Компонент Scene, нуждающийся в привязке) используется в качестве переменной. Компонент Unreal Scene (Сцена) необходим, чтобы сформировать преобразование мира приложения для маркера дополненной реальности и пространственной привязки Azure.

Чтобы создать и сохранить пространственную привязку Azure для компонента Unreal Scene (Сцена), выполните следующие действия:

1. Вызовите компонент Pin (Маркер) для компонента Unreal Scene (Сцена) и укажите его World Transform (Преобразование мира) в качестве преобразования мира для маркера дополненной реальности.
   • Unreal отслеживает точки дополненной реальности в пространстве приложения с помощью маркеров дополненной реальности, которые используются для создания пространственной привязки Azure. В Unreal маркер дополненной реальности аналогичен объекту SpatialAnchor в HoloLens.

2. Вызовите функцию Create Cloud Anchor (Создание облачной привязки) с помощью только что созданного маркера дополненной реальности.
   • При создании облачной привязки пространственная привязка Azure создается локально, а не в службе "Пространственные привязки Azure". Параметры для пространственной привязки Azure, например срок ее действия, можно задать до создания пространственной привязки с помощью службы.

3. Задайте срок действия пространственной привязки Azure. Параметр Lifetime (Время действия) этой функции позволяет разработчикам указать (в секундах), как долго привязка будет поддерживаться службой.
   • Например, срок действия длительностью в неделю будет равен 60 с x 60 мин x 24 ч x 7 дн. = 604 800 с.

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

Сохранение привязки

После настройки пространственной привязки Azure с вашими параметрами вызовите функцию Save Cloud Anchor (Сохранение облачной привязки). Функция Save Cloud Anchor (Сохранение облачной привязки) объявляет привязку для службы "Пространственные привязки Azure". Если вызов к этому действию был успешным, пространственная привязка Azure становится доступна другим пользователям службы "Пространственные привязки Azure".

Примечание

Save Cloud Anchor (Сохранение облачной привязки) — это асинхронная функция, которую можно вызвать только для события потока игры, например EventTick. Save Cloud Anchor может не отображаться как доступная функция схемы в пользовательских функциях схемы, но она также доступна в редакторе схемы графа событий для Pawn.

В приведенном ниже примере пространственная привязка Azure сохраняется в наборе во время обратного вызова входного события. Привязка затем сохраняется в EventTick. Для сохранения пространственной привязки Azure может потребоваться несколько попыток в зависимости от объема пространственных данных, созданных в сеансе Пространственных привязок Azure. Именно поэтому рекомендуется проверять, был ли успешным вызов сохранения.

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

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

Удаление привязки

Вы можете удалить привязку из службы "Пространственные привязки Azure", вызвав функцию Delete Cloud Anchor (Удаление облачной привязки).

Примечание

Delete Cloud Anchor (Удаление облачной привязки) — это скрытая функция, которую можно вызвать только для события потока игры, например EventTick. Delete Cloud Anchor может не отображаться как доступная функция схемы в пользовательских функциях схемы, но она также доступна в редакторе схемы графа событий для Pawn.

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

Схема графа событий теперь должна выглядеть так, как показано на снимке экрана ниже:

Поиск существующих привязок

Существующие привязки могут создаваться другими пользователями или устройствами со службой "Пространственные привязки Azure":

1. Получите идентификатор пространственной привязки Azure, которую хотите обнаружить.
   • Идентификатор привязки можно получить для привязки, созданной устройством из предыдущего сеанса Пространственных привязок Azure. Кроме того, его можно создать и использовать совместно с одноранговыми устройствами, взаимодействующими со службой "Пространственные привязки Azure".

2. Добавьте компонент AzureSpatialAnchorsEvent в свою схему Pawn.
   • Этот компонент позволяет вам подписаться на различные события Пространственных привязок Azure, например на события, вызываемые при нахождении пространственной привязки Azure.

3. Подпишитесь на событие ASAAnchor Located Delegate (Привязкой ASAAnchor обнаружен делегат) для компонента AzureSpatialAnchorsEvent.
   • Делегат сообщает приложению об обнаружении новых привязок, связанных с учетной записью Пространственных привязок Azure.
   • При обратном вызове события пространственные привязки Azure, созданные другими пользователями или устройствами с помощью сеанса Пространственных привязок Azure, по умолчанию не будут включать маркеры дополненной реальности. Чтобы создать маркер дополненной реальности для обнаруженной пространственной привязки Azure, разработчики могут вызвать функцию Create ARPin Around Azure Cloud Spatial Anchor (Создание маркера дополненной реальности в облачной пространственной привязке Azure).

Чтобы найти пространственные привязки Azure, созданные другими пользователями или устройствами с помощью службы "Пространственные привязки Azure", приложению нужно создать наблюдатель за Пространственными привязками Azure:

1. Убедитесь, что сеанс Пространственных привязок Azure запущен.
2. Создайте AzureSpatialAnchorsLocateCriteria.
   • Вы можете указать различные параметры расположения, например расстояние от пользователя или от другой привязки.
3. Объявите идентификатор нужной пространственной привязки Azure в AzureSpatialAnchorsLocateCriteria.
4. Вызовите функцию Create Watcher (Создание наблюдателя).

Приложение теперь начнет поиск пространственных привязок Azure, о которых известно службе "Пространственные привязки Azure", благодаря чему пользователи смогут находить пространственные привязки Azure, созданные другими.

После обнаружения пространственной привязки Azure вызовите функцию Stop Watcher (Остановка наблюдателя), чтобы остановить наблюдатель за пространственными привязками Azure и очистить его ресурсы.

Финальная схема графа событий теперь должна выглядеть так, как показано на снимке экрана ниже:

Следующий этап разработки

Если вы следуете изложенным нами инструкциям по разработке для Unreal, вы как раз прошли половину в изучении основных стандартных блоков MRTK. Отсюда вы можете перейти к следующему стандартному блоку:

Пространственное сопоставление

Или перейдите к возможностям и API платформы смешанной реальности:

Камера HoloLens

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

Дальнейшие действия

• Локальные пространственные привязки
• Документация по пространственным привязкам
• Функции пространственных привязок
• Действующие рекомендации по работе с привязками