QR 码跟踪概述

项目
05/24/2024

访问 GitHub 存储库查看 QR 码示例：

借助 Windows 混合现实和 HoloLens 头戴显示设备，你的应用可以在头戴显示设备周围的环境中检测 QR 码，并在每个代码的实际位置建立一个坐标系。还可以在多个设备上在同一位置呈现全息影像，以打造共享体验。启用设备的网络摄像头后，你将能够识别最新版本的项目中的 QR 码。为获得进入生产阶段的最佳结果，建议你查看最佳做法部分。

本文介绍以下内容：

QR 代码跟踪支持的设备
支持的 QR 码版本
QR 码检测最佳做法
故障排除和常见问题解答

设备支持

产品	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 混合现实头戴显示设备进行 QR 码跟踪。使用 Microsoft.MixedReality.QRCodeWatcher.IsSupported() API 确定当前设备是否支持该功能。

支持的 QR 码版本

下表列出了支持的和不支持的 QR 码版本：

	QR 码版本
受支持：	QR 码版本 1 - 10 Micro QR 代码 M1-M4 所有编码
Not supported:	QR 码 10 - 20 （不受完全支持） QR 代码版本 21+ 调整模块，例如：圆形模块、反射、反转（黑色/白色）。徽标结构化追加

QR 码检测最佳做法

QR 码四周的安静区域

若要正确读取，QR 码要求代码四周有边距。此边距不能包含任何打印内容，并且应为四个模块（码中的单个黑色方块）宽度。

官方 QR 代码文档包含有关安静区域的详细信息。

照明和背景

QR 码检测质量容易受到不同的照明和背景的影响。

在正常照明条件下，为黑色/白色模块提供足够的对比度，以获得更好的性能。
在光线较亮或背景较暗的极端光照条件下，可以尝试降低和调整对比度，以提高 QR 码检测率。 QR 码内的白色背景可以从 255 减少。

QR 码的大小

Windows 混合现实和 HoloLens 设备不适用于小于 5 厘米的侧边的 QR 码。

对于边长范围介于 5 cm 到 10 cm 之间的 QR 码，设备必须非常靠近才能检测到此码。检测代码可能需要比平均值长。

检测到 QR 码的确切时间不仅取决于 QR 码的大小，还取决于你与 QR 码的距离。靠近 QR 码将有助于抵消 QR 码大小问题。

与 QR 码的距离和角度位置

跟踪相机只能检测到特定级别的详细信息。对于小代码（沿两侧小于 10 厘米），必须相当接近。对于宽度在 10 厘米到 25 厘米的版本 1 QR 码，最小检测距离范围为 0.15 米到 0.5 米。

大小的检测距离呈线性增加，但也取决于受支持 QR 版本或模块大小。版本越高，模块就越小，只能从更靠近的位置检测到。如果希望延长检测距离，也可以尝试使用微型 QR 码。 QR 检测适用于 +- 45 度的角度范围，以确保有适当的分辨率来检测该码。

其他检测注意事项：

不支持曲面上的 QR 码。
支持平面方向。平面外应不得超过 +-45 直视以获得更好的检测。
QR 码的物理大小应具有至少 2/3 像素的模块。注意：更高版本的 QR 码具有更小的模块。

有关实现最佳检测的 QR 码距离和大小之间的权衡关系，请参阅下图：

重要

请始终确保有足够的对比度和正确的边框。

管理 QR 码数据

Windows 混合现实和 HoloLens 设备在驱动程序的系统级别检测 QR 码。当重新启动设备或重新启动驱动程序时，将清除检测到的 QR 码历史记录。重新检测的 QR 码将视为新对象。

建议将应用配置为忽略特定时间戳之前的 QR 码，时间戳可在应用中指定。 QR 码 API 指定上次检测发生的时间。大多数应用开发人员会使用应用启动时的系统时间来确定检测到 QR 码的时间。

QR 码数据并非特定于应用。在应用启动后，会提供一个可用 QR 码列表。应用开发人员将确定哪些 QR 码与此应用相关。

QR 码在空间中的放置

有关在何处以及如何放置 QR 码的建议，请参阅 HoloLens 的环境注意事项。

故障排除和常见问题解答

需要哪些功能？

若要在 HoloLens 应用程序中启用 QR 码跟踪，请将网络摄像头功能添加到应用程序的清单中。如果要在 Unity 中开发，可以从播放器设置中配置此功能。

此外，用户可能会通过权限对话框提示授予应用网络摄像头权限。这仅在应用的生存期内发生一次。如果应用显式请求网络摄像头访问，对话框将不会重新出现。

对于具有 WebCam 功能的 Unity 应用，在 ARMarkerManager 场景中启用可能会触发网络摄像头权限对话框显示。

对于本机 OpenXR C++应用，对包含的 XR_SCENE_COMPUTE_FEATURE_MARKER_MSFT XrNewSceneComputeInfoMSFT::requestedFeatures 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 码。 OpenXR for Windows 混合现实（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 可跟踪项集合。
返回可跟踪 ID 指定的 QR 码数据的方法。

若要在应用中使用ARMarkerManager，需要导入混合现实 OpenXR 插件包。

导入包：

下载并运行混合现实功能工具。
安装 OpenXR 插件。

有关如何使用该工具的详细说明，请参阅欢迎使用混合现实功能工具。

接下来的一般过程是：

在 Unity 项目中，启用 WebCam 功能。
创建 prefab 并附加 ARMarker 组件，如下所示：
打开希望在运行时检测到 QR 码的场景。
附加到ARMarkerManager场景中的 GameObject，并将 Marker Prefab 设置为创建的 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 pack 将所需文件解压缩。
在项目中添加对 Microsoft.MixedReality.QR.winmd 的引用，并开始使用 API。
添加正确的插件体系结构版本，并在内部版本中相应地使用这些版本。

如何通过 MixedReality QRCodeWatcher 准备 Unity？

注意

下面特定于旧版 QR 代码 API。建议改用 OpenXR 实现进行 QR 码。

将 NuGet for Unity，并指向上述 NuGet pack。

如何制作 QR 码？

查看任何 QR 码生成器。

如果 QR 码跟踪通常不起作用，我该怎么办？

QR 码版本是否是受支持的版本？我们不支持高密度版本，如版本 40。高于版本 10 的版本不能保证受支持；高于 20 的版本不受支持。
离 QR 码是否足够近？请参阅与 QR 码的距离和角度位置。
照明情况如何？一个已知的问题是，当 QR 码处于较暗的环境背景时，检测会变得困难 - 由于高对比度，QR 码在相机面前会显得很模糊。有关详细信息，请参阅照明和背景。

准确性如何？

在单帧中检测时，预计大小与实际大小最多有 1% 的误差。例如，在测量到的大小上，一个 10 厘米的 QR 码可能会有最多 +/-1 毫米的误差。在连续检测下，码的位置可能会漂移最多 +/- 2.5 毫米。一旦移出检测范围，之前的检测位置将取决于映射误差。

我需要离 QR 码多近才能检测到它？

显然，距离取决于 QR 码的大小，以及它的版本。有关详细信息，请参阅与 QR 码的距离和角度位置。

在 HoloLens 2 上，对于边长在 5 厘米到 25 厘米的版本 1 QR 码，最小检测距离范围为 0.25 米到 0.5 米。可以检测到的最远距离是大约 0.5 米（最小的 QR 码）到 2 米（最大的 QR 码）。
在 Windows Mixed Reality 中，这些大小的距离将减半。
对于任何更大的 QR 码，可推断大小的检测距离呈线性增加。对于任何更小的 QR 码，根本不会进行检测，因为 4-5 厘米是我们可以检测的最小尺寸。

为什么我无法读取带有徽标的 QR 码？

不支持带有徽标的 QR 码。

已检测到 QR 码，但为什么我无法获取数据？

如果平台无法解码 QR 码，将不会向你提供数据。你可以使用流，并使用开源代码解释数据。
某些功能（如结构追加）不受支持。

有关详细信息，请参阅支持哪些 QR 码版本？

QR 码是保存在“空间”级别还是应用级别？

在驱动程序会话或 HoloLens 上的启动会话中，QR 码在系统级别保存。有关详细信息，请参阅管理 QR 码数据。

在基础平台中如何实现此操作？ 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 码版本