Visão geral do rastreamento de código QR

Artigo
05/24/2024

Para acessar o repositório do GitHub para o exemplo de código QR:

Com os fones de ouvido Windows Mixed Reality e HoloLens, seu aplicativo pode detectar códigos QR no ambiente ao redor do fone de ouvido, estabelecendo um sistema de coordenadas no local real de cada código. Você também pode renderizar hologramas no mesmo local em vários dispositivos para criar uma experiência compartilhada. Depois de ativar a webcam do seu dispositivo, você reconhecerá códigos QR nas versões mais recentes de seus projetos. Para obter melhores resultados em produção, recomendamos que você revise a seção de práticas recomendadas.

Neste artigo, os seguintes tópicos serão abordados:

Dispositivos suportados para rastreamento de código QR
Versões de código QR suportadas
Práticas recomendadas para detecção de código QR
Solução de problemas e perguntas frequentes

Suporte a dispositivos

Product	HoloLens 1ª Geração	HoloLens 2	Headsets imersivos
OpenXR		✔️ (com OpenXR Runtime versão 113 e extensão OpenXR XR_MSFT_scene_marker )
Realidade mista Unity Plugin		✔️ (com OpenXR Runtime versão 113 e Mixed Reality Unity Plugin `ARMarkerManager`)
SDK QR herdado	✔️	✔️	✔️

Observação

O seguinte é específico para as APIs de código QR herdadas. Recomendamos usar a implementação OpenXR para códigos QR.

Usando o SDK de código QR herdado, o rastreamento de código QR com fones de ouvido imersivos do Windows Mixed Reality em PCs desktop é suportado no Windows 10 Versão 2004 e superior. Use a Microsoft.MixedReality.QRCodeWatcher.IsSupported() API para determinar se o recurso tem suporte no dispositivo atual.

Versões de código QR suportadas

A tabela a seguir lista as versões de código QR suportadas e não suportadas:

	Versões do código QR
Com suporte:	QR Code versões 1 - 10 Micro QR Códigos M1-M4 Todas as codificações
Não compatível:	QR Codes 10 - 20 (não totalmente suportado) QR Codes versões 21+ Módulos ajustados, por exemplo: módulos circulares, reflexos, invertidos (preto/branco). Logos Anexos estruturados

Práticas recomendadas para detecção de código QR

Zonas tranquilas em torno de códigos QR

Para serem lidos corretamente, os códigos QR exigem uma margem em todos os lados do código. Essa margem não deve conter nenhum conteúdo impresso e deve ter quatro módulos (um único quadrado preto no código) de largura.

A documentação oficial do código QR contém mais informações sobre zonas de silêncio.

Iluminação e pano de fundo

A qualidade de detecção do código QR é suscetível a iluminação e pano de fundo variados.

Em condições normais de iluminação, forneça contraste suficiente para os módulos preto/branco para um melhor desempenho.
Em condições extremas de iluminação com iluminação brilhante ou fundo escuro, você pode tentar reduzir e ajustar o contraste, o que pode melhorar a taxa de detecção de código QR. O fundo branco dentro do código QR pode ser reduzido de 255 para baixo.

Tamanho dos códigos QR

Os dispositivos Windows Mixed Reality e HoloLens não funcionam com códigos QR com lados menores que 5 cm.

Para códigos QR com laterais que variam de 5 cm a 10 cm, o dispositivo deve estar bastante próximo para detectar o código. Pode levar mais tempo do que a média para detectar o código.

O tempo exato para detectar códigos depende não apenas do tamanho dos códigos QR, mas de quão longe você está do código. Aproximar-se do código ajudará a compensar problemas com o tamanho.

Distância e posição angular do código QR

As câmeras de rastreamento só podem detectar um certo nível de detalhe. Para códigos pequenos (menos de 10 cm ao longo das laterais), você deve estar bastante próximo. Para um código QR versão 1 que varia de 10 cm a 25 cm de tamanho, a distância mínima de detecção é entre 0,15 metros e 0,5 metros.

A distância de detecção para o tamanho aumenta linearmente, mas também depende da versão QR suportada ou do tamanho do módulo. Quanto maior a versão, menores os módulos, que só podem ser detectados a partir de uma posição mais próxima. Você também pode tentar micro-códigos QR se quiser que a distância de detecção seja maior. A detecção de QR funciona com uma faixa de ângulos += 45 graus para garantir que tenhamos resolução adequada para detectar o código.

Outras considerações de detecção:

Códigos QR em superfícies curvas não são suportados.
A orientação no plano é suportada. Fora do plano deve ser <= +-45 olhando diretamente para ter melhor detecção.
O tamanho físico do código QR deve ter módulos de pelo menos 2/3 pixels. Nota: Versões mais altas de códigos QR terão módulos menores.

Para a relação de compensação entre distância e tamanho do código QR para detecção ideal, consulte o gráfico a seguir:

Gráfico de distância do tamanho do código QR

Importante

Certifique-se sempre de que tem contraste suficiente e uma borda adequada.

Gerenciando dados de código QR

Os dispositivos Windows Mixed Reality e HoloLens detectam códigos QR no nível do sistema no driver. Quando o dispositivo é reinicializado ou o driver é reiniciado, o histórico de códigos QR detectados é limpo. Os códigos QR detectados são tratados como novos objetos.

Recomendamos configurar seu aplicativo para ignorar códigos QR mais antigos do que um carimbo de data/hora específico, que pode ser especificado no aplicativo. A API do QR Code especifica a hora em que a última detecção aconteceu. A maioria dos desenvolvedores de aplicativos usará o tempo do sistema quando o aplicativo for iniciado para determinar a hora em que um código QR é detectado.

Os dados do código QR não são específicos do aplicativo. Após o lançamento do aplicativo, haverá uma lista de códigos QR disponíveis sendo fornecidos. O desenvolvedor do aplicativo determinará quais códigos QR são relevantes para este aplicativo.

Colocação de código QR em um espaço

Para obter recomendações sobre onde e como colocar códigos QR, consulte Considerações sobre ambiente para HoloLens.

Solução de problemas e perguntas frequentes

Que capacidades são necessárias?

Para ativar o rastreamento de código QR em seu aplicativo HoloLens, adicione o recurso de webcam ao manifesto do aplicativo. Se você estiver desenvolvendo em Unity, você pode configurar isso a partir das configurações do jogador.

Além disso, os usuários podem ser solicitados pela caixa de diálogo de permissões para conceder permissões de webcam do aplicativo. Isso só acontece uma vez ao longo da vida útil de um aplicativo. Em casos como o aplicativo solicitando explicitamente o acesso à webcam, a caixa de diálogo não reaparecerá.

Para aplicativos Unity com o recurso WebCam, ativar ARMarkerManager em uma cena pode acionar a caixa de diálogo de permissão da webcam para aparecer.

Para aplicativos OpenXR C++ nativos, as chamadas iniciais para xrComputeNewSceneMSFT com XrNewSceneComputeInfoMSFT::requestedFeatures contendo XR_SCENE_COMPUTE_FEATURE_MARKER_MSFT podem acionar a caixa de diálogo de permissões.

Observação

O seguinte é específico para as APIs de código QR herdadas. Recomendamos usar a implementação OpenXR para códigos QR.

Você precisará do recurso de webcam adicionado ao seu manifesto (caixa de seleção em Recursos Unity). Se você estiver criando como um projeto UWP padrão, ele também estará no package.appxmanifest no projeto de solução.

No SDK de código QR herdado, solicite acesso chamando o seguinte método:

#if WINDOWS_UWP

async QRCodeWatcher.RequestAccessAsync();

#endif

O status de acesso deve ser (status == QRCodeWatcherAccessStatus::Allowed).

Se o acesso for negado, o recurso retornará o acesso negado quando você iniciar o QRTracking.

Essa API deve ser chamada antes de você construir o QRCodeWatcher objeto.

Se você estiver executando o projeto a partir do Unity, também precisará garantir que está chamando a partir do thread da interface do usuário. Caso contrário, a API sempre retornará negada. Para obter mais informações, consulte Classe AppCallbacks no Manual Unity.

Para obter mais informações sobre como configurar seu projeto para o Unity, consulte Configurar o Unity para Windows Mixed Reality.

Como faço para que o recurso de rastreamento de código QR funcione em dispositivos HoloLens 2?

O rastreamento QR é automático no HoloLens 2, e você precisará do recurso de "webcam" adicionado ao seu aplicativo.

Onde encontro os arquivos de plug-in da API?

Os aplicativos devem usar o OpenXR Runtime do HoloLen para detectar QR Codes. O OpenXR para Windows Mixed Reality (113.2403.5001 ou superior) fornece suporte a código QR em dispositivos HoloLens.

Para aplicativos Unity, o suporte ao código QR é fornecido através do componente fornecido com o ARMarkerManager Mixed Reality OpenXR Plugin.

Para suporte a código QR em aplicativos que não sejam Unity, use a extensão OpenXR XR_MSFT_scene_marker .

Observação

O seguinte é específico para as APIs de código QR herdadas. Recomendamos usar a implementação OpenXR para códigos QR.

Todos os arquivos e documentação necessários podem ser encontrados aqui no NuGet aqui:

Microsoft.MixedReality.QR

Como preparar um aplicativo Unity para usar o ARMarkerManager para detectar códigos QR?

Em aplicativos Unity, o componente é usado para lidar com como a ARMarkerManager detecção de código QR em um ambiente físico é representada em uma cena. ARMarkerManager Fornece:

Eventos para notificar os assinantes quando um código QR detectado foi adicionado ao gerente, atualizado ou removido.
Uma coleção de ARMarker rastreáveis para códigos QR sob detecção.
Métodos que retornam dados para códigos QR conforme especificado pelo ID rastreável.

Para usar ARMarkerManager em seu aplicativo, você precisa importar o pacote Mixed Reality OpenXR Plugin .

Para importar o pacote:

Baixe e execute a Ferramenta de Recursos de Realidade Mista.
Instale o plugin OpenXR.

Consulte Bem-vindo à Ferramenta de Recursos de Realidade Mista para obter instruções detalhadas sobre como usar a ferramenta.

O procedimento geral seguinte é:

No seu projeto Unity, ative os recursos da WebCam .
Crie um pré-fabricado e anexe o ARMarker componente conforme mostrado:
Abra uma cena que você deseja que os códigos QR sejam detectados durante a execução.
Anexe ARMarkerManager a um GameObject em sua cena e defina Marker Prefab para o pré-fabricado que você criou.

Para obter instruções e informações mais detalhadas, acesse Códigos QR no Unity.

Para obter um exemplo de como usar códigos QR em seu aplicativo Unity, consulte o cenário de exemplo de código QR no GitHub.

Como preparar um aplicativo que não seja Unity para usar o OpenXR para detectar códigos QR?

A detecção de código QR no OpenXR é fornecida através da extensão XR_MSFT_scene_marker. Esta extensão permite que vários códigos QR sejam rastreados e pode fornecer tamanho, posição, carimbo de data/hora da última detecção, UUID e dados de código QR armazenados em buffer para códigos QR detectados.

Para habilitar o suporte ao código QR, as extensões XR_MSFT_scene_marker e XR_MSFT_scene_understanding devem estar habilitadas.

Para obter um passo a passo detalhado, consulte a visão geral da extensão XR_MSFT_scene_marker na especificação OpenXR 1.0.

Para obter um exemplo de como usar códigos QR, consulte Scene_QRCode.cpp no exemplo SceneUnderstandingUwp no GitHub.

Como preparar uma UWP para usar Microsoft.MixedReality.QR.QRCodeWatcher?

Observação

O seguinte é específico para as APIs de código QR herdadas. Recomendamos usar a implementação OpenXR para códigos QR.

Use o pacote NuGet para descompactar os arquivos necessários.
Adicione uma referência ao Microsoft.MixedReality.QR.winmd em seu projeto e comece a usar a API.
Adicione as versões de arquitetura corretas dos plugins e use-as de acordo na compilação.

Como preparar o Unity com o Microsoft.MixedReality.QR.QRCodeWatcher?

Observação

O seguinte é específico para as APIs de código QR herdadas. Recomendamos usar a implementação OpenXR para códigos QR.

Use o NuGet para Unity e aponte para o pacote NuGet acima.

Como posso fazer códigos QR?

Confira qualquer gerador de código QR.

Se o rastreamento de código QR não funcionar em geral, o que eu faço?

A versão do QR Code é suportada? Não suportamos as versões de alta densidade, como a versão 40. Nada acima da versão 10 é garantido; versões acima de 20 não são suportadas.
Você está perto o suficiente do código QR? Veja distância e posição angular do código QR.
Como é a iluminação? Há um problema conhecido em que a detecção se torna difícil quando o código QR está em um fundo ambiente escuro - o código QR aparecerá apagado para a câmera devido ao alto contraste. Para obter mais informações, consulte iluminação e pano de fundo.

Qual é a precisão?

Quando detectado em um único quadro, espera-se que o tamanho tenha no máximo um erro de 1% em relação ao tamanho real. Por exemplo, um código de 10 cm pode estar com até +/- 1 mm de distância no tamanho medido. Sob detecção contínua, a posição de um código pode flutuar em até +/- 2,5 mm. Depois de sair do intervalo de detecção, a posição de uma detecção anterior fica à mercê do erro do mapa.

Quão perto preciso estar do código QR para detectá-lo?

A distância, obviamente, depende do tamanho do código QR, e também de qual versão ele é. Para obter mais informações, consulte distância e posição angular do código QR.

No HoloLens 2, para um código QR versão 1 que varia de 5 cm de lados a 25 cm de lado, a distância mínima de detecção varia de 0,25 metros a 0,5 metro. O mais distante que eles podem ser detectados vai de cerca de 0,5 m para o código menor a dois metros para o maior.
No Windows Mixed Reality, essas distâncias para os tamanhos são reduzidas pela metade.
Para qualquer código maior, extrapole - a distância de detecção para o tamanho aumenta linearmente. Para qualquer código menor, a detecção simplesmente não ocorrerá - 4-5 cm é o menor que podemos detectar.

Por que não consigo ler códigos QR com logotipos?

Códigos QR com logotipos não são suportados.

Os códigos QR são detectados, então por que estou não recebendo dados?

Se a plataforma não conseguir decodificar o código QR, não haverá dados. Você pode usar o fluxo e interpretar os dados usando código aberto.
Alguns recursos, como acréscimo de estrutura, não são suportados.

Para obter mais informações, consulte quais versões de código QR são suportadas?.

Os códigos QR são salvos no nível de "espaço" ou no nível do aplicativo?

Os códigos QR são salvos no nível do sistema na sessão de driver ou sessão de inicialização no HoloLens. Para obter mais informações, consulte Gerenciando dados de código QR.

Como isso funciona com a plataforma subjacente? Onde persistem?

Os códigos QR detectados são mantidos na memória pelo motorista.

Como depuro o aplicativo no Visual Studio quando recebo a mensagem de erro "`Microsoft.MixedReality.QR.pdb` não encontrado"?

Observação

O seguinte é específico para as APIs de código QR herdadas. Recomendamos usar a implementação OpenXR para códigos QR.

O carregamento de símbolos para Microsoft.MixedReality.QR.dll foi ignorado porque não está especificado na lista de módulos incluídos.

Reprodução

Observação

O seguinte é específico para as APIs de código QR herdadas. Recomendamos usar a implementação OpenXR para códigos QR.

Siga as etapas para reproduzir esse comportamento:

Instale Microsoft.MixedReality.QR (NuGet) e MRTK
Tente depurar

Você deve ser capaz de depurar o aplicativo com Microsoft.MixedReality.QR.dll, mas a DLL não foi encontrada:

Mensagem de erro Microsoft.MixedReality.QR.pdb não encontrada

Solução recomendada

Observação

O seguinte é específico para as APIs de código QR herdadas. Recomendamos usar a implementação OpenXR para códigos QR.

Estamos trabalhando para adicionar símbolos à próxima versão. Enquanto isso, você ainda deve ser capaz de depurar seu aplicativo excluindo a DLL nas opções do Visual Studio:

excluindo a DLL nas opções do Visual Studio

Para obter mais informações, consulte Definindo as configurações do Visual Studio.

Existe um limite de quantos códigos QR podem ser digitalizados em uma sessão?

Há um limite de 100 códigos QR salvos no nível do sistema no driver, dentro de 10 minutos.

O processo de suavização do código QR mudou?

O processo de suavização do código QR mudou após 20H2, de suavização de pose para suavização de tamanho. Para reverter o comportamento para o processo de suavização anterior, aplicar-se-ia um algoritmo de suavização se os novos dados de pose do código QR forem detectados dentro de 5 segundos ou 10 cm do quadro detectado anteriormente. Os dados de transformação são combinados por meio de uma proporção ponderada de 90% do quadro atual com 10% do quadro anterior.

Compartilhar via

Visão geral do rastreamento de código QR

Suporte a dispositivos

Versões de código QR suportadas