QR-коды в Unity

Статья
06/29/2024

Гарнитуры HoloLens 2 могут отслеживать и обнаруживать QR-коды, которые можно использовать для предоставления голограмм и других функций AR. В этой статье описаны все, что вам нужно знать, чтобы начать использовать QR-коды в приложении Unity, в том числе:

Добавление обнаружения QR-кода в приложение Unity.
Понимание важных понятий и компонентов Unity, которые необходимо использовать.
Содержит учебники, охватывающие общее использование QR-кода.
Представляет пример сценария маркера AR, демонстрирующего сцену с поддержкой QR-кода и примеры сценариев.

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

Отслеживаемый QR-код

Настройка проекта и приложения Unity

Проект и приложение Unity должны быть настроены и настроены правильно для включения функций QR-кода, которые требуют:

OpenXR для Windows Смешанная реальность версии 113.2403.5001 или более поздней.

Примечание.

Это поставляется с ОС и может быть обновлено через Магазин Windows. Обратите внимание, что у пользователей могут быть установлены более ранние версии, и их устройства не смогут работать с маркерами AR, такими как QR-коды, до обновления до версии 113.2403.5001 или более поздней.
Проект, совместимый с поддерживаемой версией Unity:
- Unity 2022.3 LTS (рекомендуется)
- Unity 2021.3 LTS
Подключаемый модуль OpenXR Смешанная реальность.
Возможности веб-камеры, включенные для проекта Unity.
Разрешения камеры, предоставленные приложению.

В следующих разделах описано, как настроить проект и приложение Unity для включения обнаружения QR-кода.

Получение подключаемого модуля OpenXR Смешанная реальность

Пакет подключаемого модуля OpenXR Смешанная реальность содержит API C#, которые можно использовать для доступа к функциям QR-кода.

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

Скачайте и запустите средство компонента Смешанная реальность.
Установите подключаемый модуль OpenXR.

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

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

Для обнаружения и отслеживания QR-кодов проект Unity должен включать возможности WebCam .

Чтобы включить возможности WebCam , выполните следующие действия.

Откройте проект Unity.
Щелкните "Изменить" в меню приложения редактора Unity.
Перейдите в проигрыватель параметров > проекта и перейдите на вкладку UWP, как показано ниже.
Включите webCam в списке возможностей .
Выход из параметров проекта.

Возможности WebCam теперь включены для приложения Unity. Однако приложению по-прежнему необходимо предоставить разрешения на доступ к камере устройства.

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

Если в приложении включены возможности WebCam , диалоговое окно разрешений предложит пользователям предоставить приложению доступ к камере устройства.

Диалоговое окно

Это диалоговое окно отображается пользователям только один раз, обычно при вводе сцены ARMarkerManager с поддержкой маркера QR-кода. Если доступ к камере запрещен, пользователи могут перейти к приложениям параметров > и включить его с помощью дополнительных параметров приложения.

Расширенные параметры приложения с включенными разрешениями

Создание обнаружения QR-кода в сцене

Обнаружение QR-кода должно быть встроено в каждую сцену, в которой требуется использовать QR-коды:

ARMarkerManager С GameObject присоединенным. ARMarkerManager несет ответственность за создание, обновление и удаление каждого GameObject из обнаруженных QR-кодов.
Префаб с ARMarker присоединенным.
ARMarkerManager настроено использовать префаб при создании GameObject QR-кода.

Создание префаб для QR-кодов

Чтобы использовать QR-коды в сцене, необходимо создать префаб для QR-кодов. ARMarkerManager использует этот префаб для создания кода GameObject при обнаружении QR-кода.

Чтобы сделать префаб для QR-кодов, сделайте так:

Создайте новую префаб для проекта.
Добавьте компонент в префаб, расположенный ARMarkerв разделе Script > Microsoft.MixedReality.OpenXR > ARMarker.

Теперь у вас есть базовая префаб для работы. Скорее всего, ваше приложение визуально представляет QR-коды, обнаруженные в среде. В следующем разделе описано, как добавить визуальное представление ДЛЯ QR-кодов.

Добавление визуальных элементов

В предыдущем разделе ARMarkerдобавление в префаб также автоматически добавлен компонент ARMarkerScale . Этот компонент используется для сопоставления масштаба визуального представления QR-кода с физическим аналогом.

Для этого:

Добавьте пустой GameObject в префаб, созданный в предыдущем разделе. Он будет представлять все содержимое маркера визуального элемента.
Добавьте дочерний трехмерный объект GameObject, например Quad, в содержимое GameObjectмаркера.
В компоненте предварительной ARMarkerScale версии задайте для преобразования маркера содержимое GameObjectмаркера. Задание этого поля гарантирует правильное масштабирование выбранного трехмерного идентификатора GameObject для сопоставления реальных QR-кодов.

Добавление `ARMarkerManager` в сцену

ARMarkerManager несет ответственность за создание, обновление и удаление каждого GameObject из обнаруженных QR-кодов.

Чтобы добавить ARMarkerManager в сцену, выполните приведенные действия.

Поместите его в сцену GameObject .
Добавьте компонент в ARMarkerManager папку GameObjectScript > Microsoft.MixedReality.OpenXR > ARMarkerManager.
Задайте для поля "Предварительный ARMarkerManager маркер" префаб , созданный в предыдущем разделе.
Разверните включенные типы маркеров, а затем выберите элемент и задайте для него QR-код.

Отслеживание изменений QR-кода

ARMarkerManager содержит markersChanged событие, которое предоставляет ARMarkersChangedEventArgs подписчикам. Используйте эти аргументы событий, чтобы отслеживать, какие QR-коды добавляются или удаляются из обнаружения или обновленных данных о позе.

В следующем коде демонстрируется подписка на ARMarkerManager.markersChanged событие, используя его аргументы событий для итерации объектов ARMarker ARMarkerManager , обрабатывающих и записывая их в отладку независимо от того, будут ли они добавлены, удалены или обновлены.

using System;
using Microsoft.MixedReality.OpenXR;

// ...

private void Awake()
{
    m_arMarkerManager = GetComponent<ARMarkerManager>();
    m_arMarkerManager.markersChanged += OnQRCodesChanged;
}

void OnQRCodesChanged(ARMarkersChangedEventArgs args)
{
    foreach (ARMarker qrCode in args.added)
        Debug.Log($"QR code with the ID {qrCode.trackableId} added.");

    foreach (ARMarker qrCode in args.removed)
        Debug.Log($"QR code with the ID {qrCode.trackableId} removed.");

    foreach (ARMarker qrCode in args.updated)
    {
        Debug.Log($"QR code with the ID {qrCode.trackableId} updated.");
        Debug.Log($"Pos:{qrCode.transform.position} Rot:{qrCode.transform.rotation} Size:{qrCode.size}");
    }
}

Получение времени последнего обнаружения QR-кода

ARMarker.lastSeenTime Используйте свойство, чтобы определить, когда устройство в последний раз отслеживало обнаруженный QR-код и время, если таковые есть, отслеживание теряется. Время измеряется в количестве секунд после запуска приложения Unity и аналогично UnityEngine.Time.realtimeSinceStartup.

Использование отслеживаемого идентификатора QR-кода

QR-коды являются отслеживаемыми, которые являются любым устройством AR, которое может обнаруживать и отслеживать в физической среде. Отслеживаемые элементы являются производными от типа ARTrackable<TSessionRelativeData, TTrackable> , предоставляющего идентификатор, состояние отслеживания, позу и другие данные.

Отслеживаемый идентификатор QR-кода можно передать в ARMarkerManager методы, чтобы получить свойства QR-кода, необработанные данные байтов и строковое представление, а также задать режим преобразования ДЛЯ QR-кода. Эти методы позволяют извлекать данные для QR-кода, не удерживая ссылку ARMarker на объект.

Идентификатор QR-кода можно передать в следующие ARMarkerManager методы:

Примечание.

GetRawData Для параметра allocatorметода передача Unity.Collections.Allocator.Temp достаточной для большинства сценариев.

После отслеживания QR-кода

ARMarker Так как объект можно отслеживать, он наследует trackingState свойство и имеет значение одно из трехUnityEngine.XR.ARSubsystems.TrackingState:

Limited: указывает, что QR-код отслеживается, но ограниченная информация доступна или имеет плохое качество.
Tracking: указывает, что QR-код полностью отслеживается.
None: указывает, что QR-код не отслеживается.

Чтобы отслеживать состояние отслеживания QR-кода, подписываться на ARMarkerManager.markersChanged коллекции маркеров, ARMarker предоставленные в аргументах события, переданных обработчику событий.

Следующий код демонстрирует использование ARMarkerManager.markersChanged события для итерации объектов ARMarker для недавно обнаруженных QR-кодов и записи их отслеживаемого идентификатора в окно отладки.

using System;
using Microsoft.MixedReality.OpenXR;

// ...

private void Awake()
{
    m_arMarkerManager = GetComponent<ARMarkerManager>();
    m_arMarkerManager.markersChanged += OnQRCodesChanged;
}

void OnQRCodesChanged(ARMarkersChangedEventArgs args)
{
    foreach (ARMarker qrCode in args.added)
    {
       if (qrCode.trackingState == UnityEngine.XR.ARSubsystems.TrackingState.Tracking)
           Debug.Log($"Fully tracked QR code with the ID {qrCode.trackableId} was added.");
    }
}

Получение версии QR-кода и типа QR-кода

Чтобы получить версию и тип обнаруженного QR-кода:

Вызов ARMarker.GetQRCodeProperties(), который возвращает QRCodeProperties экземпляр.
Перейдите к полю QRCodeProperties в возвращаемом значении, чтобы получить тип QR-кода. Имеет значение QRCodeType.QRCode или QRCodeType.MicroQRCode.
Перейдите к полю возвращаемого значения QRCodeProperties.version , чтобы получить версию QR-кода. Значение диапазонов от 1 до 40, если тип имеет значение QRCodeType.QRCode, и от 1 до 4, если тип имеет значение QRCodeType.MicroQRCode.

В качестве альтернативы передайте ARMarker отслеживаемый идентификатор объекта, чтобы ARMarkerManager.GetQRCodeProperties(TrackableId) получить тип и версию QR-кода.

Предупреждение

QR-коды являются единственным типом маркеров, поддерживаемым в настоящее время, хотя поддержка других типов маркеров может быть добавлена в будущих выпусках. Если markerType нет ARMarkerType.QRCode, вызов GetQRCodeProperties(TrackableId) вызывает вызов System.InvalidOperationException. Рассмотрите возможность упаковки вызовов GetQRCodeProperties(TrackableId) в блоки try-catch, если это может вызвать проблемы в приложении позже.

Чтение QR-данных

Компонент ARMarker присоединяется к каждому GameObject из создаваемых ARMarkerManager элементов. ARMarker предоставляет два метода, которые возвращают данные QR-кода:

GetDecodedString(): этот метод получает строковое представление QR-кода, например URL-адрес.
GetRawData(Unity.Collections.Allocator allocator): этот метод возвращает содержимое QR-кода в виде массива байтов, что позволяет точно настроить способ выделения массива. Используйте этот метод в горячих путях и других ситуациях, когда производительность является критической.

Следующий код демонстрирует базовое использование GetDecodedString() и GetRawData(Unity.Collections.Allocator allocator):

using System;
using Microsoft.MixedReality.OpenXR;

// ...

void OnQRCodesChanged(ARMarkersChangedEventArgs args)
{
    foreach (ARMarker qrCode in args.added)
    {
        var text = qrCode.GetDecodedString();
        Debug.Log($"QR code text: {text}");

        var bytes = qrCode.GetRawData(Unity.Collections.Allocator.Temp);
        Debug.Log($"QR code bytes: {bytes.Length}");
        bytes.Dispose();
    }
}

Получение размера QR-кода, позиции, поворота и центра

Объект ARMarker предоставляет размер, позицию, поворот и центр QR-кода, который он представляет.

Чтобы получить размер QR-кода в метрах, используйте свойство ARMarker.size.

ARMarker.transform Используйте свойство для получения положения поворота и пространства мира преобразования QR-кода, а ARMarker.center также для 2D-координат QR-кода относительно преобразования QR-кода. Само преобразование находится в центре в зависимости от того, установлен ли (режим преобразования) (наиболее стабильный, верхний левый QR-код) или TransformMode.Center (центр, геометрический центр QR-кода).ARMarker.transformMode TransformMode.MostStable

ARMarkerManager.defaultTransformMode Используйте поле, чтобы задать режим ARMarkerManager преобразования, создайте новые ARMarker объекты. Поле инициализируется с Default Transform Mode помощью поля в инспекторе Unity, как показано ниже.

Поле инспектора режима преобразования по умолчанию компонента ARMarkerManager

В качестве альтернативы использованию ARMarker.transformModeпередайте ARMarker отслеживаемый идентификатор объекта, чтобы ARMarkerManager.SetTransformMode(TrackableId, TransformMode) задать его режим преобразования.

В следующем коде показано получение нового размера QR-кода и центра, положение и поворот его преобразования, а также обновленное положение преобразования после изменения режима преобразования.

using System;
using Microsoft.MixedReality.OpenXR;

// ...

void OnMarkersChanged(ARMarkersChangedEventArgs args)
{
    Debug.Log($"Default transform mode is {ARMarkerManager.Instance.defaultTransformMode}./n");

    if (e.added.Count > 0)
    {
        ARMarker qrCode = args.added[0];

        Debug.Log($"Position: {qrCode.transform.position}");
        Debug.Log($"Rotation: {qrCode.transform.rotation}");
        Debug.Log($"Center: {qrCode.center}");

        if (qrCode.transformMode == TransformMode.Center)
            qrCode.transformMode = TransformMode.MostStable;
        else
            qrCode.transformMode = TransformMode.Center;

        Debug.Log($"QR code's transform mode is now set to {qrCode.transformMode}. /n");
        Debug.Log($"New position: {qrCode.transform.position}");
    }
}

Пример сценария маркера AR

Пример, предоставленный пакетом подключаемого модуля OpenXR, содержит сцену с поддержкой QR-кода, которая содержит пример использования ARMarkerManager и ARMarker его использования.

Сцена находится в assets > ARMarker , как показано ниже. Расположение ресурса сцены ARMarker

Скрипты C#, используемые на сцене, можно найти в репозитории примеров OpenXR Unity Смешанная реальность на сайте GitHub: /OpenXR-Unity-MixedReality-Samples/tree/main/SampleScenarios/Scripts/MarkerSample/Scripts

Поделиться через

QR-коды в Unity

Настройка проекта и приложения Unity

Получение подключаемого модуля OpenXR Смешанная реальность

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

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

Создание обнаружения QR-кода в сцене

Создание префаб для QR-кодов

Добавление визуальных элементов

Добавление `ARMarkerManager` в сцену

Отслеживание изменений QR-кода

Получение времени последнего обнаружения QR-кода

Использование отслеживаемого идентификатора QR-кода

После отслеживания QR-кода

Получение версии QR-кода и типа QR-кода

Чтение QR-данных

Получение размера QR-кода, позиции, поворота и центра

Пример сценария маркера AR

См. также

Дополнительные ресурсы

Поделиться через

QR-коды в Unity

Настройка проекта и приложения Unity

Получение подключаемого модуля OpenXR Смешанная реальность

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

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

Создание обнаружения QR-кода в сцене

Создание префаб для QR-кодов

Добавление визуальных элементов

Добавление ARMarkerManager в сцену

Отслеживание изменений QR-кода

Получение времени последнего обнаружения QR-кода

Использование отслеживаемого идентификатора QR-кода

После отслеживания QR-кода

Получение версии QR-кода и типа QR-кода

Чтение QR-данных

Получение размера QR-кода, позиции, поворота и центра

Пример сценария маркера AR

См. также

Дополнительные ресурсы

Добавление `ARMarkerManager` в сцену