QR 码跟踪概述

  • 项目

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

Unity 中的 QR 码跟踪

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

本文介绍以下内容：

设备支持

功能 HoloLens 第 1 代 HoloLens 2 沉浸式头戴显示设备
QR 码检测 ✔ ✔

注意

Windows 10 版本 2004 及更高版本支持在台式计算机上通过沉浸式 Windows Mixed Reality 头戴显示设备进行 QR 码跟踪。 使用 Microsoft.MixedReality.QRCodeWatcher.IsSupported() API 确定当前设备是否支持该功能。

支持的 QR 码版本

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

  QR 码版本
支持：
  • QR 版本 1-10
  • 微型 QR 码 M1-M4
  • 所有编码
Not supported:
  • QR 码 10 - 20（这些版本可能支持，但不能保证）
  • QR 码 20+
  • 调整模块，例如：圆形模块、反射、反转（黑色/白色）。
  • 徽标
  • 结构化追加

    QR 码检测最佳做法

    QR 码四周的安静区域

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

    QR 规范包含有关安静区域的详细信息。

    照明和背景

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

    • 在正常照明条件下，为黑色/白色模块提供足够的对比度，以获得更好的性能。

    • 在光线较亮或背景较暗的极端光照条件下，可以尝试降低和调整对比度，以提高 QR 码检测率。 QR 码内的白色背景可以从 255 减少。

    QR 码的大小

    Windows Mixed Reality 设备不能使用边长小于 5 厘米的 QR 码。

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

    检测到 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 code size distance chart

    重要

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

    管理 QR 码数据

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

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

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

    QR 码在空间中的放置

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

    故障排除和常见问题解答

    需要哪些功能？

    需要将网络摄像头功能添加到清单中（Unity 功能中的复选框）。 如果要构建为标准 UWP 项目，它也位于解决方案项目的 package.appxmanifest 中。

    通过调用以下函数来请求访问：

    #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 插件文件？

    可在此处找到所有必需的文件和文档。

    https://www.nuget.org/packages/Microsoft.MixedReality.QR

    如何准备 UWP 以使用 Microsoft.MixedReality.QR.QRCodeWatcher？

    • 使用 NuGet pack 将所需文件解压缩。

    • 在项目中添加对 Microsoft.MixedReality.QR.winmd 的引用，并开始使用 API。

    • 添加正确的插件体系结构版本，并在内部版本中相应地使用这些版本。

    如何通过 MixedReality QRCodeWatcher 准备 Unity？

    将 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 中调试应用？

    已跳过 Microsoft.MixedReality.QR.dll 的符号加载，因为未在包含的模块列表中指定它。

    重现步骤

    按照以下步骤重现此行为：

    1. 安装 Microsoft.MixedReality.QR (NuGet) 和 MRTK
    2. 尝试调试

    应能用 Microsoft.MixedReality.QR.dll 调试应用，但找不到此 DLL：

    Microsoft.MixedReality.QR.pdb not found error message

    我们正努力将符号添加到下一个版本。 同时，你应该仍然可以通过在 Visual Studio 选项中排除 DLL 来调试你的应用：

    excluding the DLL in Visual Studio options

    有关详细信息，请参阅配置 Visual Studio 的设置。

    关于在一次会话中可扫描的 QR 码数目，是否存在限制？

    在驱动程序中，10 分钟内最多可在系统级别保存 100 个 QR 码。

    QR 码平滑处理过程是否有变化？

    QR 码平滑处理过程在 20H2 之后有变化，从姿势平滑处理变成尺寸平滑处理。 若要将行为还原到之前的平滑处理过程，当在之前检测到的帧的 5 秒或 10 厘米内检测到新的 QR 码姿势数据时，会应用平滑算法。 转换数据按当前帧 90% 与之前的帧 10% 的加权比率进行混合。

    另请参阅