Visão geral do rastreamento de código QR

Artigo
11/23/2024

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

Com headsets Windows Mixed Reality e HoloLens, seu aplicativo pode detectar códigos QR no ambiente ao redor do headset, 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á os códigos QR nas versões mais recentes de seus projetos. Para obter melhores resultados ao entrar em produção, recomendamos que você examine a seção de práticas recomendadas.

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

Dispositivos compatíveis com 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 )
Plug-in do Unity de Realidade Misturada		✔️ (com OpenXR Runtime versão 113 e Plug-in do Unity de Realidade Misturada `ARMarkerManager`)
SDK QR legado	✔️	✔️	✔️

Observação

O seguinte é específico para as APIs de código QR herdadas. Em vez disso, recomendamos usar a implementação do OpenXR para códigos QR.

Usando o SDK de código QR herdado, o rastreamento de código QR com headsets imersivos Windows Mixed Reality em computadores desktop tem suporte no Windows 10 versão 2004 e superior. Use a Microsoft.MixedReality.QRCodeWatcher.IsSupported() API para determinar se o recurso é compatível com o dispositivo atual.

Versões de código QR suportadas

A tabela a seguir lista as versões de código QR com e sem suporte:

	Versões do código QR
Com suporte:	QR Code versões 1 - 10 Micro Códigos QR M1-M4 Todas as codificações
Não compatível:	Códigos QR 10 - 20 (não totalmente suportados) Códigos QR 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 silenciosas em torno de códigos QR

Para serem lidos corretamente, os códigos QR requerem uma margem em todos os lados do código. Esta margem não deve conter qualquer 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 silenciosas.

Iluminação e pano de fundo

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

Em condições normais de iluminação, forneça contraste suficiente para os módulos preto/branco para melhor desempenho.
Em condições extremas de iluminação com iluminação forte ou pano de fundo escuro, você pode tentar reduzir e ajustar o contraste, o que pode melhorar a taxa de detecção do 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 lados que variam de 5 cm a 10 cm, o dispositivo deve estar bem 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 também da distância que você está do código. Aproximar-se do código ajudará a compensar problemas de 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 nas laterais), você deve estar bem próximo. Para um código QR versão 1 variando 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 do tamanho aumenta linearmente, mas também depende da versão do QR suportada ou do tamanho do módulo. Quanto maior a versão, menores os módulos, que só podem ser detectados de uma posição mais próxima. Você também pode tentar códigos micro-QR se quiser que a distância de detecção seja maior. A detecção de QR funciona com uma variedade de ângulos += 45 graus para garantir que tenhamos a resolução adequada para detectar o código.

Outras considerações de detecção:

Os 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 uma melhor detecção.
O tamanho físico do código QR deve ter módulos de pelo menos 2/3 pixels. Observação: versões superiores de códigos QR terão módulos menores.

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

Tabela de distância do tamanho do código QR

Importante

Certifique-se sempre de ter 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 é apagado. Os códigos QR redetectados 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 QR Code especifica a hora em que ocorreu a última detecção. A maioria dos desenvolvedores de aplicativos usará a hora do sistema quando o aplicativo é 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 a inicialização 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.

Posicionamento do código QR em um espaço

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

Solução de problemas e perguntas frequentes

Quais recursos são necessários?

Para habilitar o rastreamento de código QR em seu aplicativo HoloLens, adicione o recurso de webcam ao manifesto do aplicativo. Se você estiver desenvolvendo no Unity, poderá configurar isso nas configurações do player.

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

Para aplicativos Unity com o recurso WebCam, habilitar ARMarkerManager em uma cena pode disparar 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 containing XR_SCENE_COMPUTE_FEATURE_MARKER_MSFT podem disparar a caixa de diálogo de permissões.

Observação

O seguinte é específico para as APIs de código QR herdadas. Em vez disso, recomendamos usar a implementação do OpenXR para códigos QR.

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

No SDK do 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 do Unity, também precisará garantir que está chamando do thread da interface do usuário. Caso contrário, a API sempre retornará negado. Para obter mais informações, consulte a classe AppCallbacks no Manual do 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 de 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 códigos QR. O OpenXR para Windows Mixed Reality (113.2403.5001 ou superior) fornece suporte a código QR em dispositivos HoloLens.

Para aplicativos do Unity, o suporte ao código QR é fornecido por meio do componente fornecido com o ARMarkerManager Plug-in OpenXR de Realidade Misturada.

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

Observação

O seguinte é específico para as APIs de código QR herdadas. Em vez disso, recomendamos usar a implementação do OpenXR para códigos QR.

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

Microsoft.MixedReality.QR

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

Em aplicativos Unity, o componente é usado para lidar com a forma 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 for adicionado ao gerenciador, 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 pela ID rastreável.

Para usar ARMarkerManager em seu aplicativo, você precisa importar o pacote de plug-in OpenXR de realidade misturada.

Para importar o pacote:

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

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

O procedimento geral a seguir é:

Em seu projeto do Unity, habilite 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 como o prefab 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 do Unity para usar o OpenXR para detectar códigos QR?

A detecção de código QR no OpenXR é fornecida por meio da extensão XR_MSFT_scene_marker . Essa 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 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. Em vez disso, recomendamos usar a implementação do 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 plug-ins e use-as adequadamente na compilação.

Como faço para preparar o Unity com o Microsoft.MixedReality.QR.QRCodeWatcher?

Observação

O seguinte é específico para as APIs de código QR herdadas. Em vez disso, recomendamos usar a implementação do 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 é uma versão compatível? Não oferecemos suporte às versões de alta densidade como a versão 40. Nada acima da versão 10 é garantido; Não há suporte para versões acima de 20.
Você está perto o suficiente do código QR? Veja a distância e a 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 ambiental escuro - o código QR aparecerá desbotado 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 1% de erro em relação ao tamanho real. Por exemplo, um código de 10 cm pode estar com até +/- 1 mm de diferença no tamanho medido. Sob detecção contínua, a posição de um código pode variar em até +/- 2,5 mm. Depois de sair do alcance de detecção, a posição de uma detecção anterior fica à mercê do erro de 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 da versão. 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 variando de 5 cm a 25 cm de lados, a distância mínima de detecção varia de 0,25 metros a 0,5 metros. O mais longe que eles podem ser detectados vai de cerca de 0,5 m para o menor código 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 não estou 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-fonte aberto.
Não há suporte para alguns recursos, como acréscimo de estrutura.

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 do 'espaço' ou no nível do aplicativo?

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

Como isso funciona com a plataforma subjacente? Onde eles persistem?

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

Como faço para depurar 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. Em vez disso, recomendamos usar a implementação do 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.

Reproduzir

Observação

O seguinte é específico para as APIs de código QR herdadas. Em vez disso, recomendamos usar a implementação do OpenXR para códigos QR.

Siga as etapas para reproduzir esse comportamento:

Instalar 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 encontrado

Solução recomendada

Observação

O seguinte é específico para as APIs de código QR herdadas. Em vez disso, recomendamos usar a implementação do 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, em 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, seria aplicado um algoritmo de suavização se os novos dados de pose de 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 taxa 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