Panoramica del rilevamento del codice a matrice

Per accedere al repository GitHub per l'esempio di codice a matrice:

Con i visori VR Windows Realtà mista e HoloLens, l'app può rilevare i codici a matrice nell'ambiente intorno al visore VR, stabilendo un sistema di coordinate in corrispondenza della posizione reale di ogni codice. È anche possibile eseguire il rendering degli ologrammi nella stessa posizione in più dispositivi per creare un'esperienza condivisa. Dopo aver abilitato la webcam del dispositivo, si riconosceranno i codici a matrice nelle versioni più recenti dei progetti. Per ottenere risultati ottimali nell'ambiente di produzione, è consigliabile esaminare la sezione procedure consigliate .

Questo articolo contiene informazioni relative agli argomenti seguenti:

• Dispositivi supportati per il rilevamento del codice a matrice
• Versioni supportate del codice a matrice
• Procedure consigliate per il rilevamento del codice a matrice
  • Zone silenziose intorno ai codici a matrice
  • Illuminazione e sfondo
  • Dimensioni dei codici a matrice
  • Distanza e posizione angolare dal codice a matrice
  • Gestione dei dati del codice a matrice
  • Posizionamento del codice a matrice in uno spazio
• Risoluzione dei problemi e domande frequenti
  • Quali funzionalità sono necessarie?
  • Ricerca per categorie rendere funzionante la funzionalità di rilevamento del codice a matrice nei dispositivi HoloLens 2?
  • Dove si trovano i file del plug-in dell'API?
  • Ricerca per categorie preparare un'app Unity per usare ARMarkerManager per rilevare i codici a matrice?
  • Ricerca per categorie preparare un'app non Unity per usare OpenXR per rilevare i codici a matrice?
  • Ricerca per categorie preparare una piattaforma UWP per l'uso di Microsoft.MixedReality.QR.QRCodeWatcher?
  • Ricerca per categorie preparare Unity con Microsoft.MixedReality.QR.QRCodeWatcher?
  • Come posso creare codici a matrice?
  • Se il rilevamento del codice a matrice non funziona in generale, cosa faccio?
  • Qual è l'accuratezza?
  • Quanto è necessario chiudere il codice a matrice per rilevarlo?
  • Perché non è possibile leggere codici a matrice con logo?
  • Vengono rilevati i codici a matrice, quindi perché non si ricevono dati?
  • I codici a matrice vengono salvati a livello di 'spazio' o app?
  • Come funziona con la piattaforma sottostante? Dove vengono mantenuti?
  • Ricerca per categorie eseguire il debug dell'app in Visual Studio quando viene visualizzato il messaggio di errore "Microsoft.MixedReality.QR.pdbnon trovato"?

Supporto di dispositivi

Usando l'SDK di codice a matrice legacy, il rilevamento del codice a matrice con visori VR immersive di Windows Realtà mista nei PC desktop è supportato in Windows 10 versione 2004 e successive. Usare l'API Microsoft.MixedReality.QRCodeWatcher.IsSupported() per determinare se la funzionalità è supportata nel dispositivo corrente.

Versioni supportate del codice a matrice

La tabella seguente elenca le versioni di codice a matrice supportate e non supportate:

Procedure consigliate per il rilevamento del codice a matrice

Zone silenziose intorno ai codici a matrice

Per essere letti correttamente, i codici a matrice richiedono un margine intorno a tutti i lati del codice. Questo margine non deve contenere alcun contenuto stampato e deve essere di quattro moduli (un singolo quadrato nero nel codice).

La documentazione ufficiale del codice a matrice contiene altre informazioni sulle zone non attendibili.

Illuminazione e sfondo

La qualità del rilevamento del codice a matrice è soggetta a diverse illuminazione e sfondo.

• In condizioni di illuminazione normali, fornire un contrasto sufficiente per i moduli in bianco/nero per ottenere prestazioni migliori.

• In condizioni di illuminazione estrema con illuminazione luminosa o sfondo scuro, è possibile provare a ridurre e regolare il contrasto che potrebbe migliorare la frequenza di rilevamento del codice a matrice. Lo sfondo bianco all'interno del codice a matrice può essere ridotto da 255 verso il basso.

Dimensioni dei codici a matrice

I dispositivi Windows Realtà mista e HoloLens non funzionano con codici a matrice con lati inferiori a 5 cm.

Per i codici a matrice con lati compresi tra 5 cm e 10 cm, il dispositivo deve essere abbastanza vicino per rilevare il codice. Il rilevamento del codice potrebbe richiedere più tempo della media.

Il tempo esatto per rilevare i codici dipende non solo dalle dimensioni dei codici a matrice, ma dalla distanza del codice. Il passaggio più vicino al codice consentirà di compensare i problemi relativi alle dimensioni.

Distanza e posizione angolare dal codice a matrice

Le telecamere di rilevamento possono rilevare solo un determinato livello di dettaglio. Per i codici piccoli (meno di 10 cm lungo i lati), è necessario essere abbastanza vicini. Per una versione 1 codice a matrice che varia da 10 cm a 25 cm di dimensione, la distanza minima di rilevamento è compresa tra 0,15 metri e 0,5 metri.

La distanza di rilevamento per le dimensioni aumenta in modo lineare, ma dipende anche dalla versione a matrice o dalle dimensioni del modulo supportate. Maggiore è la versione, i moduli più piccoli, che possono essere rilevati solo da una posizione più vicina. È anche possibile provare i codici a matrice micro se si vuole che la distanza di rilevamento sia più lunga. Il rilevamento a matrice funziona con un intervallo di angoli += 45 gradi per garantire una risoluzione corretta per rilevare il codice.

Altre considerazioni sul rilevamento:

• I codici a matrice sulle superfici curve non sono supportati.
• L'orientamento sul piano è supportato. Fuori piano deve essere <= +-45 guardando dritto su per avere un rilevamento migliore.
• Le dimensioni fisiche del codice a matrice devono avere moduli di almeno 2/3 pixel. Nota: le versioni successive dei codici a matrice avranno moduli più piccoli.

Per la relazione di compromesso tra distanza e dimensioni del codice a matrice per un rilevamento ottimale, vedere il grafico seguente:

Gestione dei dati del codice a matrice

I dispositivi Windows Realtà mista e HoloLens rilevano i codici a matrice a livello di sistema nel driver. Quando il dispositivo viene riavviato o il driver viene riavviato, la cronologia dei codici a matrice rilevata viene cancellata. I codici a matrice rilevati vengono considerati come nuovi oggetti.

È consigliabile configurare l'app per ignorare i codici a matrice precedenti a un timestamp specifico, che può essere specificato all'interno dell'app. L'API codice a matrice specifica l'ora dell'ultimo rilevamento. La maggior parte degli sviluppatori di app userà l'ora di sistema all'avvio dell'app per determinare l'ora in cui viene rilevato un codice a matrice.

I dati del codice a matrice non sono specifici dell'app. Al momento dell'avvio dell'app, verrà fornito un elenco di codici a matrice disponibili. Lo sviluppatore dell'app determinerà quali codici a matrice sono rilevanti per questa app.

Posizionamento del codice a matrice in uno spazio

Per consigli su dove e su come inserire i codici a matrice, vedere Considerazioni sull'ambiente per HoloLens.

Risoluzione dei problemi e domande frequenti

Quali funzionalità sono necessarie?

Per abilitare il rilevamento del codice a matrice nell'applicazione HoloLens, aggiungere la funzionalità webcam al manifesto dell'applicazione. Se si sviluppa in Unity, è possibile configurare questa opzione dalle impostazioni del lettore.

Inoltre, gli utenti potrebbero essere richiesti dalla finestra di dialogo delle autorizzazioni per concedere le autorizzazioni per la webcam dell'app. Questo avviene una sola volta per tutta la durata di un'app. In casi come l'app che richiede esplicitamente l'accesso alla webcam, la finestra di dialogo non verrà nuovamente visualizzata.

Per le app Unity con la funzionalità WebCam, l'abilitazione ARMarkerManager in una scena può attivare la finestra di dialogo di autorizzazione webcam da visualizzare.

Per le app Native OpenXR C++, le chiamate iniziali a xrComputeNewSceneMSFT con contenitore XrNewSceneComputeInfoMSFT::requestedFeatures XR_SCENE_COMPUTE_FEATURE_MARKER_MSFT possono attivare la finestra di dialogo delle autorizzazioni.

Sarà necessaria la funzionalità webcam aggiunta al manifesto (casella di controllo in Funzionalità unity). Se stai creando come progetto UWP standard, è anche nel progetto di soluzione package.appxmanifest.

Nell'SDK del codice a matrice legacy richiedere l'accesso chiamando il metodo seguente:

#if WINDOWS_UWP

async QRCodeWatcher.RequestAccessAsync();

#endif

Lo stato di accesso deve essere (status == QRCodeWatcherAccessStatus::Allowed).

Se l'accesso viene negato, la funzionalità restituirà l'accesso negato all'avvio di QRTracking.

Questa API deve essere chiamata prima di costruire l'oggetto QRCodeWatcher .

Se si esegue il progetto da Unity, è anche necessario assicurarsi di chiamare dal thread dell'interfaccia utente. In caso contrario, l'API restituirà sempre negato. Per altre informazioni, vedere Classe AppCallbacks nel manuale di Unity.

Per altre informazioni sulla configurazione del progetto per Unity, vedere Configurare Unity per Windows Realtà mista.

Ricerca per categorie rendere funzionante la funzionalità di rilevamento del codice a matrice nei dispositivi HoloLens 2?

Il rilevamento a matrice è automatico in HoloLens 2 ed è necessaria la funzionalità "webcam" aggiunta all'app.

Dove si trovano i file del plug-in dell'API?

Le applicazioni devono usare il runtime OpenXR di HoloLen per rilevare i codici a matrice. OpenXR per Windows Realtà mista (113.2403.5001 o versione successiva) fornisce il supporto del codice a matrice nei dispositivi HoloLens.

Per le app Unity, il supporto del codice a matrice viene fornito tramite il ARMarkerManager componente fornito con Realtà mista plug-in OpenXR.

Per il supporto del codice a matrice nelle app non Unity, usare l'estensione XR_MSFT_scene_marker OpenXR.

Tutti i file e la documentazione necessari sono disponibili qui in NuGet:

Microsoft.MixedReality.QR

Ricerca per categorie preparare un'app Unity per usare ARMarkerManager per rilevare i codici a matrice?

Nelle app Unity il componente viene usato per gestire il ARMarkerManager modo in cui il rilevamento del codice a matrice all'interno di un ambiente fisico viene rappresentato in una scena. ARMarkerManager Fornisce:

• Eventi per notificare ai sottoscrittori quando un codice a matrice rilevato è stato aggiunto al manager, aggiornato o rimosso.

• Raccolta di ARMarker rilevabili per i codici a matrice nel rilevamento.

• Metodi che restituiscono dati per i codici a matrice come specificato dall'ID rilevabile.

Per usare ARMarkerManager nell'app, è necessario importare il pacchetto del plug-in OpenXR Realtà mista.

Per importare il pacchetto:

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

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.

La procedura generale è la seguente:

1. Nel progetto Unity abilitare le funzionalità WebCam .
2. Creare un prefab e collegare il ARMarker componente come illustrato di seguito:
   
3. Aprire una scena che si vuole che i codici a matrice vengano rilevati durante l'esecuzione.
4. Collegarsi ARMarkerManager a un GameObject nella scena e impostare Prefab marcatore sul prefab creato.
   

Per istruzioni e informazioni più dettagliate, vedere Codici a matrice in Unity.

Per un esempio di come usare i codici a matrice nell'app Unity, vedere lo scenario di esempio di codice a matrice in GitHub.

Ricerca per categorie preparare un'app non Unity per usare OpenXR per rilevare i codici a matrice?

Il rilevamento del codice a matrice in OpenXR viene fornito tramite l'estensione XR_MSFT_scene_marker . Questa estensione consente di tenere traccia di più codici a matrice e può fornire dimensioni, posizione, timestamp dell'ultimo rilevamento, UUID e dati di codice a matrice memorizzati nel buffer per i codici a matrice rilevati.

Per abilitare il supporto del codice a matrice, è necessario abilitare le estensioni XR_MSFT_scene_marker e XR_MSFT_scene_understanding .

Per una procedura dettagliata, vedere la panoramica dell'estensione XR_MSFT_scene_marker nella specifica OpenXR 1.0.

Per un esempio di come usare i codici a matrice, vedere Scene_QRCode.cpp nell'esempio SceneUnderstandingUwp su GitHub.

Ricerca per categorie preparare una piattaforma UWP per l'uso di Microsoft.MixedReality.QR.QRCodeWatcher?

• Usare il pacchetto NuGet per decomprimere i file necessari.

• Aggiungere un riferimento a Microsoft.MixedReality.QR.winmd nel progetto e iniziare a usare l'API.

• Aggiungere le versioni di architettura corrette dei plug-in e usarle di conseguenza nella compilazione.

Ricerca per categorie preparare Unity con Microsoft.MixedReality.QR.QRCodeWatcher?

Usare NuGet per Unity e puntare al pacchetto NuGet precedente.

Come posso creare codici a matrice?

Consultare qualsiasi generatore di codice a matrice.

Se il rilevamento del codice a matrice non funziona in generale, cosa faccio?

• La versione del codice a matrice è una versione supportata? Non sono supportate le versioni ad alta densità, ad esempio la versione 40. Nulla sopra la versione 10 è garantito; Le versioni precedenti alla 20 non sono supportate.

• Sei abbastanza vicino al codice a matrice? Vedere distanza e posizione angolare dal codice a matrice.

• Com'è l'illuminazione? C'è un problema noto in cui il rilevamento diventa difficile quando il codice a matrice si trova in uno sfondo ambientale scuro: il codice a matrice apparirà lavato sulla fotocamera a causa di un contrasto elevato. Per altre informazioni, vedi Illuminazione e sfondo.

Qual è l'accuratezza?

Quando viene rilevato in un singolo fotogramma, la dimensione dovrebbe avere al massimo un errore del 1% rispetto alle dimensioni effettive. Un codice di 10 cm, ad esempio, potrebbe essere di dimensioni misurate fino a +/- 1 mm. Con il rilevamento continuo, la posizione di un codice potrebbe derivare da un massimo di +/- 2,5 mm. Una volta spostato dall'intervallo di rilevamento, la posizione di un rilevamento precedente è fino alla misericordia dell'errore della mappa.

Quanto è necessario chiudere il codice a matrice per rilevarlo?

La distanza dipende ovviamente dalle dimensioni del codice a matrice e anche dalla versione in cui si tratta. Per altre informazioni, vedere distanza e posizione angolare dal codice a matrice.

• In HoloLens 2, per un codice a matrice versione 1 che varia da 5 cm a 25 lati, la distanza di rilevamento minima è compresa tra 0,25 metri e 0,5 metri. Il più lontano da questi può essere rilevato da va da circa 0,5 m per il codice più piccolo a due metri per il più grande.

• In Windows Realtà mista queste distanze per le dimensioni vengono dimezzate.

• Per i codici più grandi, estrapolare la distanza di rilevamento per le dimensioni aumenta in modo lineare. Per qualsiasi codice più piccolo, il rilevamento non si verifica semplicemente:-4-5 cm è il più piccolo che è possibile rilevare.

Perché non è possibile leggere codici a matrice con logo?

I codici a matrice con logo non sono supportati.

Vengono rilevati i codici a matrice, quindi perché non si ricevono dati?

• Se la piattaforma non è in grado di decodificare il codice a matrice, non saranno presenti dati. È possibile usare il flusso e interpretare i dati usando codice open source.

• Alcune funzionalità, ad esempio l'aggiunta della struttura, non sono supportate.

Per altre informazioni, vedere quali versioni del codice a matrice sono supportate?.

I codici a matrice vengono salvati a livello di 'spazio' o app?

I codici a matrice vengono salvati a livello di sistema nella sessione del driver o nella sessione di avvio in HoloLens. Per altre informazioni, vedere Gestione dei dati del codice a matrice.

Come funziona con la piattaforma sottostante? Dove vengono mantenuti?

I codici a matrice rilevati vengono resi persistenti in memoria dal driver.

Ricerca per categorie eseguire il debug dell'app in Visual Studio quando viene visualizzato il messaggio di errore "Microsoft.MixedReality.QR.pdbnon trovato"?

Il caricamento dei simboli per Microsoft.MixedReality.QR.dll è stato ignorato perché non è specificato nell'elenco dei moduli inclusi.

Per riprodurre

Seguire la procedura per riprodurre questo comportamento:

1. Installare Microsoft.MixedReality.QR (NuGet) e MRTK
2. Provare a eseguire il debug

Dovrebbe essere possibile eseguire il debug dell'app con Microsoft.MixedReality.QR.dll, ma la DLL non viene trovata:

Soluzione consigliata

Stiamo lavorando per aggiungere simboli alla versione successiva. Nel frattempo, dovresti comunque essere in grado di eseguire il debug dell'app escludendo la DLL nelle opzioni di Visual Studio:

Per altre informazioni, vedere Configurazione delle impostazioni di Visual Studio.

Esiste un limite di quanti codici a matrice possono essere analizzati in una sessione?

È previsto un limite di 100 codici a matrice salvati a livello di sistema nel driver, entro 10 minuti.

Il processo di smoothing del codice a matrice è cambiato?

Il processo di smussamento del codice a matrice è cambiato dopo 20H2, dalla posa al liscio delle dimensioni. Per ripristinare il comportamento del processo di smoothing precedente, applicare un algoritmo di smoothing se i nuovi dati di posa del codice a matrice vengono rilevati entro 5 secondi o 10 cm del fotogramma rilevato in precedenza. I dati di trasformazione vengono mescolati tramite un rapporto ponderato del 90% del frame corrente con il 10% del frame precedente.

Vedi anche

• Rilevamento del codice a matrice con esempi C++ e C# nativi
• Sistemi di coordinate
• Ancoraggi nello spazio di Azure
• Panoramica della fotocamera Locatable di HoloLens 2