Partilhar via

Códigos QR em Unity

  • Artigo

Os fones de ouvido HoloLens 2 podem rastrear e detetar códigos QR que podem ser usados para fornecer hologramas e outros recursos de RA. Este artigo orienta você através de tudo o que você precisa saber para começar a usar códigos QR em seu aplicativo Unity, incluindo:

  • Adicionar deteção de código QR ao seu aplicativo Unity.
  • Compreender conceitos importantes e componentes Unity que você precisa usar.
  • Fornece tutoriais que abrangem o uso comum de código QR.
  • Apresenta o cenário de exemplo do marcador de RA 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.

Código QR rastreado

Configurando seu projeto e aplicativo Unity

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

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

    Nota

    Isso vem com o sistema operacional e pode ser atualizado através da Windows Store. Por favor, esteja ciente de que os usuários podem ter versões anteriores instaladas, e seus dispositivos não poderão trabalhar com marcadores de RA, como códigos QR, até a atualização para a versão 113.2403.5001 ou posterior.

  • Um projeto compatível com uma versão suportada do Unity:
    • Unity 2022.3 LTS (Recomendado)
    • Unidade 2021.3 LTS
  • O Plugin OpenXR de Realidade Mista.
  • Recursos de webcam habilitados para seu projeto Unity.
  • Permissões de câmera concedidas ao seu aplicativo.

As seções a seguir guiam você por como configurar seu projeto e aplicativo Unity para habilitar a deteção de código QR.

Obtendo o plug-in OpenXR de realidade mista

O pacote Mixed Reality OpenXR Plugin contém APIs C# que você pode usar para acessar a funcionalidade de código QR.

Para importar o pacote:

  1. Transfira e execute a Ferramenta de Funcionalidade de Realidade Mista.
  2. Instale o plugin OpenXR.

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

Ativando os recursos da WebCam

Para detetar e rastrear códigos QR, seu projeto Unity precisa ter os recursos da WebCam ativados.

Para ativar as capacidades da WebCam :

  1. Abra seu projeto Unity.
  2. Clique em Editar no menu do aplicativo do editor Unity.
  3. Vá para Project Settings > Player e selecione a guia UWP conforme mostrado: Configurações da guia UWP
  4. Habilite a WebCam na lista Recursos. Recursos da WebCam ativados
  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âmara da aplicação

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

Caixa de diálogo Permissões da câmera

Esta caixa de diálogo é mostrada aos usuários apenas uma vez, normalmente ao entrar em uma cena contendo um ARMarkerManager com o suporte a marcadores de código QR ativado. Se o acesso à câmara for negado, os utilizadores podem aceder às Aplicações de Definições > e ativá-lo através das Opções Avançadas da aplicação.

Opções avançadas do aplicativo com permissões ativadas

Construindo a deteção de código QR em uma cena

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

Criação de 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 este pré-fabricado para criar um GameObject a partir de sempre que um código QR é detetado.

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.
    Adicionando o componente ARMarker

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

Adicionando elementos visuais

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

Para tal:

  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 3D GameObjectfilho , como um Quad, ao conteúdo GameObjectdo marcador . Adicionar 3D GameObject ao ARMarker pré-fabricado
  3. No componente pré-fabricado ARMarkerScale , defina Marker Scale Transform como o conteúdo GameObjectdo marcador. Definir este 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 detetados.

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.
    Adicionando o componente ARMarkerManager
  3. Defina o ARMarkerManager campo Marcador pré-fabricado como o pré-fabricado criado na seção anterior. Conjunto de campos pré-fabricados do marcador
  4. Expanda Tipos de marcadores habilitados, escolha um elemento e defina-o como QR Code. Tipo de marcador de código QR ativado

Acompanhar 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 deteçã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 através dos ARMarker objetos ARMarkerManager é manipular e gravar 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}");
    }
}

Obter a hora em que um código QR foi detetado pela última vez

Use a ARMarker.lastSeenTime propriedade para determinar quando o dispositivo rastreou pela última vez um código QR detetado e a quantidade de tempo, se houver, o rastreamento é perdido. O tempo é medido no número de segundos desde que 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 de RA pode detetar e rastrear em um ambiente físico. Os rastreáveis derivam do tipo ARTrackable<TSessionRelativeData, TTrackable> que fornece um ID, estado de rastreamento, pose e outros dados.

O ID rastreável para 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 para o código QR. Esses métodos permitem que você recupere dados para um código QR sem ter que segurar uma referência de ARMarker objeto.

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

Nota

Para o parâmetro allocatormethod , a passagem Unity.Collections.Allocator.Temp é suficiente para a GetRawData maioria dos cenários.

Seguindo o estado de rastreamento de um código QR

Como um 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á a ser rastreado, mas que a informação está disponível ou é de má 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 e ARMarkerManager.markersChanged itere através das ARMarker coleções de marcadores fornecidas nos argumentos de evento passados para seu manipulador de eventos.

O código a seguir demonstra o uso do ARMarkerManager.markersChanged evento para iterar através de ARMarker objetos para códigos QR recém-detectados e gravar seu 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.");
    }
}

Obter 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 detetado:

  1. Call ARMarker.GetQRCodeProperties(), que retorna uma QRCodeProperties instância.
  2. Acesse o campo QRCodeProperties no valor de retorno para obter o tipo de código QR. O valor é ou QRCodeType.QRCode 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 marcadores possa ser adicionado em versões futuras. Se markerType não ARMarkerType.QRCodefor, a chamada GetQRCodeProperties(TrackableId) lança.System.InvalidOperationException Considere envolver chamadas em GetQRCodeProperties(TrackableId) blocos try-catch se isso puder causar problemas em seu aplicativo mais tarde.

Leitura de dados QR

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

  • GetDecodedString(): Este método obtém a representação de cadeia de caracteres do código QR, como uma 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 fino em como a matriz é alocada. Use esse método em hot paths 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, posição, rotação e centro do código QR que ele representa.

Para obter o tamanho do código QR em metros, use o imóvel 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 ARMarkerManager de transformação cria novos ARMarker objetos com. O campo é inicializado com o Default Transform Mode campo definido como no Unity Inspetor, conforme mostrado:

O campo Inspetor do modo de transformação padrão do componente ARMarkerManager

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

O código a seguir demonstra como obter o tamanho e o 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 depois de 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 exemplo de marcador de RA

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 em Assets > ARMarker como mostrado: Localização do ARMarker Scene Asset

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

Consulte também