QR 代碼追蹤概觀

發行項
05/24/2024

若要存取 QR 代碼範例的 GitHub 存放庫：

使用 Windows Mixed Reality 和 HoloLens 頭戴式裝置，您的應用程式可以在頭戴式裝置周圍的環境中偵測 QR 代碼，並在每個程式代碼的實際位置建立座標系統。您也可以在多個裝置的相同位置轉譯全像投影，以建立共享體驗。啟用裝置的網路攝影機之後，您將會在最新版的項目中辨識 QR 代碼。如需進入生產環境的最佳結果，建議您檢閱最佳做法一節。

在此文章中，您將了解：

支援 QR 代碼追蹤的裝置
支援的 QR 代碼版本
QR 代碼偵測的最佳做法
疑難排解和常見問題集

裝置支援

Products	HoloLens (第 1 代)	HoloLens 2	沉浸式頭戴裝置
OpenXR		✔️ （搭配 OpenXR 運行時間版本 113 和 OpenXR XR_MSFT_scene_marker 擴充功能）
混合實境 Unity 外掛程式		✔️ （使用 OpenXR 執行時間版本 113 和混合實境 Unity 外掛程式 `ARMarkerManager`）
舊版 QR SDK	✔️	✔️	✔️

注意

以下是舊版 QR 代碼 API 特有的。建議改用 OpenXR 實作 QR 代碼。

Windows 10 版本 2004 和更新版本支援使用舊版 QR 代碼 SDK，在桌面電腦上搭配沉浸式 Windows Mixed Reality 頭戴式裝置進行 QR 代碼追蹤。 Microsoft.MixedReality.QRCodeWatcher.IsSupported()使用 API 來判斷目前裝置是否支援此功能。

支援的 QR 代碼版本

下表列出支援和不支援的 QR 代碼版本：

	QR 代碼版本
支援：	QR 代碼第 1 版 - 10 Micro QR 代碼 M1-M4 所有編碼
不受支援：	QR 代碼 10 - 20 （不支援） QR 代碼版本 21+ 調整的模組，例如：迴圈模組、反射、反轉（黑色/白色）。標誌結構化附加

QR 代碼偵測的最佳做法

QR 代碼周圍的安靜區域

若要正確讀取，QR 代碼需要程式代碼所有側邊的邊界。此邊界不得包含任何列印的內容，而且應該是四個模組（程序代碼中的單一黑色方塊）寬。

官方 QR 代碼檔包含有關無訊息區域的詳細資訊。

光源和底圖

QR 代碼偵測品質容易受到不同照明和背景的影響。

在正常光源條件下，為黑白模組提供足夠的對比，以提升效能。
在具有明亮光源或深色背景的極端光源條件下，您可以嘗試減少和調整對比，以改善 QR 代碼偵測率。 QR 代碼中的白色背景可以從 255 個向下減少。

QR 代碼的大小

Windows Mixed Reality 和 HoloLens 裝置無法搭配小於 5 公分的側邊使用 QR 代碼。

對於側邊範圍從 5 公分到 10 公分的 QR 代碼，裝置必須相當接近才能偵測到代碼。偵測程式代碼可能需要更長的時間。

偵測代碼的確切時間不只取決於 QR 代碼的大小，也取決於您與代碼相距多遠。更接近程式代碼有助於位移大小的問題。

QR 代碼的距離和角度位置

追蹤相機只能偵測特定層級的詳細數據。對於小型代碼（沿著兩側小於 10 釐米），您必須相當接近。對於 1 版 QR 代碼，大小從 10 公分到 25 公分不等，最小偵測距離介於 0.15 公尺和 0.5 公尺之間。

大小偵測距離會以線性方式增加，但也取決於支援的QR版本或模組大小。版本越高，模組越小，只能從較近的位置偵測到。如果您希望偵測距離更長，您也可以嘗試微 QR 代碼。 QR 偵測適用於一系列的角度 += 45 deg，以確保我們有適當的解析度來偵測程序代碼。

其他偵測考慮：

不支援弧形表面上的 QR 代碼。
支援平面內方向。飛機外應該 <= +-45 直視，以有更好的偵測。
QR 代碼的實體大小應該至少有 2/3 像素的模組。注意：較新版本的 QR 代碼會有較小的模組。

如需 QR 代碼距離與大小之間的取捨關聯性，以獲得最佳偵測，請參閱下圖：

重要

請務必確定您有足夠的對比和適當的框線。

管理 QR 代碼數據

Windows Mixed Reality 和 HoloLens 裝置會在驅動程式的系統層級偵測 QR 代碼。當裝置重新啟動或驅動程式重新啟動時，會清除偵測到的 QR 代碼歷程記錄。重新設定的 QR 代碼會被視為新物件。

建議您設定您的應用程式以忽略比特定時間戳還舊的 QR 代碼，這可以在應用程式內指定。 QR 代碼 API 會指定上次偵測發生的時間。大部分的應用程式開發人員都會使用應用程式啟動時的系統時間，以判斷偵測到 QR 代碼的時間。

QR 代碼數據並非應用程式專屬。應用程式啟動時，將會提供可用的 QR 代碼清單。應用程式開發人員會判斷與此應用程式相關的 QR 代碼。

在空間中放置 QR 代碼

如需如何放置 QR 代碼的建議，請參閱 HoloLens 的環境考慮。

疑難排解與常見問題

需要哪些功能？

若要在 HoloLens 應用程式中啟用 QR 代碼追蹤，請將網路攝影機功能新增至應用程式的指令清單。如果您要在 Unity 中開發，您可以從播放機設定進行此設定。

此外，使用者可能會收到 [許可權] 對話框提示，以授與您的應用程式網络攝影機許可權。這隻會在應用程式的存留期內發生一次。在應用程式明確要求網路攝影機存取的情況下，對話框將不會再次出現。

針對具有 WebCam 功能的 Unity 應用程式，在場景中啟用 ARMarkerManager 可能會觸發網路攝影機許可權對話框出現。

針對原生 OpenXR C++應用程式，使用包含 XrNewSceneComputeInfoMSFT::requestedFeatures XR_SCENE_COMPUTE_FEATURE_MARKER_MSFT 的初始呼叫 xrComputeNewSceneMSFT 可以觸發許可權對話框。

注意

以下是舊版 QR 代碼 API 特有的。建議改用 OpenXR 實作 QR 代碼。

您需要將網路攝影機功能新增至指令清單（Unity 功能中的複選框）。如果您要建置為標準 UWP 專案，它也會位於方案專案中的 package.appxmanifest 中。

在舊版 QR 代碼 SDK 中，呼叫下列方法來要求存取：

#if WINDOWS_UWP

async QRCodeWatcher.RequestAccessAsync();

#endif

存取狀態應該是 (status == QRCodeWatcherAccessStatus::Allowed)。

如果拒絕存取，則當您啟動時，此功能會傳回拒絕存取 QRTracking權。

在建構 QRCodeWatcher 物件之前，應該先呼叫此 API。

如果您是從 Unity 執行專案，您也必須確定您是從 UI 線程呼叫。否則，API 一律會傳回拒絕。如需詳細資訊，請參閱 Unity 手冊中的 AppCallbacks 類別。

如需設定 Unity 專案的詳細資訊，請參閱設定適用於 Windows Mixed Reality 的 Unity。

如何? 讓 QR 代碼追蹤功能在 HoloLens 2 裝置上運作？

QR 追蹤會在 HoloLens 2 上自動執行，而且您需要將「網路攝影機」功能新增至您的應用程式。

哪裡可以找到 API 外掛程式檔案？

應用程式應該使用 HoloLen 的 OpenXR 執行時間來偵測 QR 代碼。適用於 Windows Mixed Reality 的 OpenXR （113.2403.5001 或更新版本）在 HoloLens 裝置上提供 QR 代碼支援。

針對 Unity 應用程式，QR 代碼支援是透過 ARMarkerManager 混合實境 OpenXR 外掛程式所提供的元件來提供。

針對非 Unity 應用程式中的 QR 代碼支援，請使用 OpenXR XR_MSFT_scene_marker 延伸模組。

注意

以下是舊版 QR 代碼 API 特有的。建議改用 OpenXR 實作 QR 代碼。

您可以在 NuGet 上在這裡找到所有必要的檔案與檔案：

Microsoft.MixedReality.QR

如何? 準備 Unity 應用程式以使用 ARMarkerManager 來偵測 QR 代碼？

在 Unity 應用程式中， ARMarkerManager 元件可用來處理實體環境中 QR 代碼偵測在場景中的呈現方式。 ARMarkerManager 提供：

偵測到的 QR 代碼已新增至管理員、更新或移除時，通知訂閱者的事件。
偵測下 QR 代碼的 ARMarker 可追蹤集合。
傳回可追蹤標識碼所指定 QR 代碼資料的方法。

若要在應用程式中使用 ARMarkerManager ，您必須匯入混合實境 OpenXR 外掛程式套件。

若要匯入套件：

下載並執行混合實境功能工具。
安裝 OpenXR 外掛程式。

如需如何使用此工具的詳細指示，請參閱歡迎使用混合實境功能工具。

接下來的一般程式是：

在您的 Unity 專案中，啟用 WebCam 功能。
建立預製專案並附加 ARMarker 元件，如下所示：
開啟您想要在執行時偵測 QR 代碼的場景。
附加ARMarkerManager至場景中的 GameObject，並將 Marker Prefab 設定為您建立的預製專案。

如需更詳細的指示和資訊，請移至 Unity 中的 QR 代碼。

如需如何在 Unity 應用程式中使用 QR 代碼的範例，請參閱 GitHub 上的 QR 代碼範例案例。

如何? 準備非 Unity 應用程式，以使用 OpenXR 來偵測 QR 代碼？

OpenXR 中的 QR 代碼偵測是透過 XR_MSFT_scene_marker 延伸模組提供。此延伸模組允許追蹤多個 QR 代碼，並可針對偵測到的 QR 代碼提供大小、位置、上次偵測時間戳、UUID 和緩衝的 QR 代碼數據。

若要啟用 QR 代碼支援，必須啟用XR_MSFT_scene_marker和 XR_MSFT_scene_understanding 延伸模組。

如需詳細的逐步說明，請參閱 OpenXR 1.0 規格中的XR_MSFT_scene_marker 擴充功能概觀。

如需如何使用 QR 代碼的範例，請參閱 GitHub 上 SceneUnderstandingUwp 範例中的Scene_QRCode.cpp。

如何? 準備 UWP 以使用 Microsoft.MixedReality.QR.QRCodeWatcher？

注意

以下是舊版 QR 代碼 API 特有的。建議改用 OpenXR 實作 QR 代碼。

使用 NuGet 套件來解除封裝所需的檔案。
在專案中新增的 Microsoft.MixedReality.QR.winmd 參考，並開始使用 API。
新增正確的外掛程式架構版本，並據以在組建中使用它們。

如何? 使用 Microsoft.MixedReality.QR.QRCodeWatcher 準備 Unity？

注意

以下是舊版 QR 代碼 API 特有的。建議改用 OpenXR 實作 QR 代碼。

使用 NuGet for Unity 並指向上述 NuGet 套件。

如何製作 QR 代碼？

查看任何 QR 代碼產生器。

如果 QR 代碼追蹤一般無法運作，該怎麼辦？

QR 代碼版本是否為支援的版本？我們不支援高密度版本，例如版本 40。保證沒有高於第 10 版的專案;不支持超過 20 的版本。
您夠接近 QR 代碼嗎？請參閱 QR 代碼中的距離和角度位置。
光源如何？有一個已知問題，當 QR 代碼處於深色環境背景時，偵測變得很困難，因為高對比度，QR 代碼會出現在相機上。如需詳細資訊，請參閱光源和背景。

精確度為何？

在單一畫面格中偵測到時，大小最多會有實際大小的 1% 錯誤。例如，10 cm 程式代碼的測量大小可能高達 +/- 1 公厘。在連續偵測下，程序代碼的位置可能會漂移到最高 +/- 2.5 公厘。一旦您移出偵測範圍，先前偵測的位置就會由地圖錯誤的憐悯決定。

我需要接近 QR 代碼才能偵測到它？

距離顯然取決於 QR 代碼的大小，以及其版本。如需詳細資訊，請參閱 QR 代碼的距離和角度位置。

在 HoloLens 2 上，針對第 1 版 QR 代碼，從 5 公分側到 25 公分的最小偵測距離從 0.25 公尺到 0.5 公尺不等。從最小的程式代碼從大約0.5米到兩米的最小代碼，可以偵測到最遠的。
在 Windows Mixed Reality 上，這些大小的距離會減半。
對於較大的任何程序代碼，推斷-大小偵測距離會以線性方式增加。對於任何較小的程式代碼，偵測不會發生--4-5 cm 是我們可以偵測到的最小。

為什麼我無法讀取具有標誌的 QR 代碼？

不支援具有標誌的 QR 代碼。

偵測到 QR 代碼，所以我為什麼沒有收到任何數據？

如果平臺無法譯碼 QR 代碼，則不會有任何數據。您可以使用數據流，並使用開放原始碼來解譯數據。
不支援某些功能，例如結構附加。

如需詳細資訊，請參閱支援哪些 QR 代碼版本？。

QR 代碼是否儲存在「空間」層級或應用層級？

QR 代碼會儲存在驅動程式會話的系統層級，或 HoloLens 上的開機會話。如需詳細資訊，請參閱管理 QR 代碼數據。

這如何與基礎平臺搭配運作？他們會在何處保存？

驅動程式偵測到的 QR 代碼會保存在記憶體中。

當我收到「`Microsoft.MixedReality.QR.pdb`找不到」錯誤訊息時，如何? 在Visual Studio中偵錯應用程式？

注意

以下是舊版 QR 代碼 API 特有的。建議改用 OpenXR 實作 QR 代碼。

已略過的符號載入 Microsoft.MixedReality.QR.dll ，因為它未在包含的模組清單中指定。

若要重現

注意

以下是舊版 QR 代碼 API 特有的。建議改用 OpenXR 實作 QR 代碼。

請遵循下列步驟來重現此行為：

安裝 Microsoft.MixedReality.QR （NuGet）和 MRTK
嘗試偵錯

您應該使用 Microsoft.MixedReality.QR.dll 對應用程式進行偵錯，但找不到 DLL：

建議的解決方案

注意

以下是舊版 QR 代碼 API 特有的。建議改用 OpenXR 實作 QR 代碼。

我們正努力將符號新增至下一個版本。同時，您仍然可以在 Visual Studio 選項中排除 DLL，以偵錯您的應用程式：

如需詳細資訊，請參閱設定Visual Studio的設定。

會話中有多少 QR 代碼可以掃描的限制？

在 10 分鐘內，驅動程式的系統層級儲存了 100 個 QR 代碼的限制。

QR 代碼平滑處理程式是否已變更？

QR 代碼平滑處理程式在 20H2 之後變更，從姿勢平滑到大小平滑。若要將行為還原為先前的平滑處理程式，如果在先前偵測到框架的 5 秒或 10 公分內偵測到新的 QR 代碼姿勢數據，則會套用平滑演算法。轉換數據會透過目前畫面中 90% 的加權比例與上一個畫面格的 10% 混合。

共用方式為

QR 代碼追蹤概觀

裝置支援

支援的 QR 代碼版本