Vue d’ensemble du suivi des codes QR

Article
05/24/2024

Pour accéder au dépôt GitHub pour l’exemple de code QR :

Avec les casques Windows Mixed Reality et HoloLens, votre application peut détecter les codes QR dans l’environnement autour du casque, en établissant un système de coordonnées à l’emplacement réel de chaque code. Vous pouvez également afficher des hologrammes dans le même emplacement sur plusieurs appareils pour créer une expérience partagée. Une fois que vous avez activé la webcam de votre appareil, vous reconnaîtrez les codes QR dans les dernières versions de vos projets. Pour obtenir les meilleurs résultats en production, nous vous recommandons de passer en revue la section bonnes pratiques .

Cet article porte sur les points suivants :

Appareils pris en charge pour le suivi du code QR
Versions de code QR prises en charge
Meilleures pratiques pour la détection de code QR
Dépannage et FAQ

Prise en charge des appareils

Produit	HoloLens 1ère génération	HoloLens 2	Casques immersifs
OpenXR		✔️ (avec l’extension OpenXR Runtime version 113 et OpenXR XR_MSFT_scene_marker )
Plug-in Mixed Reality Unity		✔️ (avec le plug-in `ARMarkerManager`Unity OpenXR Runtime version 113 et Mixed Reality Unity)
SDK QR hérité	✔️	✔️	✔️

Remarque

Les API de code QR héritées sont spécifiques aux API de code QR héritées. Nous vous recommandons d’utiliser l’implémentation OpenXR pour les codes QR à la place.

À l’aide du SDK de code QR hérité, le suivi du code QR avec des casques Windows Mixed Reality immersifs sur les PC de bureau est pris en charge sur Windows 10 version 2004 et ultérieure. Utilisez l’API Microsoft.MixedReality.QRCodeWatcher.IsSupported() pour déterminer si la fonctionnalité est prise en charge sur l’appareil actuel.

Versions de code QR prises en charge

Le tableau suivant répertorie les versions de code QR prises en charge et non prises en charge :

	Versions du code QR
Pris en charge :	Code QR versions 1 - 10 Micro QR Codes M1-M4 Tous les encodages
Non pris en charge :	Codes QR 10 - 20 (non entièrement pris en charge) Codes QR versions 21+ Modules ajustés, par exemple : modules circulaires, réflexions, inversés (noir/blanc). Logos Ajouts structurés

Meilleures pratiques pour la détection de code QR

Zones calmes autour des codes QR

Pour être lu correctement, les codes QR nécessitent une marge autour de tous les côtés du code. Cette marge ne doit contenir aucun contenu imprimé et doit comporter quatre modules (un carré noir unique dans le code).

La documentation officielle du code QR contient plus d’informations sur les zones silencieuses.

Éclairage et toile de fond

La qualité de détection de code QR est susceptible de varier en éclairage et en arrière-plan.

Dans des conditions d’éclairage normales, fournissez suffisamment de contraste pour les modules noirs/blancs pour de meilleures performances.
Dans des conditions d’éclairage extrêmes avec un éclairage lumineux ou un arrière-plan sombre, vous pouvez essayer de réduire et d’ajuster le contraste qui pourrait améliorer le taux de détection de code QR. L’arrière-plan blanc dans le code QR peut être réduit de 255 vers le bas.

Taille des codes QR

Les appareils Windows Mixed Reality et HoloLens ne fonctionnent pas avec des codes QR avec des côtés inférieurs à 5 cm.

Pour les codes QR avec des côtés allant de 5 cm à 10 cm, l’appareil doit être assez proche pour détecter le code. La détection du code peut prendre plus de temps que la moyenne.

Le temps exact de détection des codes dépend non seulement de la taille des codes QR, mais de la distance entre vous et le code. Le fait de se rapprocher du code permet de compenser les problèmes de taille.

Distance et position angulaire du code QR

Les caméras de suivi ne peuvent détecter qu’un certain niveau de détail. Pour les petits codes (moins de 10 cm le long des côtés), vous devez être assez proche. Pour un code QR version 1 variant de 10 cm à 25 cm de taille, la distance de détection minimale est comprise entre 0,15 mètres et 0,5 mètres.

La distance de détection pour la taille augmente linéairement, mais dépend également de la version QR ou de la taille du module prise en charge. Plus la version est élevée, plus les modules ne peuvent être détectés qu’à partir d’une position plus proche. Vous pouvez également essayer des codes micro-QR si vous souhaitez que la distance de détection soit plus longue. La détection QR fonctionne avec une plage d’angles += 45g pour nous assurer que nous disposons d’une résolution appropriée pour détecter le code.

Autres considérations relatives à la détection :

Les codes QR sur les surfaces courbes ne sont pas pris en charge.
L’orientation dans le plan est prise en charge. Hors plan doit être <= +-45 regardant directement sur pour avoir une meilleure détection.
La taille physique du code QR doit avoir des modules d’au moins 2/3 pixels. Remarque : Les versions supérieures des codes QR auront des modules plus petits.

Pour connaître la relation de compromis entre la distance et la taille du code QR pour une détection optimale, consultez le graphique suivant :

Graphique de distance de taille de code QR

Important

Veillez toujours à avoir suffisamment de contraste et une bordure appropriée.

Gestion des données de code QR

Les appareils Windows Mixed Reality et HoloLens détectent les codes QR au niveau du système dans le pilote. Lorsque l’appareil est redémarré ou que le pilote redémarre, l’historique des codes QR détectés est effacé. Les codes QR détectés sont traités comme de nouveaux objets.

Nous vous recommandons de configurer votre application pour ignorer les codes QR antérieurs à un horodatage spécifique, qui peut être spécifié dans l’application. L’API de code QR spécifie l’heure à laquelle la dernière détection s’est produite. La plupart des développeurs d’applications utilisent l’heure système à laquelle l’application est lancée pour déterminer l’heure à laquelle un code QR est détecté.

Les données de code QR ne sont pas spécifiques à l’application. Lors du lancement de l’application, il y aura une liste des codes QR disponibles fournis. Le développeur de l’application détermine quels codes QR sont pertinents pour cette application.

Positionnement du code QR dans un espace

Pour obtenir des recommandations sur l’emplacement et la façon de placer des codes QR, reportez-vous aux considérations relatives à l’environnement pour HoloLens.

Résolution des problèmes et FAQ

Quelles sont les fonctionnalités nécessaires ?

Pour activer le suivi du code QR dans votre application HoloLens, ajoutez la fonctionnalité webcam au manifeste de l’application. Si vous développez dans Unity, vous pouvez le configurer à partir des paramètres du lecteur.

En outre, les utilisateurs peuvent être invités par la boîte de dialogue d’autorisations pour accorder des autorisations à votre webcam d’application. Cela ne se produit qu’une seule fois au cours de la durée de vie d’une application. Dans les cas tels que l’application demandant explicitement l’accès webcam, la boîte de dialogue ne réapparaît pas.

Pour les applications Unity avec la fonctionnalité WebCam, l’activation ARMarkerManager dans une scène peut déclencher la boîte de dialogue d’autorisation de webcam à apparaître.

Pour les applications OpenXR C++ natives, les appels initiaux à xrComputeNewSceneMSFT avec XrNewSceneComputeInfoMSFT::requestedFeatures utilisant XR_SCENE_COMPUTE_FEATURE_MARKER_MSFT le conteneur peuvent déclencher la boîte de dialogue autorisations.

Remarque

Les API de code QR héritées sont spécifiques aux API de code QR héritées. Nous vous recommandons d’utiliser l’implémentation OpenXR pour les codes QR à la place.

Vous aurez besoin de la fonctionnalité webcam ajoutée à votre manifeste (case à cocher dans Fonctionnalités Unity). Si vous créez un projet UWP standard, il se trouve également dans package.appxmanifest dans le projet de solution.

Dans le SDK de code QR hérité, demandez l’accès en appelant la méthode suivante :

#if WINDOWS_UWP

async QRCodeWatcher.RequestAccessAsync();

#endif

L’état d’accès doit être (status == QRCodeWatcherAccessStatus::Allowed).

Si l’accès est refusé, la fonctionnalité renvoie l’accès refusé lorsque vous démarrez le QRTracking.

Cette API doit être appelée avant de construire l’objet QRCodeWatcher .

Si vous exécutez le projet à partir d’Unity, vous devez également vous assurer que vous appelez à partir du thread d’interface utilisateur. Sinon, l’API retourne toujours refusé. Pour plus d’informations, consultez la classe AppCallbacks dans le Manuel Unity.

Pour plus d’informations sur la configuration de votre projet pour Unity, consultez configurer Unity pour Windows Mixed Reality.

Comment faire rendre la fonctionnalité de suivi du code QR fonctionne sur les appareils HoloLens 2 ?

Le suivi QR est automatique sur HoloLens 2 et vous aurez besoin de la fonctionnalité « webcam » ajoutée à votre application.

Où puis-je trouver les fichiers de plug-in d’API ?

Les applications doivent utiliser le runtime OpenXR d’HoloLen pour détecter les codes QR. OpenXR pour Windows Mixed Reality (113.2403.5001 ou version ultérieure) fournit une prise en charge du code QR sur les appareils HoloLens.

Pour les applications Unity, la prise en charge du code QR est fournie via le composant fourni avec le ARMarkerManager plug-in Mixed Reality OpenXR.

Pour la prise en charge du code QR dans les applications non Unity, utilisez l’extension openXR XR_MSFT_scene_marker .

Remarque

Les API de code QR héritées sont spécifiques aux API de code QR héritées. Nous vous recommandons d’utiliser l’implémentation OpenXR pour les codes QR à la place.

Tous les fichiers et la documentation requis sont disponibles ici sur NuGet :

Microsoft.MixedReality.QR

Comment faire préparer une application Unity pour utiliser ARMarkerManager pour détecter les codes QR ?

Dans les applications Unity, le composant est utilisé pour gérer la façon dont la ARMarkerManager détection de code QR dans un environnement physique est représentée dans une scène. ARMarkerManager Fournit:

Événements pour avertir les abonnés lorsqu’un code QR détecté a été ajouté au gestionnaire, mis à jour ou supprimé.
Collection de suivis pour ARMarker les codes QR en cours de détection.
Méthodes retournant des données pour les codes QR comme spécifié par l’ID trackable.

Pour l’utiliser ARMarkerManager dans votre application, vous devez importer le package de plug-in OpenXR Mixed Reality.

Pour importer le package :

Téléchargez et exécutez Mixed Reality Feature Tool.
Installez le plug-in OpenXR.

Pour obtenir des instructions détaillées sur l’utilisation de l’outil, consultez Bienvenue dans l’outil De réalité mixte.

La procédure générale suivante consiste à :

Dans votre projet Unity, activez les fonctionnalités WebCam .
Créez un préfabriqué et attachez le ARMarker composant comme indiqué :
Ouvrez une scène que vous souhaitez que les codes QR soient détectés lors de l’exécution.
Attachez-vous à un GameObject dans votre scène et définissez ARMarkerManager Marker Prefab sur le préfabriqué que vous avez créé.

Pour obtenir des instructions et des informations plus détaillées, accédez aux codes QR dans Unity.

Pour obtenir un exemple d’utilisation de codes QR dans votre application Unity, consultez l’exemple de scénario de code QR sur GitHub.

Comment faire préparer une application non Unity pour utiliser OpenXR pour détecter les codes QR ?

La détection de code QR dans OpenXR est fournie via l’extension XR_MSFT_scene_marker . Cette extension permet à plusieurs codes QR d’être suivis et peut fournir une taille, une position, un horodatage de la dernière détection, un UUID et des données de code QR mis en mémoire tampon pour les codes QR détectés.

Pour activer la prise en charge du code QR, les extensions XR_MSFT_scene_marker et XR_MSFT_scene_understanding doivent être activées.

Pour obtenir une étape détaillée, consultez la vue d’ensemble de l’extension XR_MSFT_scene_marker dans la spécification OpenXR 1.0.

Pour obtenir un exemple d’utilisation des codes QR, consultez Scene_QRCode.cpp dans l’exemple SceneUnderstandingUwp sur GitHub.

Comment faire préparer un UWP pour utiliser Microsoft.MixedReality.QRCodeWatcher ?

Remarque

Les API de code QR héritées sont spécifiques aux API de code QR héritées. Nous vous recommandons d’utiliser l’implémentation OpenXR pour les codes QR à la place.

Utilisez le pack NuGet pour décompresser les fichiers requis.
Ajoutez une référence au projet et commencez à Microsoft.MixedReality.QR.winmd utiliser l’API.
Ajoutez les versions d’architecture correctes des plug-ins et utilisez-les en conséquence dans la build.

Comment faire préparer Unity avec Microsoft.MixedReality.QRCodeWatcher ?

Remarque

Les API de code QR héritées sont spécifiques aux API de code QR héritées. Nous vous recommandons d’utiliser l’implémentation OpenXR pour les codes QR à la place.

Utilisez NuGet pour Unity et pointez sur le pack NuGet ci-dessus.

Comment puis-je créer des codes QR ?

Consultez n’importe quel générateur de code QR.

Si le suivi du code QR ne fonctionne pas en général, que dois-je faire ?

La version du code QR est-elle prise en charge ? Nous ne prenons pas en charge les versions à haute densité comme la version 40. Rien au-dessus de la version 10 n’est garanti ; les versions supérieures à 20 ne sont pas prises en charge.
Êtes-vous assez proche du code QR ? Voir la distance et la position angulaire du code QR.
Comment est l’éclairage ? Il existe un problème connu dans lequel la détection devient difficile lorsque le code QR se trouve sur un arrière-plan environnemental sombre : le code QR apparaît effacé à la caméra en raison d’un contraste élevé. Pour plus d’informations, consultez éclairage et toile de fond.

Quelle est la précision ?

Lorsqu’elle est détectée dans un cadre unique, la taille est censée avoir au maximum une erreur de 1 % de la taille réelle. Par exemple, un code de 10 cm peut atteindre +/- 1 mm de la taille mesurée. Sous détection continue, la position d’un code peut dériver jusqu’à +/- 2,5 mm. Une fois que vous avez quitté la plage de détection, la position d’une détection précédente est jusqu’à la merci de l’erreur de carte.

À quelle proximité dois-je être au code QR pour le détecter ?

La distance dépend évidemment de la taille du code QR et de la version qu’il contient. Pour plus d’informations, consultez la distance et la position angulaire du code QR.

Sur HoloLens 2, pour un code QR version 1 variant entre 5 cm et 25 cm, la distance de détection minimale est comprise entre 0,25 mètres et 0,5 mètres. Les plus éloignés peuvent être détectés d’environ 0,5 m pour le plus petit code à deux mètres pour le plus grand.
Sur Windows Mixed Reality, ces distances pour les tailles sont divisées en deux.
Pour tous les codes plus volumineux, extrapolez-la distance de détection pour la taille augmente linéairement. Pour tout code plus petit, la détection ne se produit pas simplement --4-5 cm est la plus petite que nous pouvons détecter.

Pourquoi ne puis-je pas lire les codes QR avec des logos ?

Les codes QR avec logos ne sont pas pris en charge.

Les codes QR sont détectés. Pourquoi ne reçois-je pas de données ?

Si la plateforme ne peut pas décoder le code QR, il n’y aura pas de données. Vous pouvez utiliser le flux et interpréter les données à l’aide du code open source.
Certaines fonctionnalités, telles que l’ajout de structure, ne sont pas prises en charge.

Pour plus d’informations, consultez les versions de code QR prises en charge ?.

Les codes QR sont-ils enregistrés au niveau « espace » ou au niveau de l’application ?

Les codes QR sont enregistrés au niveau du système dans la session du pilote ou la session de démarrage sur HoloLens. Pour plus d’informations, consultez la gestion des données de code QR.

Comment cela fonctionne-t-il avec la plateforme sous-jacente ? Où sont-ils persistants ?

Les codes QR détectés sont conservés en mémoire par le pilote.

Comment faire déboguer l’application dans Visual Studio quand je reçois le message d’erreur «`Microsoft.MixedReality.QR.pdb` introuvable » ?

Remarque

Les API de code QR héritées sont spécifiques aux API de code QR héritées. Nous vous recommandons d’utiliser l’implémentation OpenXR pour les codes QR à la place.

Le chargement de symboles pour Microsoft.MixedReality.QR.dll a été ignoré, car il n’est pas spécifié dans la liste des modules inclus.

Opérations à reproduire

Remarque

Les API de code QR héritées sont spécifiques aux API de code QR héritées. Nous vous recommandons d’utiliser l’implémentation OpenXR pour les codes QR à la place.

Suivez les étapes pour reproduire ce comportement :

Installer Microsoft.MixedReality.QR (NuGet) et MRTK
Essayer de déboguer

Vous devez être en mesure de déboguer l’application avec Microsoft.MixedReality.QR.dll, mais la DLL n’est pas trouvée :

Message d’erreur Introuvable dans Microsoft.MixedReality.QR.pdb

Solution recommandée

Remarque

Les API de code QR héritées sont spécifiques aux API de code QR héritées. Nous vous recommandons d’utiliser l’implémentation OpenXR pour les codes QR à la place.

Nous travaillons sur l’ajout de symboles à la prochaine version. En attendant, vous devez toujours être en mesure de déboguer votre application en excluant la DLL dans les options Visual Studio :

exclusion de la DLL dans les options de Visual Studio

Pour plus d’informations, consultez Configuration des paramètres de Visual Studio.

Existe-t-il une limite de combien de codes QR peuvent être analysés dans une session ?

Il existe une limite de 100 codes QR enregistrés au niveau du système dans le pilote, dans les 10 minutes.

Le processus de lissage du code QR a-t-il changé ?

Le processus de lissage du code QR a changé après 20H2, de la pose lissage à la taille de lissage. Pour rétablir le comportement du processus de lissage précédent, il est préférable d’appliquer un algorithme de lissage si les nouvelles données de pose de code QR sont détectées dans les 5 secondes ou 10 cm du cadre précédemment détecté. Les données de transformation sont fusionnées via un ratio pondéré de 90 % de l’image actuelle avec 10 % de l’image précédente.

Partager via

Vue d’ensemble du suivi des codes QR

Prise en charge des appareils

Versions de code QR prises en charge