Códigos QR en Unity

Artículo
02/18/2025

HoloLens 2 auriculares pueden realizar un seguimiento y detectar códigos QR que se pueden usar para proporcionar hologramas y otras características de AR. Este artículo le guía por todo lo que necesita saber para empezar a usar códigos QR en su aplicación de Unity, entre los que se incluyen:

Agregar la detección de código QR a la aplicación de Unity.
Descripción de los conceptos importantes y los componentes de Unity que necesita usar.
Proporciona tutoriales que tratan el uso común de código QR.
Presenta el escenario de ejemplo marcador de AR que muestra una escena habilitada para código QR y scripts de ejemplo.

Antes de continuar con este artículo, le recomendamos que pase por la introducción a los códigos QR.

Código QR de seguimiento

Configuración del proyecto y la aplicación de Unity

El proyecto y la aplicación de Unity deben configurarse y configurarse correctamente para habilitar la funcionalidad de código QR, que requiere:

OpenXR para Windows Mixed Reality versión 113.2403.5001 o posterior.

Nota:

Esto viene con el sistema operativo y se puede actualizar a través de la Tienda Windows. Tenga en cuenta que es posible que los usuarios tengan instaladas versiones anteriores y que sus dispositivos no podrán trabajar con marcadores de AR, como códigos QR, hasta que se actualicen a la versión 113.2403.5001 o posterior.
Un proyecto compatible con una versión compatible de Unity:
- Unity 2022.3 LTS (recomendado)
- Unity 2021.3 LTS
El complemento Mixed Reality OpenXR.
Funcionalidades de cámara web habilitadas para el proyecto de Unity.
Permisos de cámara concedidos a la aplicación.

En las secciones siguientes se explica cómo configurar el proyecto y la aplicación de Unity para habilitar la detección de código QR.

Obtención del complemento Mixed Reality OpenXR

El paquete del complemento Mixed Reality OpenXR contiene las API de C# que puede usar para acceder a la funcionalidad de código QR.

Para importar el paquete:

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

La Mixed Reality Feature Tool también simplifica la administración de paquetes y se puede usar para buscar, actualizar y agregar las características Mixed Reality que requiere la aplicación. Consulte Welcome to the Mixed Reality Feature Tool (Bienvenido a la herramienta de características de Mixed Reality) para obtener instrucciones detalladas sobre cómo usar la herramienta.

Habilitación de las funcionalidades de WebCam

Para detectar y realizar un seguimiento de los códigos QR, el proyecto de Unity debe tener habilitadas las funcionalidades de WebCam .

Para habilitar las funcionalidades de WebCam :

Abra el proyecto de Unity.
Haga clic en Editar en el menú de la aplicación del editor de Unity.
Ve al Reproductor de configuración del > proyecto y selecciona la pestaña UWP como se muestra:
Habilite WebCam en la lista de funcionalidades .
Salga de Configuración del proyecto.

Las funcionalidades de WebCam ahora están habilitadas para la aplicación de Unity. Sin embargo, a la aplicación todavía se le deben conceder permisos para acceder a la cámara del dispositivo.

Concesión de permisos de acceso a la cámara de la aplicación

Si la aplicación tiene habilitadas las funcionalidades de WebCam , el cuadro de diálogo de permisos solicita a los usuarios que concedan acceso a la aplicación a la cámara del dispositivo.

Cuadro de diálogo Permisos de cámara

Este cuadro de diálogo se muestra a los usuarios solo una vez, normalmente al escribir una escena que contiene una compatibilidad con marcadores ARMarkerManager de código QR habilitada. Si se deniega el acceso a la cámara, los usuarios pueden ir a Aplicaciones de configuración > y habilitarlo a través de las Opciones avanzadas de la aplicación.

Opciones avanzadas de la aplicación con permisos habilitados

Creación de la detección de código QR en una escena

La detección de código QR debe estar integrada en todas las escenas en las que quiera usar códigos QR, lo que requiere:

Con GameObjectARMarkerManager adjunto. ARMarkerManager es el único responsable de crear, actualizar y quitar todos los GameObject códigos QR detectados.
Un objeto prefabricado con ARMarker adjunto.
ARMarkerManager configurado para usar el objeto prefabricado al crear cuando GameObject se detecta un código QR.

Creación de un objeto prefabricado para códigos QR

Para usar códigos QR en la escena, debe crear un objeto prefab para códigos QR. ARMarkerManager usa este objeto prefabricado para crear a GameObject partir de cada vez que se detecta un código QR.

Para crear un objeto prefab para códigos QR:

Cree un nuevo objeto prefabricado para el proyecto.
Agregue el ARMarkercomponente al objeto prefabricado, ubicado en Script > Microsoft.MixedReality.OpenXR > ARMarker.

Ahora tiene un prefabricado básico con el que trabajar. Es probable que quiera que la aplicación represente visualmente los códigos QR que se detectan en el entorno. La siguiente sección le guiará a través de cómo agregar una representación visual para códigos QR.

Agregar objetos visuales

En la sección anterior, al agregar ARMarkeral objeto prefabricado también se agregó automáticamente el ARMarkerScale componente. Este componente se usa para hacer coincidir la escala de la representación visual de un código QR con su homólogo físico.

Para ello:

Agregue un elemento vacío GameObject al objeto prefabricado que creó en la sección anterior. Representará todo el contenido del marcador visual.
Agregue un elemento 3D GameObjectsecundario, como , Quadal contenido GameObjectdel marcador .
En el componente del ARMarkerScale objeto prefabricado, establezca La transformación de escala de marcadores en el contenido GameObjectdel marcador . Al establecer este campo, se garantiza que el 3D GameObject que eligió se escala correctamente para que coincida con los códigos QR del mundo real.

Agregar `ARMarkerManager` a una escena

ARMarkerManager es el único responsable de crear, actualizar y quitar todos los GameObject códigos QR detectados.

Para agregar ARMarkerManager a la escena:

Coloque un objeto GameObject en su escena.
Agregue el ARMarkerManager componente a GameObject, ubicado en Script > Microsoft.MixedReality.OpenXR > ARMarkerManager.
Establezca el ARMarkerManager campo Marcador prefab en el objeto prefabricado que creó en la sección anterior.
Expanda Tipos de marcador habilitados, elija un elemento y establézcalo en Código QR.

Realizar un seguimiento de los cambios de código QR

ARMarkerManager contiene el markersChanged evento , que proporciona a los ARMarkersChangedEventArgs suscriptores. Use estos argumentos de evento para realizar un seguimiento de los códigos QR que se agregan o quitan de la detección o de los datos de pose actualizados.

En el código siguiente se muestra cómo suscribirse al ARMarkerManager.markersChanged evento, el uso de sus argumentos de evento para recorrer en iteración los ARMarker objetos ARMarkerManager controla y escribe en Depurar si se agregan, quitan o actualizan.

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}");
    }
}

Obtención de la hora en que se detectó por última vez un código QR

Use la ARMarker.lastSeenTime propiedad para determinar cuándo el dispositivo resonó por última vez un código QR detectado y la cantidad de tiempo, si existe, se pierde el seguimiento. El tiempo se mide en el número de segundos desde que Unity inició la aplicación y es análogo a UnityEngine.Time.realtimeSinceStartup.

Uso del identificador de seguimiento de un código QR

Los códigos QR son rastreables, que son cualquier cosa que un dispositivo de AR pueda detectar y realizar un seguimiento en un entorno físico. Los objetos de seguimiento se derivan del tipo ARTrackable<TSessionRelativeData, TTrackable> que proporciona un identificador, un estado de seguimiento, una posición y otros datos.

El identificador de seguimiento de un código QR se puede pasar a ARMarkerManager métodos para obtener las propiedades del código QR, los datos de bytes sin procesar y la representación de cadena, y para establecer el modo de transformación para el código QR. Estos métodos permiten recuperar datos de un código QR sin tener que mantener una referencia de ARMarker objeto.

Puede pasar el identificador de un código QR a los métodos siguientes ARMarkerManager :

Nota:

Para el parámetro allocatorde GetRawData método , el paso Unity.Collections.Allocator.Temp es suficiente para la mayoría de los escenarios.

Seguimiento del estado de seguimiento de un código QR

Dado que se puede realizar el seguimiento de un ARMarker objeto , hereda la trackingState propiedad y se establece en uno de los tres UnityEngine.XR.ARSubsystems.TrackingState:

Limited: indica que se está realizando el seguimiento del código QR, pero que hay información limitada disponible o que es de mala calidad.
Tracking: especifica que se está realizando un seguimiento completo del código QR.
None: indica que no se está realizando el seguimiento del código QR.

Para supervisar el estado de seguimiento de un código QR, suscríbase a ARMarkerManager.markersChanged y recorra en iteración las ARMarker colecciones de marcadores proporcionadas en los argumentos de evento pasados al controlador de eventos.

En el código siguiente se muestra cómo usar el ARMarkerManager.markersChanged evento para recorrer en iteración ARMarker los objetos de los códigos QR recién detectados y escribir su identificador de seguimiento en la ventana Depurar.

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.");
    }
}

Obtención de la versión de un código QR y el tipo de código QR

Para obtener la versión y el tipo de un código QR detectado:

Llame a ARMarker.GetQRCodeProperties(), que devuelve una QRCodeProperties instancia de .
Acceda al campo QRCodeProperties del valor devuelto para obtener el tipo de código QR. El valor es o QRCodeType.QRCodeQRCodeType.MicroQRCode.
Acceda al campo del QRCodeProperties.version valor devuelto para obtener la versión del código QR. El valor oscila entre 1 y 40 si el tipo es QRCodeType.QRCodey de 1 a 4 si el tipo es QRCodeType.MicroQRCode.

Como alternativa, pase el identificador de seguimiento de un ARMarker objeto a ARMarkerManager.GetQRCodeProperties(TrackableId) para obtener el tipo y la versión de un código QR.

Advertencia

Los códigos QR son el único tipo de marcador que se admite actualmente, aunque se puede agregar compatibilidad con otros tipos de marcadores en futuras versiones. Si markerType no ARMarkerType.QRCodees , la llamada GetQRCodeProperties(TrackableId) produce System.InvalidOperationException. Considere la posibilidad de ajustar las llamadas a GetQRCodeProperties(TrackableId) en bloques try-catch si esto podría causar problemas en la aplicación más adelante.

Lectura de datos QR

El ARMarker componente se asocia a cada GameObject elemento que ARMarkerManager crea. ARMarker proporciona dos métodos que devuelven datos de código QR:

GetDecodedString(): este método obtiene la representación de cadena del código QR, como una dirección URL.
GetRawData(Unity.Collections.Allocator allocator): este método devuelve contenido de código QR como una matriz de bytes, lo que permite un ajuste preciso de cómo se asigna la matriz. Use este método en rutas de acceso frecuentes y en otras situaciones en las que el rendimiento sea crítico.

En el código siguiente se muestra el uso básico de GetDecodedString() y 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();
    }
}

Obtención del tamaño, la posición, la rotación y el centro del código QR

Un ARMarker objeto proporciona el tamaño, la posición, la rotación y el centro del código QR que representa.

Para obtener el tamaño del código QR en metros, use la propiedad ARMarker.size.

Utilice la ARMarker.transform propiedad para obtener la rotación y la posición del espacio del mundo de la transformación del código QR y ARMarker.center las coordenadas 2D del código QR en relación con la transformación del código QR. La transformación en sí se centra en función de si ARMarker.transformMode (el modo de transformación) está establecido TransformMode.MostStable en (más estable, el código QR de la parte superior izquierda) o TransformMode.Center (centro, el centro geométrico del código QR).

Use el ARMarkerManager.defaultTransformMode campo para establecer el modo ARMarkerManager de transformación con el que se crean nuevos ARMarker objetos. El campo se inicializa con el Default Transform Mode campo establecido en en el inspector de Unity, como se muestra:

Campo inspector de modo de transformación predeterminado del componente ARMarkerManager

Como alternativa al uso ARMarker.transformModede , pase el identificador de seguimiento de un ARMarker objeto a ARMarkerManager.SetTransformMode(TrackableId, TransformMode) para establecer su modo de transformación.

En el código siguiente se muestra cómo obtener el tamaño y el centro de un nuevo código QR, la posición y rotación de su transformación y la posición de transformación actualizada después de cambiar el modo de transformación.

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}");
    }
}

Escenario de ejemplo de marcador de AR

El ejemplo proporcionado con el paquete del complemento OpenXR contiene una escena habilitada para código QR que proporciona un ejemplo de cómo ARMarkerManager y ARMarker se puede usar.

La escena se encuentra en Assets > ARMarker como se muestra: ARMarker Scene Asset Location

Puede encontrar los scripts de C# usados en la escena en el repositorio De ejemplos de OpenXR Unity Mixed Reality en GitHub: /OpenXR-Unity-MixedReality-Samples/tree/main/SampleScenarios/Scenarios/MarkerSample/Scripts

Compartir a través de

Códigos QR en Unity

Configuración del proyecto y la aplicación de Unity

Obtención del complemento Mixed Reality OpenXR

Habilitación de las funcionalidades de WebCam

Concesión de permisos de acceso a la cámara de la aplicación

Creación de la detección de código QR en una escena

Creación de un objeto prefabricado para códigos QR

Agregar objetos visuales

Agregar `ARMarkerManager` a una escena

Realizar un seguimiento de los cambios de código QR

Obtención de la hora en que se detectó por última vez un código QR

Uso del identificador de seguimiento de un código QR

Seguimiento del estado de seguimiento de un código QR

Obtención de la versión de un código QR y el tipo de código QR

Lectura de datos QR

Obtención del tamaño, la posición, la rotación y el centro del código QR

Escenario de ejemplo de marcador de AR

Vea también

Comentarios

Recursos adicionales

Compartir a través de

Códigos QR en Unity

Configuración del proyecto y la aplicación de Unity

Obtención del complemento Mixed Reality OpenXR

Habilitación de las funcionalidades de WebCam

Concesión de permisos de acceso a la cámara de la aplicación

Creación de la detección de código QR en una escena

Creación de un objeto prefabricado para códigos QR

Agregar objetos visuales

Agregar ARMarkerManager a una escena

Realizar un seguimiento de los cambios de código QR

Obtención de la hora en que se detectó por última vez un código QR

Uso del identificador de seguimiento de un código QR

Seguimiento del estado de seguimiento de un código QR

Obtención de la versión de un código QR y el tipo de código QR

Lectura de datos QR

Obtención del tamaño, la posición, la rotación y el centro del código QR

Escenario de ejemplo de marcador de AR

Vea también

Comentarios

Recursos adicionales

Agregar `ARMarkerManager` a una escena