Codici a matrice in Unity

I visori VR HoloLens 2 possono tenere traccia e rilevare codici a matrice che possono essere usati per fornire ologrammi e altre funzionalità AR. Questo articolo illustra tutto ciò che è necessario sapere per iniziare a usare i codici a matrice nell'app Unity, tra cui:

• Aggiunta del rilevamento del codice a matrice all'app Unity.
• Informazioni sui concetti importanti e sui componenti di Unity da usare.
• Vengono fornite esercitazioni che illustrano l'utilizzo comune del codice a matrice.
• Introduce lo scenario di esempio ar marker che illustra una scena abilitata per il codice a matrice e script di esempio.

Prima di continuare con questo articolo, è consigliabile esaminare la panoramica dei codici a matrice.

Configurazione del progetto e dell'app Unity

Il progetto e l'app Unity devono essere configurati e configurati correttamente per abilitare la funzionalità del codice a matrice, che richiede:

• OpenXR per Windows Realtà mista versione 113.2403.5001 o successiva.

  Nota

  Questo viene fornito con il sistema operativo e può essere aggiornato tramite Windows Store. Tenere presente che gli utenti potrebbero avere versioni precedenti installate e che i dispositivi non potranno usare indicatori AR, ad esempio codici a matrice, fino all'aggiornamento alla versione 113.2403.5001 o successiva.

• Un progetto compatibile con una versione supportata di Unity:
  • Unity 2022.3 LTS (scelta consigliata)
  • Unity 2021.3 LTS
• Plug-in OpenXR Realtà mista.
• Funzionalità webcam abilitate per il progetto Unity.
• Autorizzazioni della fotocamera concesse all'app.

Le sezioni seguenti illustrano come configurare il progetto Unity e l'app per abilitare il rilevamento del codice a matrice.

Recupero del plug-in OpenXR Realtà mista

Il pacchetto del plug-in OpenXR Realtà mista contiene API C# che è possibile usare per accedere alla funzionalità del codice a matrice.

Per importare il pacchetto:

1. Scaricare ed eseguire lo strumento funzionalità Realtà mista.
2. Installare il plug-in OpenXR.

Lo strumento Realtà mista funzionalità semplifica anche la gestione dei pacchetti e può essere usato per trovare, aggiornare e aggiungere le funzionalità Realtà mista richieste dall'app. Per istruzioni dettagliate su come usare lo strumento, vedere Welcome to the Realtà mista Feature Tool .See Welcome to the Realtà mista Feature Tool for detailed instructions on how to use the tool.

Abilitazione delle funzionalità WebCam

Per rilevare e tenere traccia dei codici a matrice, il progetto Unity deve avere funzionalità WebCam abilitate.

Per abilitare le funzionalità webcam :

1. Aprire il progetto Unity.
2. Fare clic su Modifica nel menu dell'app dell'editor di Unity.
3. Passare a Project Settings Player (Lettore impostazioni > progetto) e selezionare la scheda UWP come illustrato:
4. Abilitare WebCam nell'elenco Funzionalità .
5. Uscire da Impostazioni progetto.

Le funzionalità WebCam sono ora abilitate per l'app Unity. Tuttavia, all'app devono comunque essere concesse le autorizzazioni per accedere alla fotocamera del dispositivo.

Concessione delle autorizzazioni di accesso alla fotocamera dell'app

Se l'app dispone di funzionalità WebCam abilitate, la finestra di dialogo delle autorizzazioni richiede agli utenti di concedere all'app l'accesso alla fotocamera del dispositivo.

Questa finestra di dialogo viene visualizzata agli utenti una sola volta, in genere quando si immette una scena contenente un oggetto con supporto per l'indicatore ARMarkerManager di codice a matrice abilitato. Se l'accesso alla fotocamera viene negato, gli utenti possono passare a Impostazioni > App e abilitarlo tramite le opzioni avanzate dell'app.

Compilazione del rilevamento di codice a matrice in una scena

Il rilevamento del codice a matrice deve essere integrato in ogni scena in cui si vogliono usare codici a matrice, che richiedono:

• Oggetto GameObject con ARMarkerManager associato. ARMarkerManager è responsabile esclusivamente della creazione, dell'aggiornamento e della rimozione di ogni GameObject codice a matrice rilevato.
• Prefab collegato ARMarker .
• ARMarkerManager configurato per l'uso del prefab durante la creazione di un GameObject oggetto quando viene rilevato un codice a matrice.

Creazione di un prefab per i codici a matrice

Per usare i codici a matrice nella scena, è necessario creare un prefab per i codici a matrice. ARMarkerManager usa questo prefab per creare un oggetto GameObject da ogni volta che viene rilevato un codice a matrice.

Per creare un prefab per i codici a matrice:

1. Creare un nuovo prefab per il progetto.
2. Aggiungere il ARMarkercomponente al prefab, disponibile in Script > Microsoft.MixedReality.OpenXR > ARMarker.
   

È ora disponibile un prefab di base con cui lavorare. È probabile che l'app rappresenti visivamente i codici a matrice rilevati nell'ambiente. La sezione successiva illustra come aggiungere una rappresentazione visiva per i codici a matrice.

Aggiunta di oggetti visivi

Nella sezione precedente, anche l'aggiunta ARMarkeral prefab ha aggiunto automaticamente il ARMarkerScale componente. Questo componente viene usato per associare la scala della rappresentazione visiva di un codice a matrice alla controparte fisica.

A questo scopo:

1. Aggiungere un oggetto vuoto GameObject al prefab creato nella sezione precedente. Rappresenta tutto il contenuto dell'indicatore visivo.
2. Aggiungere un elemento figlio 3D GameObject, ad esempio , Quadal contenuto GameObjectdell'indicatore .
3. Nel componente del ARMarkerScale prefab impostare Trasformazione scala marcatore sul contenuto GameObjectdell'indicatore . L'impostazione di questo campo garantisce che il 3D GameObject scelto venga ridimensionato correttamente in modo che corrisponda ai codici a matrice reali.

Aggiunta ARMarkerManager a una scena

ARMarkerManager è responsabile esclusivamente della creazione, dell'aggiornamento e della rimozione di ogni GameObject codice a matrice rilevato.

Per aggiungere ARMarkerManager alla scena:

1. Posizionare un oggetto GameObject nella scena.
2. Aggiungere il ARMarkerManager componente a GameObject, disponibile in Script > Microsoft.MixedReality.OpenXR > ARMarkerManager.
   
3. Impostare il ARMarkerManager campo Prefab marcatore sul prefab creato nella sezione precedente.
4. Espandere Tipi di marcatori abilitati, quindi scegliere un elemento e impostarlo su Codice a matrice.

Tenere traccia delle modifiche al codice a matrice

ARMarkerManager contiene l'evento markersChanged , che fornisce ARMarkersChangedEventArgs ai sottoscrittori. Usare questi argomenti di evento per tenere traccia dei codici a matrice aggiunti o rimossi dal rilevamento o dai dati di posa aggiornati.

Nel codice seguente viene illustrata la sottoscrizione all'evento ARMarkerManager.markersChanged , usando gli argomenti dell'evento per scorrere gli ARMarker oggetti ARMarkerManager e scrivendo in Debug, indipendentemente dal fatto che vengano aggiunti, rimossi o aggiornati.

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}");
    }
}

Recupero dell'ultimo rilevamento di un codice a matrice

Usare la ARMarker.lastSeenTime proprietà per determinare quando il dispositivo ha rilevato un codice a matrice rilevato e la quantità di tempo, se presente, viene perso il rilevamento. Il tempo viene misurato nel numero di secondi dall'avvio dell'applicazione Unity ed è analogo a UnityEngine.Time.realtimeSinceStartup.

Uso dell'ID rilevabile di un codice a matrice

I codici a matrice sono rilevabili, che sono qualsiasi elemento che un dispositivo AR può rilevare e tenere traccia in un ambiente fisico. I rilevabili derivano dal tipo ARTrackable<TSessionRelativeData, TTrackable> che fornisce un ID, uno stato di rilevamento, una posizione e altri dati.

L'ID rilevabile per un codice a matrice può essere passato ai ARMarkerManager metodi per ottenere le proprietà del codice a matrice, i dati di byte non elaborati e la rappresentazione di stringa e per impostare la modalità di trasformazione per il codice a matrice. Questi metodi consentono di recuperare i dati per un codice a matrice senza dover tenere premuto un riferimento a un ARMarker oggetto.

È possibile passare l'ID di un codice a matrice nei metodi seguenti 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)

Seguendo lo stato di rilevamento di un codice a matrice

Poiché un oggetto ARMarker è rilevabile, eredita la trackingState proprietà ed è impostata su uno di tre UnityEngine.XR.ARSubsystems.TrackingState:

• Limited: indica che il codice a matrice è in corso di rilevamento, ma le informazioni limitate sono disponibili o sono di scarsa qualità.
• Tracking: specifica che il codice a matrice viene monitorato completamente.
• None: indica che il codice a matrice non viene rilevato.

Per monitorare lo stato di rilevamento per un codice a matrice, sottoscrivere ARMarkerManager.markersChanged e scorrere le ARMarker raccolte di marcatori fornite negli argomenti dell'evento passati al gestore eventi.

Il codice seguente illustra l'uso dell'evento ARMarkerManager.markersChanged per scorrere ARMarker gli oggetti per i codici a matrice appena rilevati e scrivere il relativo ID rilevabile nella finestra Debug.

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.");
    }
}

Recupero della versione e del tipo di codice a matrice di un codice a matrice

Per ottenere la versione e il tipo di un codice a matrice rilevato:

1. Chiamare , che restituisce ARMarker.GetQRCodeProperties()un'istanza QRCodeProperties di .
2. Accedere al campo QRCodeProperties nel valore restituito per ottenere il tipo di codice a matrice. Il valore può essere QRCodeType.QRCode o QRCodeType.MicroQRCode.
3. Accedere al campo del QRCodeProperties.version valore restituito per ottenere la versione del codice a matrice. Il valore è compreso tra 1 e 40 se il tipo è QRCodeType.QRCodee da 1 a 4 se il tipo è QRCodeType.MicroQRCode.

In alternativa, passare l'ID tracciabile di un ARMarker oggetto per ARMarkerManager.GetQRCodeProperties(TrackableId) ottenere il tipo e la versione di un codice a matrice.

Lettura dei dati a matrice

Il ARMarker componente è collegato a ogni GameObject oggetto creato ARMarkerManager . ARMarker fornisce due metodi che restituiscono dati di codice a matrice:

• GetDecodedString(): questo metodo ottiene la rappresentazione di stringa del codice a matrice, ad esempio un URL.

• GetRawData(Unity.Collections.Allocator allocator): questo metodo restituisce il contenuto del codice a matrice come matrice di byte, consentendo l'ottimizzazione con granularità fine sulla modalità di allocazione della matrice. Usare questo metodo nei percorsi ad accesso frequente e in altre situazioni in cui le prestazioni sono critiche.

Il codice seguente illustra l'utilizzo di base di GetDecodedString() e 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();
    }
}

Recupero delle dimensioni, della posizione, della rotazione e del centro del codice a matrice

Un ARMarker oggetto fornisce le dimensioni, la posizione, la rotazione e il centro del codice a matrice rappresentato.

Per ottenere le dimensioni del codice a matrice in metri, usare la proprietà ARMarker.size.

Usare la ARMarker.transform proprietà per ottenere la rotazione e la posizione dello spazio globale della trasformazione del codice a matrice e ARMarker.center per le coordinate 2D del codice a matrice relative alla trasformazione del codice a matrice. La trasformazione stessa viene centrata in base al fatto che ARMarker.transformMode (la modalità di trasformazione) sia impostata TransformMode.MostStable su (più stabile, il codice a matrice in alto a sinistra) o TransformMode.Center (al centro, il centro geometrico del codice a matrice).

Usare il ARMarkerManager.defaultTransformMode campo per impostare la modalità ARMarkerManager di trasformazione con cui vengono creati nuovi ARMarker oggetti. Il campo viene inizializzato con il Default Transform Mode campo è impostato su in Unity Inspector come illustrato di seguito:

In alternativa all'uso ARMarker.transformModedi , passare l'ID rilevabile di un ARMarker oggetto a ARMarkerManager.SetTransformMode(TrackableId, TransformMode) per impostarne la modalità di trasformazione.

Il codice seguente illustra come ottenere le dimensioni e il centro di un nuovo codice a matrice, la posizione e la rotazione della trasformazione e la posizione di trasformazione aggiornata dopo aver modificato la modalità di trasformazione.

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}");
    }
}

Scenario di esempio di marcatore AR

L'esempio fornito con il pacchetto OpenXR Plugin contiene una scena abilitata per il codice a matrice che fornisce un esempio di come ARMarkerManager e ARMarker può essere usato.

La scena si trova in Assets > ARMarker come illustrato:

Gli script C# usati nella scena sono disponibili nel repository OpenXR Unity Realtà mista Samples in GitHub: /OpenXR-Unity-MixedReality-Samples/tree/main/SampleScenarios/Scenarios/MarkerSample/Scripts

Vedi anche

• Informazioni di riferimento sulle API del plug-in OpenXR Realtà mista
• Panoramica dei codici a matrice