Codes QR dans Unity
Les casques HoloLens 2 peuvent suivre et détecter les codes QR qui peuvent être utilisés pour fournir des hologrammes et d’autres fonctionnalités AR. Cet article vous guide tout ce dont vous avez besoin pour commencer à utiliser des codes QR dans votre application Unity, notamment :
- Ajout de la détection de code QR à votre application Unity.
- Comprendre les concepts importants et les composants Unity que vous devez utiliser.
- Fournit des didacticiels qui couvrent l’utilisation courante du code QR.
- Présente l’exemple de scénario de marqueur AR qui illustre une scène avec code QR et des exemples de scripts.
Avant de continuer avec cet article, nous vous recommandons de passer en revue la vue d’ensemble des codes QR.
Configuration de votre projet et de votre application Unity
Votre projet et votre application Unity doivent être configurés et configurés correctement pour activer la fonctionnalité de code QR, ce qui nécessite :
- OpenXR pour Windows Mixed Reality version 113.2403.5001 ou ultérieure.
Remarque
Cela est fourni avec le système d’exploitation et peut être mis à jour via le Windows Store. N’oubliez pas que les utilisateurs peuvent avoir installé des versions antérieures et que leurs appareils ne pourront pas utiliser des marqueurs AR tels que des codes QR jusqu’à la mise à jour vers la version 113.2403.5001 ou ultérieure.
- Un projet compatible avec une version prise en charge d’Unity :
- Unity 2022.3 LTS (recommandé)
- Unity 2021.3 LTS
- Plug-in Mixed Reality OpenXR.
- Fonctionnalités de webcam activées pour votre projet Unity.
- Autorisations d’appareil photo accordées à votre application.
Les sections suivantes vous guident tout au long de la configuration de votre projet et de votre application Unity pour activer la détection de code QR.
Obtention du plug-in Mixed Reality OpenXR
Le package de plug-in OpenXR Mixed Reality contient des API C# que vous pouvez utiliser pour accéder aux fonctionnalités de code QR.
Pour importer le package :
- Téléchargez et exécutez Mixed Reality Feature Tool.
- Installez le plug-in OpenXR.
Mixed Reality Feature Tool simplifie également la gestion des packages et peut être utilisé pour rechercher, mettre à jour et ajouter les fonctionnalités de réalité mixte dont votre application a besoin. Pour obtenir des instructions détaillées sur l’utilisation de l’outil, consultez Bienvenue dans l’outil De réalité mixte.
Activation des fonctionnalités WebCam
Pour détecter et suivre les codes QR, votre projet Unity doit avoir des fonctionnalités WebCam activées.
Pour activer les fonctionnalités webCam :
- Ouvrez votre projet Unity.
- Cliquez sur Modifier dans le menu de l’application de l’éditeur Unity.
- Accédez au Lecteur des paramètres > du projet et sélectionnez l’onglet UWP, comme indiqué :
- Activez WebCam dans la liste des fonctionnalités .
- Quittez les paramètres du projet.
Les fonctionnalités WebCam sont désormais activées pour votre application Unity. Toutefois, votre application doit toujours disposer des autorisations nécessaires pour accéder à la caméra de l’appareil.
Octroi des autorisations d’accès à la caméra de votre application
Si les fonctionnalités webCam de votre application sont activées, la boîte de dialogue d’autorisations invite les utilisateurs à accorder à votre application l’accès à la caméra de l’appareil.
Cette boîte de dialogue s’affiche aux utilisateurs une seule fois, généralement lors de l’entrée d’une scène contenant une ARMarkerManager
prise en charge des marqueurs de code QR activée. Si l’accès à la caméra est refusé, les utilisateurs peuvent accéder aux applications paramètres > et les activer via les options avancées de l’application.
Création d’une détection de code QR dans une scène
La détection de code QR doit être intégrée à chaque scène dans laquelle vous souhaitez utiliser des codes QR, ce qui nécessite :
- A
GameObject
avecARMarkerManager
attaché.ARMarkerManager
est uniquement responsable de la création, de la mise à jour et de la suppression de tous lesGameObject
codes QR détectés. - Un préfabriqué avec
ARMarker
attaché. ARMarkerManager
configuré pour utiliser le préfabriqué lors de la création d’unGameObject
code QR détecté.
Création d’un préfabriqué pour les codes QR
Pour utiliser des codes QR dans votre scène, vous devez créer un préfabriqué pour les codes QR. ARMarkerManager
utilise ce préfabriqué pour créer un GameObject
code QR à partir de chaque fois qu’un code QR est détecté.
Pour créer un préfabriqué pour les codes QR :
- Créez un préfabriqué pour votre projet.
- Ajoutez le
ARMarker
composant au préfabriqué, situé sous Script > Microsoft.MixedReality.OpenXR > ARMarker.
Vous disposez maintenant d’un préfabriqué de base pour travailler avec. Vous souhaiterez probablement que votre application représente visuellement des codes QR détectés dans l’environnement. La section suivante vous guide tout au long de l’ajout d’une représentation visuelle pour les codes QR.
Ajout de visuels
Dans la section précédente, l’ajout ARMarker
au préfabriqué a également ajouté automatiquement le ARMarkerScale
composant. Ce composant est utilisé pour faire correspondre l’échelle de la représentation visuelle d’un code QR à son équivalent physique.
Pour ce faire :
- Ajoutez un vide
GameObject
au préfabriqué que vous avez créé dans la section précédente. Il représente tout le contenu du marqueur visuel. - Ajoutez un 3D
GameObject
enfant, tel qu’unQuad
, au contenuGameObject
du marqueur. - Dans le composant du
ARMarkerScale
préfabriqué, définissez la transformation de l’échelle de marqueur sur le contenuGameObject
du marqueur. La définition de ce champ garantit que la 3DGameObject
que vous avez choisie est correctement mise à l’échelle pour correspondre aux codes QR réels.
Ajout ARMarkerManager
à une scène
ARMarkerManager
est uniquement responsable de la création, de la mise à jour et de la suppression de tous les GameObject
codes QR détectés.
Pour ajouter ARMarkerManager
à votre scène :
- Placez une
GameObject
dans votre scène. - Ajoutez le
ARMarkerManager
composant auGameObject
composant situé sous Script > Microsoft.MixedReality.OpenXR > ARMarkerManager.
- Définissez le
ARMarkerManager
champ Marker Prefab sur le préfabriqué que vous avez créé dans la section précédente. - Développez Types de marqueurs activés, puis choisissez un élément et définissez-le sur code QR.
Suivi des modifications du code QR
ARMarkerManager
contient l’événement markersChanged
, qui fournit ARMarkersChangedEventArgs
aux abonnés. Utilisez ces arguments d’événement pour suivre les codes QR ajoutés ou supprimés de la détection ou des données de pose mises à jour.
Le code suivant illustre l’abonnement à l’événementARMarkerManager.markersChanged
, à l’aide de ses arguments d’événement pour itérer au sein des objets ARMarkerManager
est la gestion et l’écriture ARMarker
dans Debug, qu’ils soient ajoutés, supprimés ou mis à jour.
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}");
}
}
Obtention de l’heure de la dernière détection d’un code QR
Utilisez la ARMarker.lastSeenTime
propriété pour déterminer quand l’appareil a suivi pour la dernière fois un code QR détecté et la durée, le cas échéant, le suivi est perdu. Le temps est mesuré en nombre de secondes depuis que Unity a démarré votre application et est analogue à UnityEngine.Time.realtimeSinceStartup
.
Utilisation de l’ID suivi d’un code QR
Les codes QR sont des pistes, qui sont tout ce qu’un appareil AR peut détecter et suivre dans un environnement physique. Les suivis dérivent du type ARTrackable<TSessionRelativeData, TTrackable>
qui fournit un ID, un état de suivi, une pose et d’autres données.
L’ID trackable d’un code QR peut être passé dans ARMarkerManager
des méthodes pour obtenir les propriétés du code QR, les données brutes d’octets et la représentation sous forme de chaîne, et définir le mode de transformation pour le code QR. Ces méthodes vous permettent de récupérer des données pour un code QR sans avoir à conserver une référence d’objet ARMarker
.
Vous pouvez transmettre l’ID d’un code QR aux méthodes suivantes ARMarkerManager
:
GetDecodedString(UnityEngine.XR.ARSubsystems.TrackableId trackableId)
GetMarker(UnityEngine.XR.ARSubsystems.TrackableId trackableId)
GetQRCodeProperties(UnityEngine.XR.ARSubsystems.TrackableId)
GetRawData(UnityEngine.XR.ARSubsystems.TrackableId, Unity.Collections.Allocator)
SetTransformMode(UnityEngine.XR.ARSubsystems.TrackableId, Microsoft.MixedReality.OpenXR.TransformMode)
Remarque
Pour le paramètre allocator
de méthode, le passage Unity.Collections.Allocator.Temp
est suffisant pour la GetRawData
plupart des scénarios.
Suivi de l’état de suivi d’un code QR
Étant donné qu’un ARMarker
élément est suivi, il hérite de la trackingState
propriété et est défini sur l’un des trois UnityEngine.XR.ARSubsystems.TrackingState
suivants :
Limited
: indique que le code QR est suivi, mais que des informations limitées sont disponibles ou sont de mauvaise qualité.Tracking
: spécifie que le code QR est entièrement suivi.None
: indique que le code QR n’est pas suivi.
Pour surveiller l’état de suivi d’un code QR, abonnez-vous aux ARMarkerManager.markersChanged
ARMarker
collections de marqueurs fournies dans les arguments d’événement passés à votre gestionnaire d’événements.
Le code suivant illustre l’utilisation de l’événement ARMarkerManager.markersChanged
pour itérer dans ARMarker
des objets pour les codes QR nouvellement détectés et écrire leur ID trackable dans la fenêtre Débogage.
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.");
}
}
Obtention de la version d’un code QR et du type de code QR
Pour obtenir la version et le type d’un code QR détecté :
- Appel
ARMarker.GetQRCodeProperties()
, qui retourne uneQRCodeProperties
instance. - Accédez au champ
QRCodeProperties
dans la valeur de retour pour obtenir le type du code QR. La valeur est soitQRCodeType.QRCode
, soitQRCodeType.MicroQRCode
. - Accédez au champ de la valeur de
QRCodeProperties.version
retour pour obtenir la version du code QR. La valeur est comprise entre 1 et 40 si le type estQRCodeType.QRCode
, et de 1 à 4 si le type estQRCodeType.MicroQRCode
.
En guise d’alternative, passez l’ID trackable d’un ARMarker
objet pour ARMarkerManager.GetQRCodeProperties(TrackableId)
obtenir le type et la version d’un code QR.
Avertissement
Les codes QR sont actuellement le seul type de marqueur pris en charge, même si la prise en charge d’autres types de marqueurs peut être ajoutée dans les versions ultérieures. Si markerType
ce n’est pas ARMarkerType.QRCode
le cas, l’appel GetQRCodeProperties(TrackableId)
lève System.InvalidOperationException
. Envisagez d’inclure des appels dans GetQRCodeProperties(TrackableId)
des blocs try-catch si cela peut entraîner des problèmes dans votre application ultérieurement.
Lecture des données QR
Le ARMarker
composant est attaché à chaque GameObject
création ARMarkerManager
. ARMarker
fournit deux méthodes qui retournent des données de code QR :
GetDecodedString()
: cette méthode obtient la représentation sous forme de chaîne du code QR, telle qu’une URL.GetRawData(Unity.Collections.Allocator allocator)
: cette méthode retourne le contenu du code QR en tant que tableau d’octets, ce qui permet un réglage précis sur la façon dont le tableau est alloué. Utilisez cette méthode dans des chemins d’accès chauds et d’autres situations où les performances sont critiques.
Le code suivant illustre l’utilisation de base et GetDecodedString()
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();
}
}
Obtention de la taille, de la position, de la rotation et du centre du code QR
Un ARMarker
objet fournit la taille, la position, la rotation et le centre du code QR qu’il représente.
Pour obtenir la taille du code QR en mètres, utilisez la propriété ARMarker.size
.
Utilisez la ARMarker.transform
propriété pour obtenir la rotation et la position de l’espace mondial de la transformation du code QR, ainsi ARMarker.center
que les coordonnées 2D du code QR par rapport à la transformation du code QR. La transformation elle-même est centrée selon que ARMarker.transformMode
(le mode de transformation) est défini TransformMode.MostStable
sur (le plus stable, le code QR en haut à gauche) ou TransformMode.Center
(centre, le centre géométrique du code QR).
Utilisez le champ pour définir le ARMarkerManager.defaultTransformMode
mode ARMarkerManager
de transformation avec lequel créer de nouveaux ARMarker
objets. Le champ est initialisé avec le Default Transform Mode
champ est défini sur dans l’inspecteur Unity, comme indiqué :
En guise d’alternative à l’utilisation ARMarker.transformMode
, transmettez l’ID trackable d’un ARMarker
objet pour ARMarkerManager.SetTransformMode(TrackableId, TransformMode)
définir son mode de transformation.
Le code suivant montre comment obtenir la taille et le centre d’un nouveau code QR, la position et la rotation de sa transformation, et la position de transformation mise à jour après avoir modifié le mode de transformation.
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}");
}
}
Exemple de scénario de marqueur AR
L’exemple fourni avec le package de plug-in OpenXR contient une scène avec code QR qui fournit un exemple de comment ARMarkerManager
et ARMarker
peut être utilisé.
La scène se trouve dans Assets > ARMarker , comme indiqué :
Vous trouverez les scripts C# utilisés dans la scène dans le référentiel Exemples de réalité mixte OpenXR Unity sur GitHub : /OpenXR-Unity-MixedReality-Samples/tree/main/SampleScenarios/Scenarios/MarkerSample/Scripts