Visão geral do rastreamento de código QR

Artigo
05/24/2024

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

Com os auriculares Windows Mixed Reality e HoloLens, a sua aplicação pode detetar códigos QR no ambiente à volta do auricular, estabelecendo um sistema de coordenadas na localização 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 os melhores resultados em produção, recomendamos que você revise a seção de práticas recomendadas .

Neste artigo, ficará a saber mais sobre:

Dispositivos suportados para rastreamento de código QR
Versões de código QR suportadas
Práticas recomendadas para deteção de código QR
Resolução de problemas e FAQ

Suporte de dispositivos

Produto	HoloLens 1ª Geração	HoloLens 2	Auriculares imersivos
OpenXR		✔️ (com OpenXR Runtime versão 113 e OpenXR XR_MSFT_scene_marker extensão)
Plugin Unity de Realidade Mista		✔️ (com OpenXR Runtime versão 113 e Mixed Reality Unity Plugin `ARMarkerManager`)
SDK QR legado	✔️	✔️	✔️

Nota

O seguinte é específico para as APIs de código QR herdadas. Em vez disso, 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 é suportado 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 de código QR
Suportado:	QR Code versões 1 - 10 Micro Códigos QR M1-M4 Todas as codificações
Não suportado:	Códigos QR 10 - 20 (não totalmente suportados) QR Codes versões 21+ Módulos ajustados, por exemplo: módulos circulares, reflexos, invertidos (preto/branco). Logótipos Apêndices estruturados

Práticas recomendadas para deteçã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 torno de 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 tranquilas.

Iluminação e pano de fundo

A qualidade de deteçã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 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 deteçã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 lados que variam de 5 cm a 10 cm, o dispositivo deve estar bastante próximo para detetar o código. Pode levar mais tempo do que a média para detetar o código.

O tempo exato para detetar códigos depende não só do tamanho dos códigos QR, mas 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 a partir do código QR

As câmeras de rastreamento só podem detetar 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 uma versão 1 código QR variando de 10 cm a 25 cm de tamanho, a distância mínima de deteção é entre 0,15 metros e 0,5 metros.

A distância de deteçã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 detetados de uma posição mais próxima. Você também pode tentar códigos micro-QR se quiser que a distância de deteção seja maior. A deteção de QR funciona com uma gama de ângulos += 45 graus para garantir que temos uma resolução adequada para detetar o código.

Outras considerações de deteçã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 direto para ter melhor deteção.
O tamanho físico do código QR deve ter módulos de pelo menos 2/3 pixels. Nota: As versões superiores dos códigos QR terão módulos mais pequenos.

Para a relação de compensação entre distância e tamanho do código QR para deteçã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.

Gerir dados de código QR

Os dispositivos Windows Mixed Reality e HoloLens detetam códigos QR no nível do sistema no driver. Quando o dispositivo é reiniciado ou o driver é reiniciado, o histórico de códigos QR detetados é limpo. 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 aconteceu a última deteção. A maioria dos desenvolvedores de aplicativos usará o tempo do sistema quando o aplicativo é iniciado para determinar a hora em que um código QR é detetado.

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 do código QR num espaço

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

Resolução de Problemas e FAQ

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 a conceder permissões à webcam do aplicativo. Isso só acontece uma vez ao longo da 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, ativar em uma cena pode acionar ARMarkerManager 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 contenção XR_SCENE_COMPUTE_FEATURE_MARKER_MSFT podem acionar a caixa de diálogo de permissões.

Nota

O seguinte é específico para as APIs de código QR herdadas. Em vez disso, 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 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 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 "webcam" adicionado ao seu aplicativo.

Onde posso encontrar os arquivos de plug-in da API?

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

Para aplicativos Unity, o suporte a código QR é fornecido através do componente fornecido com o plug-in OpenXR de realidade mistaARMarkerManager.

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

Nota

O seguinte é específico para as APIs de código QR herdadas. Em vez disso, 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 preparo um aplicativo Unity para usar ARMarkerManager para detetar códigos QR?

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

Eventos para notificar os subscritores quando um código QR detetado foi adicionado ao gestor, atualizado ou removido.
Uma coleção de ARMarker rastreáveis para códigos QR sob deteçã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 de plug-in OpenXR de realidade mista.

Para importar o pacote:

Transfira e execute a Ferramenta de Funcionalidade 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 é o seguinte:

Em seu projeto 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 detetados durante a execução.
Anexe ARMarkerManager a um GameObject em sua cena e defina o marcador pré-fabricado para o pré-fabricado que você criou.

Para obter instruções e informações mais detalhadas, vá para códigos QR em 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 preparo um aplicativo que não seja Unity para usar o OpenXR para detetar códigos QR?

A deteçã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 deteção, UUID e dados de código QR em buffer para códigos QR detetados.

Para habilitar o suporte a código QR, as extensões XR_MSFT_scene_marker e XR_MSFT_scene_understanding devem ser 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 preparo uma UWP para usar Microsoft.MixedReality.QR.QRCodeWatcher?

Nota

O seguinte é específico para as APIs de código QR herdadas. Em vez disso, 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 corretas da arquitetura dos plugins e use-as de acordo na compilação.

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

Nota

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

Use o NuGet for 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 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 a distância e a posição angular a partir do código QR.
Como é a iluminação? Há um problema conhecido em que a deteção se torna difícil quando o código QR está em um fundo ambiente escuro - o código QR aparecerá lavado 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 detetado 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 até +/- 1 mm de desconto no tamanho medido. Sob deteção contínua, a posição de um código pode se desviar em até +/- 2,5 mm. Depois de sair do intervalo de deteção, a posição de uma deteção anterior fica à mercê do erro de mapa.

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

A distância, obviamente, depende do tamanho do código QR, e também da versão que 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 lado a 25 cm de lado, a distância mínima de deteção varia de 0,25 metros a 0,5 metros. O mais longe que estes podem ser detetados 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 deteção para o tamanho aumenta linearmente. Para qualquer código menor, a deteção simplesmente não ocorrerá - 4-5 cm é o menor que podemos detetar.

Porque não consigo ler códigos QR com logótipos?

Não são suportados códigos QR com logótipos.

Os códigos QR são detetados, 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 aberto.
Alguns recursos, como o 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 guardados ao nível do "espaço" ou da aplicação?

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 detetados são mantidos na memória pelo motorista.

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

Nota

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

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

Reproduzir

Nota

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

Siga as etapas para reproduzir esse comportamento:

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

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

Microsoft.MixedReality.QR.pdb não encontrado mensagem de erro

Solução recomendada

Nota

O seguinte é específico para as APIs de código QR herdadas. Em vez disso, 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 numa sessão?

Há um limite de 100 códigos QR salvos no nível do sistema no motorista, 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, pode-se aplicar um algoritmo de suavização se os novos dados de pose do código QR forem detetados dentro de 5 segundos ou 10 cm do quadro detetado 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.

Partilhar via

Visão geral do rastreamento de código QR

Suporte de dispositivos

Versões de código QR suportadas