Sdílet prostřednictvím

Přehled sledování kódu QR

  • Článek

Přístup k úložišti GitHub pro ukázku kódu QR:

Sledování kódu QR v Unity

Díky náhlavním soupravám Windows Mixed Reality a HoloLens dokáže vaše aplikace detekovat kódy QR v prostředí kolem náhlavní soupravy a vytvořit souřadnicový systém v reálném světě každého kódu. Hologramy můžete také vykreslit na stejném místě na více zařízeních a vytvořit tak sdílené prostředí. Jakmile povolíte webovou kameru zařízení, rozpoznáte kódy QR v nejnovějších verzích projektů. Pro dosažení nejlepších výsledků v produkčním prostředí doporučujeme projít si část s osvědčenými postupy .

V tomto článku najdete následující informace:

Podpora zařízení

Produkt HoloLens 1. generace HoloLens 2 Imerzivní náhlavní soupravy
OpenXR ✔️ (s rozšířením OpenXR Runtime verze 113 a OpenXR XR_MSFT_scene_marker )
Modul plug-in Mixed Reality Unity ✔️ (s modulem runtime OpenXR verze 113 a modulem plug-in ARMarkerManagerMixed Reality Unity )
Starší sada QR SDK ✔️ ✔️ ✔️

Poznámka:

Toto je specifické pro starší rozhraní API kódu QR. Doporučujeme místo toho použít implementaci OpenXR pro kódy QR.

Použití starší sady SDK kódu QR podporuje sledování kódu QR s imerzivními náhlavními soupravami Windows Mixed Reality na stolních počítačích ve Windows 10 verze 2004 a novějších. Microsoft.MixedReality.QRCodeWatcher.IsSupported() Pomocí rozhraní API určete, jestli je funkce na aktuálním zařízení podporovaná.

Podporované verze kódu QR

Následující tabulka uvádí podporované a nepodporované verze kódu QR:

  Verze kódu QR
Podporováno:
  • Kód QR verze 1 – 10
  • Mikro QR kódy M1-M4
  • Všechna kódování
Není podporováno:
  • Kódy QR 10 – 20 (plně podporované)
  • Kódy QR verze 21 a novější
  • Vylepšené moduly, například: kruhové moduly, odrazy, invertované (černobílé).
  • Loga
  • Strukturované připojení

    Osvědčené postupy pro detekci kódu QR

    Tiché zóny kolem kódů QR

    Aby bylo možné kódy QR správně číst, vyžadují kolem všech stran kódu okraj. Tento okraj nesmí obsahovat žádný tištěný obsah a měl by být čtyři moduly (jeden černý čtverec v kódu).

    Oficiální dokumentace ke kódu QR obsahuje další informace o tichých zónách.

    Osvětlení a pozadí

    Kvalita detekce kódu QR je náchylná k různým osvětlením a pozadím.

    • Za normálních světelných podmínek zajistěte dostatečný kontrast pro černobílé moduly pro lepší výkon.

    • V extrémních světelných podmínkách s jasným osvětlením nebo tmavým pozadím se můžete pokusit snížit a upravit kontrast, což může zlepšit rychlost detekce kódu QR. Bílé pozadí kódu QR lze snížit z 255 dolů.

    Velikost kódů QR

    Zařízení s Windows Mixed Reality a HoloLens nefungují s kódy QR s stranami menšími než 5 cm.

    Pro kódy QR s stranami v rozsahu od 5 cm do 10 cm musí být zařízení poměrně blízko ke zjištění kódu. Zjištění kódu může trvat déle než průměr.

    Přesný čas detekce kódů závisí nejen na velikosti kódů QR, ale také na tom, jak daleko od kódu jste. Pokud se přesunete blíž ke kódu, pomůže vám to odsazení problémů s velikostí.

    Vzdálenost a úhlová pozice od kódu QR

    Sledovací kamery mohou detekovat pouze určitou úroveň podrobností. Pro malé kódy (méně než 10 cm podél stran) musíte být poměrně blízko. Pro kód QR verze 1 se liší od 10 cm do 25 cm, minimální vzdálenost detekce je mezi 0,15 metrů a 0,5 metrů.

    Vzdálenost detekce pro velikost se zvětšuje lineárně, ale také závisí na podporované verzi QR nebo velikosti modulu. Čím vyšší je verze, tím menší moduly, které lze zjistit pouze z bližší pozice. Kódy micro-QR můžete vyzkoušet také v případě, že chcete, aby vzdálenost detekce byla delší. Detekce QR funguje s rozsahem úhlů += 45 stupňů, abychom zajistili správné rozlišení pro detekci kódu.

    Další aspekty detekce:

    • Kódy QR na zakřivených plochách se nepodporují.
    • Podporuje se orientace v rovině. Z roviny by mělo být <= +-45, které by mělo mít lepší detekci.
    • Fyzická velikost kódu QR by měla mít moduly nejméně 2/3 pixely. Poznámka: Vyšší verze kódů QR budou mít menší moduly.

    Vztah kompromisu mezi vzdáleností a velikostí kódu QR pro optimální detekci najdete v následujícím grafu:

    Graf vzdálenosti velikosti kódu QR

    Důležité

    Vždy se ujistěte, že máte dostatečný kontrast a správné ohraničení.

    Správa dat kódu QR

    Zařízení Windows Mixed Reality a HoloLens detekují kódy QR na úrovni systému v ovladači. Po restartování zařízení nebo restartování ovladače se vymaže historie zjištěných kódů QR. Kódy QR jsou znovu označeny jako nové objekty.

    Doporučujeme nakonfigurovat aplikaci tak, aby ignorovala kódy QR starší než konkrétní časové razítko, které je možné zadat v aplikaci. Rozhraní API kódu QR určuje čas posledního zjištění. Většina vývojářů aplikací použije systémový čas při spuštění aplikace k určení času zjištění kódu QR.

    Data kódu QR nejsou specifická pro konkrétní aplikaci. Po spuštění aplikace bude k dispozici seznam dostupných kódů QR. Vývojář aplikace určí, které kódy QR jsou pro tuto aplikaci relevantní.

    Umístění kódu QR v prostoru

    Doporučení týkající se toho, kde a jak umístit kódy QR, najdete v tématu Aspekty prostředí pro HoloLens.

    Řešení potíží a nejčastější dotazy

    Jaké možnosti jsou potřeba?

    Pokud chcete povolit sledování kódu QR v aplikaci HoloLens, přidejte do manifestu aplikace funkci webové kamery. Pokud vyvíjíte v Unity, můžete ho nakonfigurovat z nastavení přehrávače.

    Kromě toho se uživatelům může zobrazit výzva v dialogovém okně oprávnění k udělení oprávnění webové kamery vaší aplikace. K tomu dochází jenom jednou po celou dobu života aplikace. V případech, jako je například aplikace, která explicitně žádá o přístup k webové kameře, se dialogové okno znovu nezobrazí.

    U aplikací Unity s funkcí WebCam může povolení ARMarkerManager ve scéně aktivovat dialogové okno oprávnění webové kamery.

    V případě nativních aplikací OpenXR C++ můžou počáteční volání xrComputeNewSceneMSFT s obsahem XrNewSceneComputeInfoMSFT::requestedFeatures XR_SCENE_COMPUTE_FEATURE_MARKER_MSFT aktivovat dialogové okno oprávnění.

    Poznámka:

    Toto je specifické pro starší rozhraní API kódu QR. Doporučujeme místo toho použít implementaci OpenXR pro kódy QR.

    Budete potřebovat funkci webové kamery přidanou do manifestu (zaškrtávací políčko v možnostech Unity). Pokud vytváříte jako standardní projekt UPW, je to také v souboru package.appxmanifest v projektu řešení.

    Ve starší verzi sady SDK kódu QR požádejte o přístup voláním následující metody:

    #if WINDOWS_UWP

async QRCodeWatcher.RequestAccessAsync();

#endif

    Stav přístupu by měl být (status == QRCodeWatcherAccessStatus::Allowed).

    Pokud je přístup odepřen, funkce vrátí přístup odepřen při spuštění QRTracking.

    Toto rozhraní API by se mělo volat před vytvořením objektu QRCodeWatcher .

    Pokud projekt spouštíte z Unity, musíte také zajistit, že voláte z vlákna uživatelského rozhraní. V opačném případě se rozhraní API vždy vrátí zamítnuto. Další informace naleznete v tématu AppCallbacks třída v Unity Manual.

    Další informace o nastavení projektu pro Unity najdete v tématu Konfigurace Unity pro Windows Mixed Reality.

    Návody, aby funkce sledování kódu QR fungovala na zařízeních HoloLens 2?

    Sledování QR je na HoloLensu 2 automatické a budete potřebovat funkci "webcam" přidanou do vaší aplikace.

    Kde najdu soubory modulu plug-in api?

    Aplikace by měly k detekci kódů QR používat modul runtime OpenXR HoloLen. OpenXR pro Windows Mixed Reality (113.2403.5001 nebo novější) poskytuje podporu kódu QR na zařízeních HoloLens.

    Pro aplikace Unity je podpora kódu QR poskytována prostřednictvím ARMarkerManager komponenty poskytované modulem plug-in Mixed Reality OpenXR.

    Pro podporu kódu QR v jiných aplikacích než Unity použijte rozšíření OpenXR XR_MSFT_scene_marker .

    Poznámka:

    Toto je specifické pro starší rozhraní API kódu QR. Doporučujeme místo toho použít implementaci OpenXR pro kódy QR.

    Všechny požadované soubory a dokumentaci najdete tady na NuGetu:

    Microsoft.MixedReality.QR

    Návody připravit aplikaci Unity, aby k detekci kódů QR používala ARMarkerManager?

    V aplikacích Unity se komponenta ARMarkerManager používá ke zpracování způsobu rozpoznávání kódu QR ve fyzickém prostředí ve scéně. ARMarkerManager poskytuje:

    • Události pro upozorňování odběratelů, když byl zjištěný kód QR přidán do manažera, aktualizován nebo odebrán.

    • Kolekce ARMarker sledovatelných kódů QR v rámci detekce.

    • Metody vracející data pro kódy QR podle specifikace trackable ID.

    Pokud chcete aplikaci používat ARMarkerManager , musíte importovat balíček modulu plug-in Mixed Reality OpenXR.

    Import balíčku:

    1. Stáhněte a spusťte nástroj pro funkci hybridní reality.
    2. Nainstalujte modul plug-in OpenXR.

    Podrobné pokyny k používání nástroje najdete v tématu Vítá vás nástroj funkcí hybridní reality.

    Obecný postup je následující:

    1. V projektu Unity povolte funkce WebCam .
    2. Vytvořte předfab a připojte komponentu ARMarker , jak je znázorněno níže:
      Předfab nakonfigurované
    3. Otevřete scénu, ve které chcete zjistit kódy QR při spuštění.
    4. Připojte ARMarkerManager se k objektu GameObject ve vaší scéně a nastavte prefab značky na předfab, který jste vytvořili.
      Zadaný prefab

    Podrobnější pokyny a informace najdete v Unity na kódy QR.

    Příklad použití kódů QR v aplikaci Unity najdete v ukázkovém scénáři kódu QR na GitHubu.

    Návody připravit aplikaci, která není Unity, aby k detekci kódů QR používala OpenXR?

    Detekce kódu QR v OpenXR je poskytována prostřednictvím rozšíření XR_MSFT_scene_marker . Toto rozšíření umožňuje sledovat více kódů QR a může poskytovat velikost, pozici, časové razítko poslední detekce, UUID a data kódu QR ve vyrovnávací paměti pro zjištěné kódy QR.

    Pokud chcete povolit podporu kódu QR, musí být povolená rozšíření XR_MSFT_scene_marker i XR_MSFT_scene_understanding .

    Podrobný postup najdete v přehledu rozšíření XR_MSFT_scene_marker ve specifikaci OpenXR 1.0.

    Příklad použití kódů QR najdete v tématu Scene_QRCode.cpp v ukázce SceneUnderstandingUwp na GitHubu.

    Návody připravit UPW na používání Microsoft.MixedReality.QR.QRCodeWatcher?

    Poznámka:

    Toto je specifické pro starší rozhraní API kódu QR. Doporučujeme místo toho použít implementaci OpenXR pro kódy QR.

    • Pomocí balíčku NuGet rozbalte požadované soubory.

    • Přidejte odkaz na Microsoft.MixedReality.QR.winmd projekt a začněte používat rozhraní API.

    • Přidejte správné verze architektury modulů plug-in a odpovídajícím způsobem je používejte v sestavení.

    Návody připravit Unity pomocí Microsoft.MixedReality.QR.QRCodeWatcher?

    Poznámka:

    Toto je specifické pro starší rozhraní API kódu QR. Doporučujeme místo toho použít implementaci OpenXR pro kódy QR.

    Použijte NuGet pro Unity a přejděte na výše uvedený balíček NuGet.

    Jak můžu vytvářet kódy QR?

    Podívejte se na libovolný generátor kódu QR.

    Pokud sledování kódu QR obecně nefunguje, co mám dělat?

    • Je verze kódu QR podporovanou verzí? Nepodporujeme verze s vysokou hustotou, jako je verze 40. Nic nad verzí 10 není zaručeno; verze vyšší než 20 se nepodporují.

    • Jste dost blízko kódu QR? Zobrazte vzdálenost a úhlovou pozici od kódu QR.

    • Jak je osvětlení? Existuje známý problém, kdy je detekce obtížná, když je kód QR na tmavém pozadí prostředí – kód QR se zobrazí vymytí fotoaparátu z důvodu vysokého kontrastu. Další informace najdete v tématu osvětlení a pozadí.

    Jaká je přesnost?

    Při zjištění v jednom rámečku se očekává, že velikost bude mít maximálně 1% chybu ze skutečné velikosti. Například kód o velikosti 10 cm může být v naměřené velikosti až +/- 1 mm. Při nepřetržitém zjišťování se pozice kódu může pohybovat až o +/- 2,5 mm. Jakmile se přesunete z rozsahu detekce, pozice předchozí detekce je až do slitování chyby mapy.

    Jak blízko musím být kódEM QR, abych ho rozpoznal?

    Vzdálenost samozřejmě závisí na velikosti kódu QR a také na tom, jakou verzi má. Další informace naleznete ve vzdálenosti a úhlové poloze z kódu QR.

    • Na HoloLensu 2 se pro kód QR verze 1 lišící od stran 5 cm až po 25 cm, minimální vzdálenost detekce se pohybuje od 0,25 do 0,5 metrů. Nejužší je možné zjistit od 0,5 m pro nejmenší kód na dva metry pro větší.

    • Ve Windows Mixed Reality jsou tyto vzdálenosti velikostí poloviční.

    • U jakýchkoli větších kódů extrapolujte – vzdálenost detekce pro velikost se lineárně zvyšuje. U jakéhokoli menšího kódu se detekce prostě nenastane --4-5 cm je nejmenší, co můžeme zjistit.

    Proč nemůžu číst kódy QR s logy?

    Kódy QR s logy se nepodporují.

    Zjistí se kódy QR, takže proč nedostávám žádná data?

    • Pokud platforma kód QR nedokáže dekódovat, nebudou k dispozici žádná data. Stream můžete použít a interpretovat data pomocí opensourcového kódu.

    • Některé funkce, jako je připojení struktury, se nepodporují.

    Další informace najdete v podporovaných verzích kódu QR?

    Ukládají se kódy QR na úrovni prostoru nebo na úrovni aplikace?

    Kódy QR se ukládají na úrovni systému v relaci ovladače nebo spouštěcí relace na HoloLensu. Další informace najdete v tématu správa dat kódu QR.

    Jak to funguje se základní platformou? Kde se zachovají?

    Zjištěné kódy QR zůstávají v paměti ovladačem.

    Návody ladit aplikaci v sadě Visual Studio, když se zobrazí chybová zpráva NenalezenaMicrosoft.MixedReality.QR.pdb?

    Poznámka:

    Toto je specifické pro starší rozhraní API kódu QR. Doporučujeme místo toho použít implementaci OpenXR pro kódy QR.

    Načítání symbolů pro Microsoft.MixedReality.QR.dll bylo vynecháno, protože není zadané v seznamu zahrnutých modulů.

    Reprodukování

    Poznámka:

    Toto je specifické pro starší rozhraní API kódu QR. Doporučujeme místo toho použít implementaci OpenXR pro kódy QR.

    Postupujte podle kroků pro reprodukci tohoto chování:

    1. Instalace Microsoft.MixedReality.QR (NuGet) a MRTK
    2. Pokuste se ladit

    Aplikaci byste měli být schopni ladit pomocí Microsoft.MixedReality.QR.dll, ale knihovna DLL se nenašla:

    Microsoft.MixedReality.QR.pdb nebyla nalezena chybová zpráva

    Poznámka:

    Toto je specifické pro starší rozhraní API kódu QR. Doporučujeme místo toho použít implementaci OpenXR pro kódy QR.

    Pracujeme na přidávání symbolů do příští verze. Mezitím byste měli být schopni ladit aplikaci vyloučením knihovny DLL v možnostech sady Visual Studio:

    vyloučení knihovny DLL v možnostech sady Visual Studio

    Další informace najdete v tématu Konfigurace nastavení sady Visual Studio.

    Existuje limit počtu kódů QR, které je možné v relaci naskenovat?

    Do 10 minut je limit 100 kódů QR uložených na úrovni systému v ovladači.

    Změnil se proces vyhlazování kódu QR?

    Proces vyhlazování kódu QR se po 20H2 změnil z pozice vyhlazování až po vyhlazování velikosti. Pokud se chcete vrátit k předchozímu procesu vyhlazování, použili byste algoritmus vyhlazování, pokud se nová data kódu QR zjistí během 5 sekund nebo 10 cm od dříve zjištěného rámce. Transformovaná data se prolínají pomocí váženého poměru 90 % aktuálního rámce s 10 % předchozího rámce.

    Viz také