Códigos QR no Unity

Os headsets do HoloLens 2 podem rastrear e detectar códigos QR que podem ser usados para fornecer hologramas e outros recursos de AR. Este artigo orienta você por tudo o que você precisa saber para começar a usar códigos QR em seu aplicativo Unity, incluindo:

• Adicionando detecção de código QR ao seu aplicativo Unity.
• Entender conceitos importantes e componentes do Unity que você precisa usar.
• Fornece tutoriais que abordam o uso comum do código QR.
• Apresenta o cenário de exemplo do Marcador de AR que demonstra uma cena habilitada para código QR e scripts de exemplo.

Antes de continuar com este artigo, recomendamos passar pela visão geral dos códigos QR.

Configurando seu projeto e aplicativo do Unity

Seu projeto e aplicativo do Unity devem ser configurados e configurados corretamente para habilitar a funcionalidade de código QR, o que exige:

• OpenXR para Windows Mixed Reality versão 113.2403.5001 ou posterior.

  Observação

  Isso vem com o sistema operacional e pode ser atualizado por meio da Windows Store. Esteja ciente de que os usuários podem ter versões anteriores instaladas e seus dispositivos não poderão trabalhar com marcadores AR, como códigos QR, até atualizar para a versão 113.2403.5001 ou posterior.

• Um projeto compatível com uma versão compatível do Unity:
  • Unity 2022.3 LTS (recomendado)
  • Unidade 2021.3 LTS
• O plug-in OpenXR de realidade misturada.
• Recursos de webcam habilitados para seu projeto do Unity.
• Permissões de câmera concedidas ao seu aplicativo.

As seções a seguir orientam você sobre como configurar seu projeto e aplicativo do Unity para habilitar a detecção de código QR.

Obtendo o plug-in OpenXR de realidade misturada

O pacote de plug-in OpenXR de realidade misturada contém APIs C# que você pode usar para acessar a funcionalidade de código QR.

Para importar o pacote:

1. Baixe e execute a Ferramenta de Recursos de Realidade Misturada.
2. Instale o plug-in OpenXR.

A Ferramenta de Recursos de Realidade Misturada também simplifica o gerenciamento de pacotes e pode ser usada para localizar, atualizar e adicionar os recursos de Realidade Misturada que seu aplicativo exige. Consulte Bem-vindo à Ferramenta de Recursos de Realidade Misturada para obter instruções detalhadas sobre como usar a ferramenta.

Ativando recursos de WebCam

Para detectar e rastrear códigos QR, seu projeto do Unity precisa ter os recursos da WebCam habilitados.

Para ativar os recursos da WebCam :

1. Abra seu projeto do Unity.
2. Clique em Editar no menu do aplicativo do editor do Unity.
3. Vá para o Player de Configurações > do Projeto e selecione a guia UWP, conforme mostrado:
4. Ative a WebCam na lista Recursos.
5. Saia das configurações do projeto.

Os recursos da WebCam agora estão habilitados para seu aplicativo Unity. No entanto, seu aplicativo ainda deve receber permissões para acessar a câmera do dispositivo.

Conceder permissões de acesso à câmera do aplicativo

Se o seu aplicativo tiver os recursos de WebCam ativados, a caixa de diálogo de permissões solicitará que os usuários concedam ao seu aplicativo acesso à câmera do dispositivo.

Essa caixa de diálogo é mostrada aos usuários apenas uma vez, normalmente ao entrar em uma cena contendo um ARMarkerManager com suporte a marcador de código QR ativado. Se o acesso à câmera for negado, os usuários podem acessar Aplicativos de configurações > e ativá-lo por meio das opções avançadas do aplicativo.

Criando detecção de código QR em uma cena

A detecção de código QR deve ser incorporada em todas as cenas em que você deseja usar códigos QR, o que exige:

• A GameObject com ARMarkerManager anexado. ARMarkerManager é o único responsável por criar, atualizar e remover todos os GameObject códigos QR detectados.
• Um pré-fabricado com ARMarker anexado.
• ARMarkerManager configurado para usar o pré-fabricado ao criar um GameObject quando um código QR é detectado.

Criando um pré-fabricado para códigos QR

Para usar códigos QR em sua cena, você precisa criar um pré-fabricado para códigos QR. ARMarkerManager usa esse pré-fabricado para criar um GameObject a partir de sempre que um código QR é detectado.

Para fazer um pré-fabricado para códigos QR:

1. Crie um novo pré-fabricado para o seu projeto.
2. Adicione o ARMarkercomponente ao pré-fabricado, localizado em Script > Microsoft.MixedReality.OpenXR > ARMarker.
   

Agora você tem um pré-fabricado básico para trabalhar. Você provavelmente deseja que seu aplicativo represente visualmente os códigos QR detectados no ambiente. A próxima seção explica como adicionar uma representação visual para códigos QR.

Adicionando recursos visuais

Na seção anterior, ARMarkeradicionar ao pré-fabricado também adicionou automaticamente o ARMarkerScale componente. Este componente é usado para combinar a escala da representação visual de um código QR com sua contraparte física.

Para fazer isso:

1. Adicione um vazio GameObject ao pré-fabricado que você criou na seção anterior. Ele representará todo o conteúdo do marcador visual.
2. Adicione um filho 3D GameObject, como um Quad, ao conteúdo GameObjectdo marcador .
3. No componente do ARMarkerScale pré-fabricado, defina Transformação de escala de marcador para o conteúdo GameObjectdo marcador. Definir esse campo garante que o 3D GameObject escolhido seja dimensionado corretamente para corresponder aos códigos QR do mundo real.

Adicionando ARMarkerManager a uma cena

ARMarkerManager é o único responsável por criar, atualizar e remover todos os GameObject códigos QR detectados.

Para adicionar ARMarkerManager à sua cena:

1. Coloque um GameObject em sua cena.
2. Adicione o ARMarkerManager componente ao GameObject, localizado em Script > Microsoft.MixedReality.OpenXR > ARMarkerManager.
   
3. Defina o ARMarkerManager campo Marcador Prefab como o prefab que você criou na seção anterior.
4. Expanda Tipos de marcador ativados, escolha um elemento e defina-o como QR Code.

Acompanhando as alterações do código QR

ARMarkerManager contém o markersChanged evento, que fornece ARMarkersChangedEventArgs aos assinantes. Use esses argumentos de evento para rastrear quais códigos QR são adicionados ou removidos da detecção ou dados de pose atualizados.

O código a seguir demonstra a assinatura do ARMarkerManager.markersChanged evento, usando seus argumentos de evento para iterar pelos ARMarker objetos ARMarkerManager que estão manipulando e gravando em Depurar se eles são adicionados, removidos ou atualizados.

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

Obtendo a hora em que um código QR foi detectado pela última vez

Use a ARMarker.lastSeenTime propriedade para determinar quando o dispositivo rastreou pela última vez um código QR detectado e a quantidade de tempo, se houver, que o rastreamento foi perdido. O tempo é medido no número de segundos desde que o Unity iniciou seu aplicativo e é análogo ao UnityEngine.Time.realtimeSinceStartup.

Usando o ID rastreável de um código QR

Os códigos QR são rastreáveis, que são qualquer coisa que um dispositivo AR possa detectar e rastrear em um ambiente físico. Os rastreáveis derivam do tipo ARTrackable<TSessionRelativeData, TTrackable> que fornece uma ID, estado de rastreamento, pose e outros dados.

O ID rastreável de um código QR pode ser passado para ARMarkerManager métodos para obter as propriedades do código QR, dados brutos de bytes e representação de cadeia de caracteres e para definir o modo de transformação do código QR. Esses métodos permitem que você recupere dados para um código QR sem precisar se apegar a uma referência de ARMarker objeto.

Você pode passar o ID de um código QR para os seguintes ARMarkerManager métodos:

• GetDecodedString(UnityEngine.XR.ARSubsystems.TrackableId trackableId)
• GetMarker(UnityEngine.XR.ARSubsystems.TrackableId trackableId)
• GetQRCodeProperties(UnityEngine.XR.ARSubsystems.TrackableId)
• GetRawData(UnityEngine.XR.ARSubsystems.TrackableId, Unity.Collections.Allocator)
• SetTransformMode(UnityEngine.XR.ARSubsystems.TrackableId, Microsoft.MixedReality.OpenXR.TransformMode)

Observação

Para o parâmetro allocatorde método , a aprovação Unity.Collections.Allocator.Temp é suficiente para a maioria dos GetRawData cenários.

Seguindo o estado de rastreamento de um código QR

Como an ARMarker é rastreável, ele herda a trackingState propriedade e é definido como um dos três UnityEngine.XR.ARSubsystems.TrackingState:

• Limited: Indica que o código QR está sendo rastreado, mas informações limitadas estão disponíveis ou são de baixa qualidade.
• Tracking: Especifica que o código QR está sendo totalmente rastreado.
• None: Indica que o código QR não está sendo rastreado.

Para monitorar o estado de rastreamento de um código QR, assine o ARMarkerManager.markersChanged e itere por meio das ARMarker coleções de marcadores fornecidas nos argumentos de evento passados para o manipulador de eventos.

O código a seguir demonstra o uso do evento para iterar por meio ARMarker de ARMarkerManager.markersChanged objetos para códigos QR recém-detectados e gravar sua ID rastreável na janela 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.");
    }
}

Obtendo a versão de um código QR e o tipo de código QR

Para obter a versão e o tipo de um código QR detectado:

1. Chame ARMarker.GetQRCodeProperties(), que retorna uma QRCodeProperties instância.
2. Acesse o campo QRCodeProperties no valor de retorno para obter o tipo do código QR. O valor é QRCodeType.QRCode ou QRCodeType.MicroQRCode.
3. Acesse o campo do valor de QRCodeProperties.version retorno para obter a versão do código QR. O valor varia de 1 a 40 se o tipo for QRCodeType.QRCode, e de 1 a 4 se o tipo for QRCodeType.MicroQRCode.

Como alternativa, passe o ID rastreável de um ARMarker objeto para ARMarkerManager.GetQRCodeProperties(TrackableId) obter o tipo e a versão de um código QR.

Aviso

Os códigos QR são o único tipo de marcador atualmente suportado, embora o suporte para outros tipos de marcador possa ser adicionado em versões futuras. Se markerType não ARMarkerType.QRCodefor , chamar GetQRCodeProperties(TrackableId) lança System.InvalidOperationException. Considere encapsular chamadas em GetQRCodeProperties(TrackableId) blocos try-catch se isso puder causar problemas em seu aplicativo posteriormente.

Leitura de dados QR

O ARMarker componente é anexado a cada GameObject um que ARMarkerManager cria. ARMarker fornece dois métodos que retornam dados de código QR:

• GetDecodedString(): Este método obtém a representação da string do código QR, como um URL.

• GetRawData(Unity.Collections.Allocator allocator): Este método retorna o conteúdo do código QR como uma matriz de bytes, permitindo um ajuste refinado de como a matriz é alocada. Use esse método em caminhos ativos e outras situações em que o desempenho é crítico.

O código a seguir demonstra o uso básico de GetDecodedString() e 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();
    }
}

Obtenção do tamanho, posição, rotação e centro do código QR

Um ARMarker objeto fornece o tamanho, a posição, a rotação e o centro do código QR que ele representa.

Para obter o tamanho do código QR em metros, use a propriedade ARMarker.size.

Use a ARMarker.transform propriedade para obter a rotação e a posição do espaço mundial da transformação do código QR e ARMarker.center as coordenadas 2D do código QR em relação à transformação do código QR. A transformação em si é centralizada de acordo com se ARMarker.transformMode (o modo de transformação) está definido como TransformMode.MostStable (mais estável, o canto superior esquerdo do código QR) ou TransformMode.Center (centro, o centro geométrico do código QR).

Use o ARMarkerManager.defaultTransformMode campo para definir o modo de transformação com o qual ARMarkerManager cria novos ARMarker objetos. O campo é inicializado com o Default Transform Mode campo definido como no Unity Inspector, conforme mostrado:

Como alternativa ao uso ARMarker.transformModedo , passe a ID rastreável de um ARMarker objeto para ARMarkerManager.SetTransformMode(TrackableId, TransformMode) para definir seu modo de transformação.

O código a seguir demonstra a obtenção do tamanho e do centro de um novo código QR, a posição e a rotação de sua transformação e a posição de transformação atualizada após alterar o modo de transformação.

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

Cenário de amostra de marcador AR

O exemplo fornecido com o pacote OpenXR Plugin contém uma cena habilitada para código QR que fornece um exemplo de como ARMarkerManager e ARMarker pode ser usado.

A cena está localizada no ARMarker de ativos>, conforme mostrado:

Você pode encontrar os scripts C# usados na cena no repositório de Exemplos de Realidade Misturada do OpenXR Unity no GitHub: /OpenXR-Unity-MixedReality-Samples/tree/main/SampleScenarios/Scenarios/MarkerSample/Scripts

Confira também

• Referência da API do plug-in OpenXR de realidade misturada
• Visão geral dos códigos QR