Información general sobre el seguimiento de códigos QR

Para acceder al repositorio de GitHub para el ejemplo de código QR:

Seguimiento de códigos QR en Unity

Con los cascos windows Mixed Reality y HoloLens, la aplicación puede detectar códigos QR en el entorno alrededor de los cascos, estableciendo un sistema de coordenadas en la ubicación real de cada código. También puede representar hologramas en la misma ubicación en varios dispositivos para crear una experiencia compartida. Una vez que habilite la cámara web del dispositivo, reconocerá los códigos QR en las versiones más recientes de sus proyectos. Para obtener los mejores resultados en producción, se recomienda revisar la sección procedimientos recomendados .

En este artículo, aprenderá sobre:

• Dispositivos compatibles con el seguimiento de código QR
• Versiones de código QR admitidas
• Procedimientos recomendados para la detección de código QR
  • Zonas tranquilas alrededor de códigos QR
  • Iluminación y telón de fondo
  • Tamaño de códigos QR
  • Distancia y posición angular desde el código QR
  • Administración de datos de código QR
  • Ubicación de código QR en un espacio
• Solución de problemas y preguntas frecuentes
  • ¿Qué funcionalidades se necesitan?
  • Cómo hacer que la característica de seguimiento de código QR funcione en dispositivos HoloLens 2?
  • ¿Dónde encuentro los archivos del complemento de API?
  • Cómo preparar una aplicación de Unity para usar ARMarkerManager para detectar códigos QR?
  • Cómo preparar una aplicación que no sea de Unity para usar OpenXR para detectar códigos QR?
  • Cómo preparar una UWP para usar Microsoft.MixedReality.QR.QRCodeWatcher?
  • Cómo preparar Unity con Microsoft.MixedReality.QR.QRCodeWatcher?
  • ¿Cómo puedo hacer códigos QR?
  • Si el seguimiento de código QR no funciona en general, ¿qué hago?
  • ¿Cuál es la precisión?
  • ¿Qué tan cerca necesito estar en el código QR para detectarlo?
  • ¿Por qué no puedo leer códigos QR con logotipos?
  • Se detectan los códigos QR, ¿por qué no recibo datos?
  • ¿Se guardan códigos QR en el nivel de "espacio" o en el nivel de aplicación?
  • ¿Cómo funciona eso con la plataforma subyacente? ¿Dónde se conservan?
  • Cómo depurar la aplicación en Visual Studio cuando recibo el mensaje de error "Microsoft.MixedReality.QR.pdbno encontrado"?

Compatibilidad con dispositivos

Producto	HoloLens de 1.ª generación	HoloLens 2	Cascos envolventes
OpenXR		✔️ (con la extensión openXR Runtime versión 113 y OpenXR XR_MSFT_scene_marker )
Complemento de Unity de Mixed Reality		✔️ (con OpenXR Runtime versión 113 y complemento ARMarkerManagerde Unity de Mixed Reality )
SDK QR heredado	✔️	✔️	✔️

Nota:

Lo siguiente es específico de las API de código QR heredadas. Se recomienda usar la implementación de OpenXR para códigos QR en su lugar.

Con el SDK de código QR heredado, el seguimiento de código QR con cascos envolventes de Windows Mixed Reality en equipos de escritorio es compatible con Windows 10 versión 2004 y posteriores. Use la Microsoft.MixedReality.QRCodeWatcher.IsSupported() API para determinar si la característica es compatible con el dispositivo actual.

Versiones de código QR admitidas

En la tabla siguiente se enumeran las versiones de código QR admitidas y no admitidas:

	Versiones de código QR
Compatibles:	Código QR versiones 1 - 10 Micro códigos QR M1-M4 Todas las codificaciones
No se admite:	Códigos QR 10 - 20 (no totalmente compatible) Códigos QR versiones 21+ Módulos retocados, por ejemplo: módulos circulares, reflejos, invertidos (blanco/negro). Logotipos Anexos estructurados

Procedimientos recomendados para la detección de código QR

Zonas tranquilas alrededor de códigos QR

Para leer correctamente, los códigos QR requieren un margen alrededor de todos los lados del código. Este margen no debe contener ningún contenido impreso y debe ser cuatro módulos (un único cuadrado negro en el código).

La documentación oficial del código QR contiene más información sobre zonas tranquilas.

Iluminación y fondo

La calidad de detección de código QR es susceptible a diferentes iluminaciones y telón de fondo.

• En condiciones de iluminación normales, proporcione suficiente contraste para los módulos negros y blancos para mejorar el rendimiento.

• En condiciones extremas de iluminación con iluminación brillante o fondo oscuro, puede intentar reducir y ajustar el contraste que podría mejorar la tasa de detección de código QR. El fondo blanco dentro del código QR se puede reducir de 255 hacia abajo.

Tamaño de códigos QR

Los dispositivos Windows Mixed Reality y HoloLens no funcionan con códigos QR con lados inferiores a 5 cm.

Para códigos QR con lados que van de 5 cm a 10 cm, el dispositivo debe estar bastante cerca para detectar el código. Puede tardar más tiempo que el promedio en detectar el código.

El tiempo exacto para detectar códigos no solo depende del tamaño de los códigos QR, sino de la distancia que se encuentra del código. Acercarse al código ayudará a compensar los problemas con el tamaño.

Distancia y posición angular desde el código QR

Las cámaras de seguimiento solo pueden detectar un cierto nivel de detalle. Para códigos pequeños (menos de 10 cm a lo largo de los lados), debe estar bastante cerca. Para un código QR de versión 1 que varía de 10 cm a 25 cm de tamaño, la distancia de detección mínima está entre 0,15 metros y 0,5 metros.

La distancia de detección para el tamaño aumenta linealmente, pero también depende de la versión QR compatible o del tamaño del módulo. Cuanto mayor sea la versión, menor será el módulo, que solo se puede detectar desde una posición más cercana. También puede probar códigos micro-QR si desea que la distancia de detección sea más larga. La detección de QR funciona con un intervalo de ángulos += 45g para asegurarnos de que tenemos una resolución adecuada para detectar el código.

Otras consideraciones de detección:

• No se admiten códigos QR en superficies curvadas.
• Se admite la orientación en plano. Fuera del plano debe ser <= +-45 mirando directamente para tener una mejor detección.
• El tamaño físico del código QR debe tener módulos de al menos 2/3 píxeles. Nota: Las versiones posteriores de códigos QR tendrán módulos más pequeños.

Para ver la relación de equilibrio entre la distancia y el tamaño del código QR para una detección óptima, consulte el gráfico siguiente:

Importante

Asegúrese siempre de que tiene suficiente contraste y un borde adecuado.

Administración de datos de código QR

Los dispositivos Windows Mixed Reality y HoloLens detectan códigos QR en el nivel del sistema en el controlador. Cuando se reinicia el dispositivo o se reinicia el controlador, se borra el historial de códigos QR detectados. Los códigos QR detectados se tratan como nuevos objetos.

Se recomienda configurar la aplicación para omitir los códigos QR anteriores a una marca de tiempo específica, que se puede especificar dentro de la aplicación. La API de código QR especifica la hora en que se produjo la última detección. La mayoría de los desarrolladores de aplicaciones usarán la hora del sistema cuando se inicie la aplicación para determinar la hora en que se detecta un código QR.

Los datos de código QR no son específicos de la aplicación. Tras el inicio de la aplicación, habrá una lista de códigos QR disponibles que se proporcionan. El desarrollador de la aplicación determinará qué códigos QR son relevantes para esta aplicación.

Ubicación de código QR en un espacio

Para obtener recomendaciones sobre dónde y cómo colocar códigos QR, consulte Consideraciones de entorno para HoloLens.

Solución de problemas y preguntas frecuentes

¿Qué funcionalidades se necesitan?

Para habilitar el seguimiento de código QR en la aplicación HoloLens, agregue la funcionalidad webcam al manifiesto de la aplicación. Si está desarrollando en Unity, puede configurarlo desde la configuración del reproductor.

Además, el cuadro de diálogo de permisos puede solicitar a los usuarios que concedan permisos a la cámara web de la aplicación. Esto solo ocurre una vez durante la vigencia de una aplicación. En casos como la aplicación que solicita explícitamente el acceso a la cámara web, el cuadro de diálogo no volverá a aparecer.

En el caso de las aplicaciones de Unity con la funcionalidad WebCam, habilitar ARMarkerManager en una escena puede desencadenar el cuadro de diálogo de permiso de cámara web para que aparezca.

En el caso de las aplicaciones nativas de OpenXR C++, las llamadas iniciales a xrComputeNewSceneMSFT con que XrNewSceneComputeInfoMSFT::requestedFeatures contienen XR_SCENE_COMPUTE_FEATURE_MARKER_MSFT pueden desencadenar el cuadro de diálogo de permisos.

Nota:

Lo siguiente es específico de las API de código QR heredadas. Se recomienda usar la implementación de OpenXR para códigos QR en su lugar.

Necesitará la funcionalidad de cámara web agregada al manifiesto (casilla en Funcionalidades de Unity). Si vas a compilar como un proyecto de UWP estándar, también está en package.appxmanifest en el proyecto de solución.

En el SDK de código QR heredado, solicite acceso mediante una llamada al método siguiente:

#if WINDOWS_UWP

async QRCodeWatcher.RequestAccessAsync();

#endif

El estado de acceso debe ser (status == QRCodeWatcherAccessStatus::Allowed).

Si se deniega el acceso, la característica devolverá el acceso denegado al iniciar .QRTracking

Se debe llamar a esta API antes de construir el QRCodeWatcher objeto .

Si ejecuta el proyecto desde Unity, también debe asegurarse de que llama desde el subproceso de la interfaz de usuario. De lo contrario, la API siempre devolverá denegada. Para obtener más información, consulte La clase AppCallbacks en el Manual de Unity.

Para obtener más información sobre cómo configurar el proyecto para Unity, consulte Configuración de Unity para Windows Mixed Reality.

Cómo hacer que la característica de seguimiento de código QR funcione en dispositivos HoloLens 2?

El seguimiento QR es automático en HoloLens 2 y necesitará la funcionalidad "webcam" agregada a la aplicación.

¿Dónde encuentro los archivos del complemento de API?

Las aplicaciones deben usar el entorno de ejecución de OpenXR de HoloLen para detectar códigos QR. OpenXR para Windows Mixed Reality (113.2403.5001 o posterior) proporciona compatibilidad con código QR en dispositivos HoloLens.

En el caso de las aplicaciones de Unity, la compatibilidad con código QR se proporciona a través del ARMarkerManager componente proporcionado con el complemento OpenXR de Mixed Reality.

Para la compatibilidad con código QR en aplicaciones que no son de Unity, use la extensión openXR XR_MSFT_scene_marker .

Nota:

Lo siguiente es específico de las API de código QR heredadas. Se recomienda usar la implementación de OpenXR para códigos QR en su lugar.

Todos los archivos y documentación necesarios se pueden encontrar aquí en NuGet aquí:

Microsoft.MixedReality.QR

Cómo preparar una aplicación de Unity para usar ARMarkerManager para detectar códigos QR?

En las aplicaciones de Unity, el ARMarkerManager componente se usa para controlar cómo se representa la detección de código QR dentro de un entorno físico en una escena. ARMarkerManager Proporciona:

• Eventos para notificar a los suscriptores cuando se ha agregado un código QR detectado al administrador, actualizado o quitado.

• Colección de ARMarker pistas para códigos QR en detección.

• Métodos que devuelven datos para códigos QR, tal y como se especifica mediante id. de seguimiento.

Para usarlo ARMarkerManager en la aplicación, debe importar el paquete del complemento OpenXR de Mixed Reality.

Para importar el paquete:

1. Descargue y ejecute la herramienta de características de Mixed Reality.
2. Instale el complemento OpenXR.

Consulte Welcome to the Mixed Reality Feature Tool (Herramienta de características de Mixed Reality) para obtener instrucciones detalladas sobre cómo usar la herramienta.

El procedimiento general siguiente es:

1. En el proyecto de Unity, habilite las funcionalidades de WebCam .
2. Cree un objeto prefabricado y adjunte el ARMarker componente como se muestra:
   
3. Abra una escena que quiera que se detecten códigos QR al ejecutarse.
4. Adjunte ARMarkerManager a gameObject en la escena y establezca Marker Prefab en el objeto prefabricado que creó.
   

Para obtener instrucciones e información más detalladas, vaya a Códigos QR en Unity.

Para obtener un ejemplo de cómo usar códigos QR en la aplicación de Unity, consulte el escenario de ejemplo de código QR en GitHub.

Cómo preparar una aplicación que no sea de Unity para usar OpenXR para detectar códigos QR?

La detección de código QR en OpenXR se proporciona a través de la extensión XR_MSFT_scene_marker . Esta extensión permite realizar un seguimiento de varios códigos QR y puede proporcionar datos de tamaño, posición, marca de tiempo de última detección, UUID y códigos QR almacenados en búfer para códigos QR detectados.

Para habilitar la compatibilidad con código QR, se deben habilitar las extensiones XR_MSFT_scene_marker y XR_MSFT_scene_understanding .

Para obtener información detallada detallada sobre la extensión XR_MSFT_scene_marker en la especificación OpenXR 1.0.

Para obtener un ejemplo de cómo usar códigos QR, consulte Scene_QRCode.cpp en el ejemplo SceneUnderstandingUwp en GitHub.

Cómo preparar una UWP para usar Microsoft.MixedReality.QR.QRCodeWatcher?

Nota:

Lo siguiente es específico de las API de código QR heredadas. Se recomienda usar la implementación de OpenXR para códigos QR en su lugar.

• Use el paquete NuGet para desempaquetar los archivos necesarios.

• Agregue una referencia al en el Microsoft.MixedReality.QR.winmd proyecto y empiece a usar la API.

• Agregue las versiones de arquitectura correctas de los complementos y úselas en consecuencia en la compilación.

Cómo preparar Unity con Microsoft.MixedReality.QR.QRCodeWatcher?

Nota:

Lo siguiente es específico de las API de código QR heredadas. Se recomienda usar la implementación de OpenXR para códigos QR en su lugar.

Use NuGet para Unity y apunte al paquete nuGet anterior.

¿Cómo puedo hacer códigos QR?

Consulte cualquier generador de código QR.

Si el seguimiento de código QR no funciona en general, ¿qué hago?

• ¿Es la versión del código QR una versión compatible? No se admiten las versiones de alta densidad como la versión 40. No se garantiza nada por encima de la versión 10; No se admiten versiones anteriores a 20.

• ¿Está lo suficientemente cerca del código QR? Vea la distancia y la posición angular desde el código QR.

• ¿Cómo está la iluminación? Hay un problema conocido en el que la detección se vuelve difícil cuando el código QR está en un fondo ambiental oscuro, el código QR aparecerá lavado a la cámara debido al contraste alto. Para obtener más información, consulte iluminación y telón de fondo.

¿Cuál es la precisión?

Cuando se detecta en un solo fotograma, se espera que el tamaño tenga como máximo un error del 1 % del tamaño real. Por ejemplo, un código de 10 cm puede ser de hasta +/- 1 mm desactivado en tamaño medido. En la detección continua, la posición de un código puede desplazarse por hasta +/- 2,5 mm. Una vez que se haya movido fuera del intervalo de detección, la posición de una detección anterior es la misericordia del error del mapa.

¿Qué tan cerca necesito estar en el código QR para detectarlo?

La distancia obviamente depende del tamaño del código QR, y también de la versión que es. Para obtener más información, consulte distancia y posición angular desde el código QR.

• En HoloLens 2, para un código QR de versión 1 que varía de 5 cm a 25 cm de lados, la distancia de detección mínima oscila entre 0,25 metros y 0,5 metros. El más alejado de estos se puede detectar desde va de aproximadamente 0,5 m para el código más pequeño a dos metros para el mayor.

• En Windows Mixed Reality, estas distancias para los tamaños se reducen a la mitad.

• Para los códigos más grandes, extrapolar la distancia de detección para el tamaño aumenta linealmente. Para cualquier código más pequeño, la detección simplemente no se producirá---4-5 cm es la más pequeña que podemos detectar.

¿Por qué no puedo leer códigos QR con logotipos?

No se admiten códigos QR con logotipos.

Se detectan los códigos QR, ¿por qué no recibo datos?

• Si la plataforma no puede descodificar el código QR, no habrá datos. Puede usar la secuencia e interpretar los datos mediante código abierto.

• Algunas características, como la anexión de la estructura, no se admiten.

Para obtener más información, consulte ¿qué versiones de código QR se admiten?.

¿Se guardan códigos QR en el nivel de "espacio" o en el nivel de aplicación?

Los códigos QR se guardan en el nivel del sistema en la sesión del controlador o en la sesión de arranque en HoloLens. Para obtener más información, consulte Administración de datos de código QR.

¿Cómo funciona eso con la plataforma subyacente? ¿Dónde se conservan?

El controlador conserva los códigos QR detectados en la memoria.

Cómo depurar la aplicación en Visual Studio cuando recibo el mensaje de error "Microsoft.MixedReality.QR.pdbno encontrado"?

Nota:

Lo siguiente es específico de las API de código QR heredadas. Se recomienda usar la implementación de OpenXR para códigos QR en su lugar.

Se omitió la carga de símbolos para Microsoft.MixedReality.QR.dll porque no se especifica en la lista de módulos incluidos.

Pasos de reproducción

Nota:

Lo siguiente es específico de las API de código QR heredadas. Se recomienda usar la implementación de OpenXR para códigos QR en su lugar.

Siga los pasos para reproducir este comportamiento:

1. Instalación de Microsoft.MixedReality.QR (NuGet) y MRTK
2. Intente depurar

Debería poder depurar la aplicación con Microsoft.MixedReality.QR.dll, pero no se encuentra el archivo DLL:

Solución recomendada

Nota:

Lo siguiente es específico de las API de código QR heredadas. Se recomienda usar la implementación de OpenXR para códigos QR en su lugar.

Estamos trabajando para agregar símbolos a la próxima versión. Mientras tanto, debería poder depurar la aplicación excluyendo el archivo DLL en las opciones de Visual Studio:

Para obtener más información, consulte Configuración de la configuración de Visual Studio.

¿Hay un límite de cuántos códigos QR se pueden examinar en una sesión?

Hay un límite de 100 códigos QR guardados en el nivel del sistema en el controlador, en un plazo de 10 minutos.

¿Ha cambiado el proceso de suavizado de código QR?

El proceso de suavizado de código QR cambió después de 20H2, desde el suavizado de la posición hasta el suavizado de tamaño. Para revertir el comportamiento al proceso de suavizado anterior, se aplicaría un algoritmo de suavizado si el nuevo código QR posa los datos se detectan en un plazo de 5 segundos o 10 cm del marco detectado anteriormente. Los datos de transformación se mezclan a través de una relación ponderada del 90 % del marco actual con el 10 % del fotograma anterior.

Consulte también

• Seguimiento de código QR con ejemplos nativos de C++ y C#
• Sistemas de coordenadas
• Azure Spatial Anchors
• Introducción a la cámara Locatable de HoloLens 2