Udostępnij za pośrednictwem

Omówienie śledzenia kodu QR

  • Artykuł

Aby uzyskać dostęp do repozytorium GitHub dla przykładowego kodu QR:

Śledzenie kodu QR w a środowisku Unity

Dzięki zestawom słuchawkowym Windows Mixed Reality i HoloLens aplikacja może wykrywać kody QR w środowisku zestawu nagłownego, ustanawiając system współrzędnych w rzeczywistej lokalizacji każdego kodu. Można również renderować hologramy w tej samej lokalizacji na wielu urządzeniach, aby utworzyć środowisko udostępnione. Po włączeniu kamery internetowej urządzenia rozpoznasz kody QR w najnowszych wersjach projektów. Aby uzyskać najlepsze wyniki w środowisku produkcyjnym, zalecamy zapoznanie się z sekcją najlepszych rozwiązań .

Ten artykuł zawiera informacje dotyczące następujących zagadnień:

Obsługa urządzeń

Rezultat HoloLens 1. generacji HoloLens 2 Immersyjne zestawy nagłowne
OpenXR ✔️ (z rozszerzeniem XR_MSFT_scene_marker OpenXR Runtime w wersji 113 i OpenXR)
Wtyczka aparatu Unity rzeczywistości mieszanej ✔️ (z wtyczką ARMarkerManagerśrodowiska Uruchomieniowego OpenXR w wersji 113 i aparatu Unity rzeczywistości mieszanej)
Starszy zestaw QR SDK ✔️ ✔️ ✔️

Uwaga

Poniżej przedstawiono starsze interfejsy API kodu QR. Zalecamy użycie implementacji OpenXR dla kodów QR.

Korzystając ze starszego zestawu SDK kodu QR, śledzenie kodu QR z immersywnymi zestawami słuchawkowymi Windows Mixed Reality na komputerach stacjonarnych jest obsługiwane w systemie Windows 10 w wersji 2004 lub nowszej. Użyj interfejsu Microsoft.MixedReality.QRCodeWatcher.IsSupported() API, aby określić, czy funkcja jest obsługiwana na bieżącym urządzeniu.

Obsługiwane wersje kodu QR

W poniższej tabeli wymieniono obsługiwane i nieobsługiwane wersje kodu QR:

  Wersje kodu QR
Obsługiwane:
  • Kod QR w wersji 1–10
  • Mikro kody QR M1-M4
  • Wszystkie kodowanie
Nieobsługiwane:
  • Kody QR 10–20 (nie są w pełni obsługiwane)
  • Kody QR w wersji 21+
  • Poprawione moduły, na przykład: moduły cykliczne, odbicia, odwrócone (czarne/białe).
  • Logo
  • Dołączanie ustrukturyzowane

    Najlepsze rozwiązania dotyczące wykrywania kodu QR

    Ciche strefy wokół kodów QR

    Aby kod QR był poprawnie odczytywany, wymagają marginesu wokół wszystkich stron kodu. Ten margines nie może zawierać żadnej drukowanej zawartości i powinien mieć cztery moduły (pojedynczy czarny kwadrat w kodzie).

    Oficjalna dokumentacja kodu QR zawiera więcej informacji na temat stref cichych.

    Oświetlenie i tło

    Jakość wykrywania kodu QR jest podatna na różne oświetlenie i tło.

    • W normalnych warunkach oświetleniowych zapewniają wystarczający kontrast dla czarnych/białych modułów w celu uzyskania lepszej wydajności.

    • W ekstremalnych warunkach oświetleniowych z jasnym oświetleniem lub ciemnym tle można spróbować zmniejszyć i dostosować kontrast, co może poprawić szybkość wykrywania kodu QR. Białe tło w kodzie QR można zmniejszyć z 255 w dół.

    Rozmiar kodów QR

    Urządzenia Windows Mixed Reality i HoloLens nie działają z kodami QR o bokach mniejszych niż 5 cm.

    W przypadku kodów QR z bokami od 5 cm do 10 cm urządzenie musi być dość blisko, aby wykryć kod. Wykrywanie kodu może trwać dłużej niż średnio.

    Dokładny czas wykrywania kodów zależy nie tylko od rozmiaru kodów QR, ale także od tego, jak daleko jesteś od kodu. Przejście bliżej kodu pomoże zrównoważyć problemy z rozmiarem.

    Odległość i położenie kątowe z kodu QR

    Kamery śledzące mogą wykrywać tylko określony poziom szczegółowości. W przypadku małych kodów (mniej niż 10 cm wzdłuż boków) należy być dość blisko. W przypadku kodu QR w wersji 1 różni się od 10 cm do 25 cm rozmiaru, minimalna odległość wykrywania wynosi od 0,15 metra do 0,5 metra.

    Odległość wykrywania rozmiaru zwiększa się liniowo, ale zależy również od obsługiwanej wersji QR lub rozmiaru modułu. Im wyższa wersja, tym mniejsze moduły, które można wykryć tylko z bliżej pozycji. Możesz również wypróbować kody mikro-QR, jeśli chcesz, aby odległość wykrywania mogła być dłuższa. Wykrywanie QR działa z zakresem kątów += 45 stopni, aby upewnić się, że mamy odpowiednie rozwiązanie do wykrywania kodu.

    Inne zagadnienia dotyczące wykrywania:

    • Kody QR na zakrzywionych powierzchniach nie są obsługiwane.
    • Orientacja w płaszczyźnie jest obsługiwana. Poza płaszczyzną powinien być <= +-45 patrząc prosto, aby lepiej wykryć.
    • Fizyczny rozmiar kodu QR powinien mieć moduły o rozmiarze co najmniej 2/3 pikseli. Uwaga: Wyższe wersje kodów QR będą miały mniejsze moduły.

    Aby uzyskać relację kompromisu między odległością i rozmiarem kodu QR w celu optymalnego wykrywania, zobacz następujący wykres:

    Wykres odległości rozmiaru kodu QR

    Ważne

    Zawsze upewnij się, że masz wystarczający kontrast i odpowiednie obramowanie.

    Zarządzanie danymi kodu QR

    Urządzenia Windows Mixed Reality i HoloLens wykrywają kody QR na poziomie systemu w sterowniku. Po ponownym uruchomieniu urządzenia lub ponownym uruchomieniu sterownika wykryta historia kodów QR zostanie wyczyszczone. Kody QR ponownie wykrywane są traktowane jako nowe obiekty.

    Zalecamy skonfigurowanie aplikacji w celu ignorowania kodów QR starszych niż określony znacznik czasu, który można określić w aplikacji. Interfejs API kodu QR określa czas ostatniego wykrycia. Większość deweloperów aplikacji będzie używać czasu systemowego, gdy aplikacja zostanie uruchomiona, aby określić czas wykrycia kodu QR.

    Dane kodu QR nie są specyficzne dla aplikacji. Po uruchomieniu aplikacji będzie dostępna lista dostępnych kodów QR. Deweloper aplikacji określi, które kody QR są istotne dla tej aplikacji.

    Umieszczanie kodu QR w przestrzeni

    Aby uzyskać zalecenia dotyczące miejsca i sposobu umieszczania kodów QR, zapoznaj się z zagadnieniami dotyczącymi środowiska dla urządzenia HoloLens.

    Rozwiązywanie problemów i często zadawane pytania

    Jakie możliwości są potrzebne?

    Aby włączyć śledzenie kodu QR w aplikacji HoloLens, dodaj możliwość kamery internetowej do manifestu aplikacji. Jeśli programujesz w środowisku Unity, możesz to skonfigurować za pomocą ustawień odtwarzacza.

    Ponadto użytkownicy mogą być monitowani przez okno dialogowe uprawnień w celu udzielenia uprawnień kamery internetowej aplikacji. Dzieje się tak tylko raz w okresie istnienia aplikacji. W takich przypadkach, jak aplikacja jawnie żąda dostępu do kamery internetowej, okno dialogowe nie pojawi się ponownie.

    W przypadku aplikacji aparatu Unity z funkcją WebCam włączenie ARMarkerManager w scenie może spowodować wyświetlenie okna dialogowego uprawnień kamery internetowej.

    W przypadku natywnych aplikacji OpenXR C++ początkowe wywołania xrComputeNewSceneMSFT zawierające XrNewSceneComputeInfoMSFT::requestedFeatures XR_SCENE_COMPUTE_FEATURE_MARKER_MSFT mogą wyzwolić okno dialogowe uprawnień.

    Uwaga

    Poniżej przedstawiono starsze interfejsy API kodu QR. Zalecamy użycie implementacji OpenXR dla kodów QR.

    Potrzebna będzie możliwość kamery internetowej dodana do manifestu (pole wyboru w obszarze Możliwości aparatu Unity). Jeśli tworzysz jako standardowy projekt platformy UWP, znajduje się on również w pliku package.appxmanifest w projekcie rozwiązania.

    W starszym zestawie SDK kodu QR zażądaj dostępu, wywołując następującą metodę:

    #if WINDOWS_UWP

async QRCodeWatcher.RequestAccessAsync();

#endif

    Stan dostępu powinien mieć wartość (status == QRCodeWatcherAccessStatus::Allowed).

    Jeśli dostęp zostanie odrzucony, funkcja zwróci odmowę dostępu po uruchomieniu QRTracking.

    Ten interfejs API powinien być wywoływany przed utworzeniem QRCodeWatcher obiektu.

    Jeśli uruchamiasz projekt z poziomu aparatu Unity, musisz również upewnić się, że wywołujesz wywołanie z wątku interfejsu użytkownika. W przeciwnym razie interfejs API zawsze zwróci odmowę. Aby uzyskać więcej informacji, zobacz AppCallbacks, klasa w podręczniku aparatu Unity.

    Aby uzyskać więcej informacji na temat konfigurowania projektu dla aparatu Unity, zobacz konfigurowanie aparatu Unity dla środowiska Windows Mixed Reality.

    Jak mogę sprawić, że funkcja śledzenia kodu QR działa na urządzeniach HoloLens 2?

    Śledzenie QR jest automatyczne na urządzeniu HoloLens 2 i będziesz potrzebować możliwości "kamery internetowej" dodanej do aplikacji.

    Gdzie można znaleźć pliki wtyczki interfejsu API?

    Aplikacje powinny używać środowiska uruchomieniowego OpenXR urządzenia HoloLen do wykrywania kodów QR. Program OpenXR for Windows Mixed Reality (113.2403.5001 lub nowszy) zapewnia obsługę kodu QR na urządzeniach HoloLens.

    W przypadku aplikacji Unity obsługa kodu QR jest dostarczana za pośrednictwem składnika dostarczanego ARMarkerManager z wtyczką Mixed Reality OpenXR.

    Aby uzyskać obsługę kodu QR w aplikacjach innych niż Unity, użyj rozszerzenia openXR XR_MSFT_scene_marker .

    Uwaga

    Poniżej przedstawiono starsze interfejsy API kodu QR. Zalecamy użycie implementacji OpenXR dla kodów QR.

    Wszystkie wymagane pliki i dokumentacja można znaleźć tutaj w witrynie NuGet tutaj:

    Microsoft.MixedReality.QR

    Jak mogę przygotować aplikację aparatu Unity do wykrywania kodów QR przy użyciu narzędzia ARMarkerManager?

    W aplikacjach ARMarkerManager aparatu Unity składnik służy do obsługi sposobu, w jaki wykrywanie kodu QR w środowisku fizycznym jest reprezentowane w scenie. ARMarkerManager Zapewnia:

    • Zdarzenia powiadamiania subskrybentów o dodaniu wykrytego kodu QR do menedżera, zaktualizowania lub usunięcia.

    • Kolekcja ARMarker elementów śledzenia kodów QR w ramach wykrywania.

    • Metody zwracające dane kodów QR określone przez identyfikator możliwy do śledzenia.

    Aby korzystać z ARMarkerManager aplikacji, należy zaimportować pakiet wtyczki OpenXR rzeczywistości mieszanej.

    Aby zaimportować pakiet:

    1. Pobierz i uruchom narzędzie funkcji rzeczywistości mieszanej.
    2. Zainstaluj wtyczkę OpenXR.

    Aby uzyskać szczegółowe instrukcje dotyczące korzystania z narzędzia, zobacz Welcome to the Mixed Reality Feature Tool (Witamy w narzędziu funkcji rzeczywistości mieszanej).

    Poniżej przedstawiono ogólną procedurę:

    1. W projekcie aparatu Unity włącz funkcje WebCam .
    2. Utwórz prefab i dołącz ARMarker składnik, jak pokazano poniżej:
      Skonfigurowano prefab
    3. Otwórz scenę, w której podczas uruchamiania mają być wykrywane kody QR.
    4. Dołącz ARMarkerManager do obiektu GameObject w scenie i ustaw prefab znacznika na utworzony prefab .
      Określony prefab

    Aby uzyskać bardziej szczegółowe instrukcje i informacje, przejdź do pozycji Kody QR w aucie Unity.

    Przykład użycia kodów QR w aplikacji aparatu Unity można znaleźć w przykładowym scenariuszu kodu QR w witrynie GitHub.

    Jak mogę przygotować aplikację inną niż Unity do wykrywania kodów QR za pomocą biblioteki OpenXR?

    Wykrywanie kodu QR w programie OpenXR jest udostępniane za pośrednictwem rozszerzenia XR_MSFT_scene_marker . To rozszerzenie umożliwia śledzenie wielu kodów QR i może zapewnić rozmiar, położenie, znacznik czasu ostatniego wykrywania, identyfikator UUID i buforowane dane kodu QR dla wykrytych kodów QR.

    Aby włączyć obsługę kodu QR, należy włączyć zarówno rozszerzenia XR_MSFT_scene_marker, jak i XR_MSFT_scene_understanding .

    Aby uzyskać szczegółowy opis krok po kroku, zobacz omówienie rozszerzenia XR_MSFT_scene_marker w specyfikacji OpenXR 1.0.

    Aby zapoznać się z przykładem używania kodów QR, zobacz Scene_QRCode.cpp w przykładzie SceneUnderstandingUwp w witrynie GitHub.

    Jak mogę przygotować platformę UWP do korzystania z microsoft.MixedReality.QR.QRCodeWatcher?

    Uwaga

    Poniżej przedstawiono starsze interfejsy API kodu QR. Zalecamy użycie implementacji OpenXR dla kodów QR.

    • Użyj pakietu NuGet, aby rozpakować wymagane pliki.

    • Dodaj odwołanie do elementu Microsoft.MixedReality.QR.winmd w projekcie i zacznij korzystać z interfejsu API.

    • Dodaj poprawne wersje architektury wtyczek i użyj ich odpowiednio w kompilacji.

    Jak mogę przygotować aparat Unity za pomocą microsoft.MixedReality.QR.QRCodeWatcher?

    Uwaga

    Poniżej przedstawiono starsze interfejsy API kodu QR. Zalecamy użycie implementacji OpenXR dla kodów QR.

    Użyj narzędzia NuGet dla aparatu Unity i wskaż powyższy pakiet NuGet.

    Jak mogę tworzyć kody QR?

    Zapoznaj się z dowolnym generatorem kodu QR.

    Jeśli śledzenie kodu QR nie działa ogólnie, co zrobić?

    • Czy wersja kodu QR jest obsługiwaną wersją? Nie obsługujemy wersji o wysokiej gęstości, takich jak wersja 40. Niczego powyżej wersji 10 nie ma gwarancji; wersje powyżej 20 nie są obsługiwane.

    • Czy jesteś wystarczająco blisko kodu QR? Zobacz odległość i położenie kątowe z kodu QR.

    • Jak jest oświetlenie? Istnieje znany problem polegający na tym, że wykrywanie staje się trudne, gdy kod QR znajduje się na ciemnym tle środowiska — kod QR pojawi się wymyty do aparatu z powodu dużego kontrastu. Aby uzyskać więcej informacji, zobacz oświetlenie i tło.

    Jaka jest dokładność?

    W przypadku wykrycia w jednej ramce rozmiar powinien mieć co najwyżej 1% błędu z rzeczywistego rozmiaru. Na przykład kod o rozmiarze 10 cm może wynosić do +/- 1 mm w mierzonym rozmiarze. W przypadku ciągłego wykrywania pozycja kodu może dryfować do +/- 2,5 mm. Po przeniesieniu z zakresu wykrywania pozycja poprzedniego wykrywania jest aż do łasek błędu mapy.

    Jak blisko powinienem być kod QR, aby go wykryć?

    Odległość zależy oczywiście od rozmiaru kodu QR, a także od jego wersji. Aby uzyskać więcej informacji, zobacz odległość i położenie kątowe z kodu QR.

    • Na holoLens 2, dla wersji 1 kod QR różni się od 5 cm boków do 25 cm boków, minimalna odległość wykrywania waha się od 0,25 metrów do 0,5 metra. Najdalej można je wykryć z około 0,5 m dla najmniejszego kodu do dwóch metrów dla większego.

    • W środowisku Windows Mixed Reality te odległości dla rozmiarów są o połowę mniejsze.

    • W przypadku kodów większych, ekstrapolacji — odległość wykrywania rozmiaru zwiększa się liniowo. W przypadku mniejszego kodu wykrywanie po prostu nie wystąpi--4-5 cm jest najmniejsze, które możemy wykryć.

    Dlaczego nie mogę odczytać kodów QR z logo?

    Kody QR z logo nie są obsługiwane.

    Wykryto kody QR, więc dlaczego nie otrzymuję żadnych danych?

    • Jeśli platforma nie może dekodować kodu QR, nie będzie żadnych danych. Możesz użyć strumienia i interpretować dane przy użyciu kodu open source.

    • Niektóre funkcje, takie jak dołączanie struktury, nie są obsługiwane.

    Aby uzyskać więcej informacji, zobacz obsługiwane wersje kodu QR?

    Czy kody QR są zapisywane na poziomie "spacji" lub aplikacji?

    Kody QR są zapisywane na poziomie systemu w sesji sterownika lub sesji rozruchu na urządzeniu HoloLens. Aby uzyskać więcej informacji, zobacz Zarządzanie danymi kodu QR.

    Jak to działa z podstawową platformą? Gdzie się utrzymują?

    Wykryte kody QR są utrwalane w pamięci przez sterownik.

    Jak mogę debugować aplikację w programie Visual Studio po wyświetleniu komunikatu o błędzie "Microsoft.MixedReality.QR.pdbNie znaleziono"?

    Uwaga

    Poniżej przedstawiono starsze interfejsy API kodu QR. Zalecamy użycie implementacji OpenXR dla kodów QR.

    Ładowanie symboli dla Microsoft.MixedReality.QR.dll elementu zostało pominięte, ponieważ nie jest określone na liście dołączonych modułów.

    Aby odtworzyć

    Uwaga

    Poniżej przedstawiono starsze interfejsy API kodu QR. Zalecamy użycie implementacji OpenXR dla kodów QR.

    Wykonaj kroki, aby odtworzyć to zachowanie:

    1. Instalowanie plików Microsoft.MixedReality.QR (NuGet) i MRTK
    2. Spróbuj debugować

    Powinno być możliwe debugowanie aplikacji przy użyciu Microsoft.MixedReality.QR.dll, ale nie można odnaleźć biblioteki DLL:

    Nie znaleziono komunikatu o błędzie Microsoft.MixedReality.QR.pdb

    Uwaga

    Poniżej przedstawiono starsze interfejsy API kodu QR. Zalecamy użycie implementacji OpenXR dla kodów QR.

    Pracujemy nad dodaniem symboli do następnej wersji. W międzyczasie nadal powinno być możliwe debugowanie aplikacji przez wykluczenie biblioteki DLL w opcjach programu Visual Studio:

    wykluczanie biblioteki DLL w opcjach programu Visual Studio

    Aby uzyskać więcej informacji, zobacz Konfigurowanie ustawień programu Visual Studio.

    Czy istnieje limit liczby kodów QR, które można skanować w sesji?

    Istnieje limit 100 kodów QR zapisanych na poziomie systemu w sterowniku w ciągu 10 minut.

    Czy proces wygładzenia kodu QR został zmieniony?

    Proces wygładzenia kodu QR zmienił się po 20H2, od pozy smoothing po wygładzenie rozmiaru. Aby przywrócić zachowanie poprzedniego procesu wygładzania, należy zastosować algorytm wygładzania, jeśli nowy kod QR pozuje dane w ciągu 5 sekund lub 10 cm od wcześniej wykrytej ramki. Dane przekształcenia są łączone za pomocą ważonego współczynnika 90% bieżącej ramki z 10% poprzedniej ramki.

    Zobacz też