Общие сведения об отслеживании QR-кодов

Статья
05/24/2024

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

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

В этой статье описано следующее:

Поддерживаемые устройства для отслеживания QR-кода
Поддерживаемые версии QR-кода
Рекомендации по обнаружению QR-кода
Устранение неполадок и часто задаваемые вопросы

Поддержка устройств

Продукт	HoloLens (1-го поколения)	HoloLens 2	Иммерсивные гарнитуры
OpenXR		✔️ (с расширением OpenXR Runtime версии 113 и OpenXR XR_MSFT_scene_marker )
Подключаемый модуль Unity Смешанная реальность		✔️ (с подключаемым модулем `ARMarkerManager`OpenXR Runtime версии 113 и Смешанная реальность Unity )
Устаревший QR-пакет SDK	✔️	✔️	✔️

Примечание.

Ниже приведены устаревшие API QR-кода. Вместо этого рекомендуется использовать реализацию OpenXR для QR-кодов.

Используя устаревший пакет SDK QR-кода, отслеживание QR-кода с иммерсивными гарнитурами Windows Смешанная реальность на настольных компьютерах поддерживается в Windows 10 версии 2004 и более поздних версиях. Microsoft.MixedReality.QRCodeWatcher.IsSupported() Используйте API, чтобы определить, поддерживается ли функция на текущем устройстве.

Поддерживаемые версии QR-кода

В следующей таблице перечислены поддерживаемые и неподдерживаемые версии QR-кода:

	Версии QR-кода
Поддерживается:	QR-код версии 1 – 10 Микро QR-коды M1-M4 Все кодировки
Не поддерживается:	QR-коды 10 – 20 (не полностью поддерживаются) QR-коды версии 21+ Отключаемые модули, например циклические модули, отражения, инвертированные (черно-белый). Логотипы Структурированные добавления

Рекомендации по обнаружению QR-кода

Тихие зоны вокруг QR-кодов

Для правильного чтения QR-кодов требуется поле вокруг всех сторон кода. Это поле не должно содержать печатное содержимое и должно быть четыре модуля (один черный квадрат в коде).

Официальная документация по QR-коду содержит дополнительные сведения о тихих зонах.

Освещение и фон

Качество обнаружения QR-кода подвержено различным освещению и фону.

В обычных условиях освещения обеспечивает достаточную контрастность для черных и белых модулей для повышения производительности.
В экстремальных условиях освещения с ярким освещением или темным фоном можно попытаться уменьшить и настроить контрастность, которая может повысить скорость обнаружения QR-кода. Белый фон в QR-коде может быть сокращен с 255 вниз.

Размер QR-кодов

Устройства Windows Смешанная реальность и HoloLens не работают с QR-кодами с сторонами меньше 5 см.

Для QR-кодов с сторонами от 5 см до 10 см устройство должно быть достаточно близко для обнаружения кода. Для обнаружения кода может потребоваться больше времени, чем в среднем.

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

Расстояние и угловое положение от QR-кода

Камеры отслеживания могут обнаруживать только определенный уровень детализации. Для небольших кодов (менее 10 см вдоль сторон), необходимо быть достаточно близким. Для QR-кода версии 1 от 10 см до 25 см размером минимальное расстояние обнаружения составляет от 0,15 метров до 0,5 метра.

Расстояние обнаружения для размера увеличивается линейно, но также зависит от поддерживаемой QR-версии или размера модуля. Чем выше версия, тем меньше модули, которые можно обнаружить только из более близкой позиции. Вы также можете попробовать микро QR-коды, если вы хотите, чтобы расстояние обнаружения было длиннее. Qr-обнаружение работает с диапазоном углов += 45 дег, чтобы обеспечить правильное разрешение для обнаружения кода.

Другие рекомендации по обнаружению:

QR-коды на кривых поверхностях не поддерживаются.
Поддерживается ориентация на плоскости. Вне плоскости должно быть <= +-45 глядя прямо на, чтобы иметь лучшее обнаружение.
Физический размер QR-кода должен содержать модули не менее 2/3 пикселей. Примечание. Более высокие версии QR-кодов будут иметь меньшие модули.

Сведения о компромиссе между расстоянием и размером QR-кода для оптимального обнаружения см. в следующем графе:

Внимание

Всегда убедитесь, что у вас достаточно контрастности и правильной границы.

Управление ДАННЫМи QR-кода

Устройства Windows Смешанная реальность и HoloLens обнаруживают QR-коды на уровне системы в драйвере. Когда устройство перезагружается или драйвер перезапускается, журнал обнаруженных QR-кодов очищается. QR-коды повторно обрабатываются как новые объекты.

Рекомендуется настроить приложение, чтобы игнорировать QR-коды старше определенной метки времени, которая может быть указана в приложении. API QR-кода указывает время последнего обнаружения. Большинство разработчиков приложений будут использовать системное время запуска приложения для определения времени обнаружения QR-кода.

ДАННЫЕ QR-кода не зависят от приложения. После запуска приложения появится список доступных QR-кодов. Разработчик приложения определит, какие QR-коды относятся к этому приложению.

Размещение QR-кода в пространстве

Рекомендации о том, где и как размещать QR-коды, см . в рекомендациях по среде для HoloLens.

Устранение неполадок + вопросы и ответы

Какие возможности необходимы?

Чтобы включить отслеживание QR-кода в приложении HoloLens, добавьте возможность веб-камеры в манифест приложения. Если вы разрабатываетесь в Unity, это можно настроить в параметрах проигрывателя.

Кроме того, пользователям может быть предложено в диалоговом окне разрешений предоставить веб-камере приложения разрешения. Это происходит только один раз за время существования приложения. В таких случаях, как приложение явно запрашивает доступ к веб-камере, диалоговое окно не будет повторно появляться.

Для приложений Unity с возможностью WebCam, включение ARMarkerManager в сцене может активировать диалоговое окно разрешений веб-камеры.

Для собственных приложений OpenXR C++ начальные вызовы xrComputeNewSceneMSFT с XrNewSceneComputeInfoMSFT::requestedFeatures содержащими XR_SCENE_COMPUTE_FEATURE_MARKER_MSFT могут активировать диалоговое окно разрешений.

Примечание.

Ниже приведены устаревшие API QR-кода. Вместо этого рекомендуется использовать реализацию OpenXR для QR-кодов.

Вам потребуется возможность веб-камеры, добавленная в манифест (флажок в возможностях Unity). Если вы создаете стандартный проект UWP, он также находится в пакете.appxmanifest в проекте решения.

В устаревшем пакете SDK QR-кода запросите доступ, вызвав следующий метод:

#if WINDOWS_UWP

async QRCodeWatcher.RequestAccessAsync();

#endif

Состояние доступа должно быть (status == QRCodeWatcherAccessStatus::Allowed).

Если доступ запрещен, функция вернет доступ, отказано в доступе QRTrackingпри запуске.

Перед созданием QRCodeWatcher объекта необходимо вызвать этот API.

Если вы запускаете проект из Unity, необходимо также убедиться, что вы вызываете из потока пользовательского интерфейса. В противном случае API всегда возвращает отказ. Дополнительные сведения см . в разделе AppCallbacks класса в Unity Manual.

Дополнительные сведения о настройке проекта для Unity см. в статье о настройке Unity для Windows Смешанная реальность.

Разделы справки сделать функцию отслеживания QR-кода работой на устройствах HoloLens 2?

QR-отслеживание выполняется автоматически в HoloLens 2, и вам потребуется возможность "веб-камера", добавленная в приложение.

Где найти файлы подключаемого модуля API?

Приложения должны использовать среду выполнения OpenXR HoloLen для обнаружения QR-кодов. OpenXR для Windows Смешанная реальность (113.2403.5001 или более поздней версии) обеспечивает поддержку QR-кода на устройствах HoloLens.

Для приложений Unity поддержка QR-кода предоставляется через компонент, предоставляемый ARMarkerManager с Смешанная реальность подключаемым модулем OpenXR.

Для поддержки QR-кода в приложениях, отличных от Unity, используйте расширение OpenXR XR_MSFT_scene_marker .

Примечание.

Ниже приведены устаревшие API QR-кода. Вместо этого рекомендуется использовать реализацию OpenXR для QR-кодов.

Все необходимые файлы и документацию можно найти здесь в NuGet:

Microsoft.MixedReality.QR

Разделы справки подготовить приложение Unity для обнаружения QR-кодов с помощью ARMarkerManager?

В приложениях ARMarkerManager Unity компонент используется для обработки обнаружения QR-кода в физической среде, представленной в сцене. ARMarkerManager Предоставляет:

События для уведомления подписчиков о добавлении обнаруженного QR-кода в диспетчер, обновление или удаление.
Коллекция ARMarker отслеживаемых кодов ДЛЯ QR-кодов при обнаружении.
Методы, возвращающие данные для QR-кодов, указанные отслеживаемым идентификатором.

Чтобы использовать ARMarkerManager в приложении, необходимо импортировать пакет подключаемого модуля OpenXR Смешанная реальность.

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

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

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

Далее приведена общая процедура:

В проекте Unity включите возможности WebCam .
Создайте префаб и подключите ARMarker компонент, как показано ниже.
Откройте сцену, которую вы хотите обнаружить QR-коды при выполнении.
Подключитесь ARMarkerManager к GameObject в сцене и задайте для предварительно созданного префаба маркера.

Дополнительные инструкции и сведения см. в QR-кодах в Unity.

Пример использования QR-кодов в приложении Unity см . в примере QR-кода на сайте GitHub.

Разделы справки подготовить приложение, отличное от Unity, для обнаружения QR-кодов с помощью OpenXR?

Обнаружение QR-кода в OpenXR предоставляется через расширение XR_MSFT_scene_marker . Это расширение позволяет отслеживать несколько QR-кодов и предоставлять размер, позицию, метку времени последнего обнаружения, UUID и буферные данные QR-кода для обнаруженных QR-кодов.

Чтобы включить поддержку QR-кода, необходимо включить как XR_MSFT_scene_marker, так и XR_MSFT_scene_understanding расширения.

Подробные пошаговые инструкции см . в обзоре расширения XR_MSFT_scene_marker в спецификации OpenXR 1.0.

Пример использования QR-кодов см. в разделе Scene_QRCode.cpp в примере SceneUnderstandingUwp на сайте GitHub.

Разделы справки подготовить UWP к использованию Microsoft.MixedReality.QR.QRCodeWatcher?

Примечание.

Ниже приведены устаревшие API QR-кода. Вместо этого рекомендуется использовать реализацию OpenXR для QR-кодов.

Используйте пакет NuGet для распаковки необходимых файлов.
Добавьте ссылку на Microsoft.MixedReality.QR.winmd проект и начните использовать API.
Добавьте правильные версии архитектуры подключаемых модулей и используйте их соответствующим образом в сборке.

Разделы справки подготовить Unity с помощью Microsoft.MixedReality.QR.QRCodeWatcher?

Примечание.

Ниже приведены устаревшие API QR-кода. Вместо этого рекомендуется использовать реализацию OpenXR для QR-кодов.

Используйте NuGet для Unity и наведите указатель на пакет NuGet выше.

Как сделать QR-коды?

Ознакомьтесь с любым генератором QR-кода.

Если отслеживание QR-кода не работает в целом, что делать?

Поддерживается ли версия QR-кода? Мы не поддерживаем версии высокой плотности, такие как версия 40. Ничего выше версии 10 не гарантируется; Версии выше 20 не поддерживаются.
Вы достаточно близко к QR-коду? Просмотрите расстояние и угловую позицию из QR-кода.
Как освещение? Существует известная проблема, из-за которой обнаружение становится трудным, когда QR-код находится на темном фоновом фоне окружающей среды- QR-код будет вымываться на камеру из-за высокой контрастности. Дополнительные сведения см. в разделе освещения и фона.

Какова точность?

При обнаружении в одном кадре размер, как ожидается, имеет не более 1 % ошибки из фактического размера. Например, код размером 10 см может составлять до +/- 1 мм в измеренном размере. При непрерывном обнаружении позиция кода может перемещаться на 2,5 мм до +/-2,5 мм. После того как вы перешли из диапазона обнаружения, позиция предыдущего обнаружения выполняется до мерсии ошибки карты.

Насколько близко к QR-коду, чтобы обнаружить его?

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

На HoloLens 2 для QR-кода версии 1 от 5 см до 25 см стороны минимальное расстояние обнаружения от 0,25 метров до 0,5 метра. Самый дальний из них можно обнаружить с около 0,5 м для наименьшего кода до двух метров для большего.
В Windows Смешанная реальность эти расстояния для размеров сокращены.
Для любых кодов больше экстраполяцию — расстояние обнаружения для размера увеличивается линейно. Для любого кода меньше обнаружение просто не будет происходить--4-5 см является самым маленьким, который мы можем обнаружить.

Почему я не могу читать QR-коды с логотипами?

QR-коды с логотипами не поддерживаются.

Обнаружены QR-коды, поэтому почему я не получаю данных?

Если платформа не может декодировать QR-код, данные не будут. Поток можно использовать и интерпретировать данные с помощью открытого исходного кода.
Некоторые функции, такие как добавление структуры, не поддерживаются.

Дополнительные сведения см . в том, какие версии QR-кода поддерживаются?.

Сохраняются ли QR-коды на уровне "пробел" или на уровне приложения?

QR-коды сохраняются на уровне системы в сеансе драйвера или сеансе загрузки в HoloLens. Дополнительные сведения см. в статье об управлении данными QR-кода.

Как это работает с базовой платформой? Где они сохраняются?

Обнаруженные QR-коды сохраняются в памяти драйвером.

Разделы справки отладку приложения в Visual Studio при получении сообщения об ошибке "`Microsoft.MixedReality.QR.pdb`не найдено"?

Примечание.

Ниже приведены устаревшие API QR-кода. Вместо этого рекомендуется использовать реализацию OpenXR для QR-кодов.

Загрузка символов для Microsoft.MixedReality.QR.dll пропущена, так как она не указана в списке включенных модулей.

Воспроизведение

Примечание.

Ниже приведены устаревшие API QR-кода. Вместо этого рекомендуется использовать реализацию OpenXR для QR-кодов.

Выполните действия, чтобы воспроизвести это поведение:

Установка Microsoft.MixedReality.QR (NuGet) и MRTK
Попробуйте выполнить отладку

Вы должны иметь возможность отладки приложения с помощью Microsoft.MixedReality.QR.dll, но библиотека DLL не найдена:

Сообщение об ошибке Microsoft.MixedReality.QR.pdb не найдено

Существует ли ограничение количества QR-кодов, которые можно сканировать в сеансе?

Существует ограничение в 100 QR-кодов, сохраненных на уровне системы в драйвере в течение 10 минут.

Изменился процесс сглаживания QR-кода?

Процесс сглаживания QR-кода изменился после 20H2, от сглаживания до размера сглаживания. Чтобы вернуть поведение к предыдущему процессу сглаживания, следует применить алгоритм сглаживания, если новые данные qr-кода обнаруживаются в течение 5 секунд или 10 см от ранее обнаруженного кадра. Данные преобразования смешиваются с помощью взвешированного соотношения от 90% текущего кадра с 10% предыдущего кадра.

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

Общие сведения об отслеживании QR-кодов

Поддержка устройств

Поддерживаемые версии QR-кода