图像追踪示例

此示例演示了如何检测和增强真实世界中的图像目标。

有关自定义可追踪对象更新和 Unreal Engine 的 AR Trackable Notify 组件的基本信息，请参阅 Unreal Engine 文档，要使用此功能，需要在 OpenXR 插件设置中启用，路径为：Project Settings > Snapdragon Spaces 插件。

示例工作原理

默认情况下，当示例运行并识别到图像时，会在物理目标上生成一个小工具。当前示例仅能识别一个图像，并在地图中包含的 UI 面板上显示该图像的世界位置。

图像 AR

BP_ImageTrackingManager 蓝图资产（位于 SnapdragonSpacesSamples Content > SnapdragonSpaces > Samples > ImageTracking > Placeable）负责通过事件系统创建和销毁 BP_Gizmo_AugmentedImage 参与者，它将来自 AR Trackable Notify 组件的事件绑定起来，以响应 AR 可追踪图像的变化，当系统检测到图像时，会触发 On Add/Update/Remove Tracked Image 事件。在示例蓝图中，如果要启动检测，需将 Toggle AR Capture 设置为 ON；如果要停止检测并销毁所有生成的 AR 图像，则将其设置为 OFF，也可以使用 Toggle Spaces Feature 作为启用该功能的替代方法。此外，必须将 Scene Understanding 设置为该节点的捕捉类型。

图像 AR 会话配置

系统使用 D_SpacesSessionConfig_ImageTracking 资产（位于 SnapdragonSpacesSamples Content > SnapdragonSpaces > Samples > ImageTracking > Core）来检测图像。该资产是从 SpacesSessionConfig 类派生的数据资产。

会话配置文件提供了三个字段：一个用于定义图像的大小，一个用于指定应跟踪的最大同时图像数量，另一个用于引用候选图像进行跟踪。

图像跟踪器的创建是在异步线程中进行的，以避免在跟踪图像数量非常多时出现冻结问题。因此，图像跟踪有时可能会出现启动延迟。请监听 On Spaces Image Tracking Is Ready 委托，以了解图像何时准备好进行跟踪。

AR 候选图像

Unreal Engine 使用名为 AR Candidate Image（https://dev.epicgames.com/documentation/en-us/unreal-engine/BlueprintAPI/ARSettings/AddCandidateImage?application_version=4.27） 的专用资产类型来创建 XR 系统需要跟踪的图像引用，开发者可以添加任意数量的 AR Candidate Images，并将它们分配到 AR Session Config 中指定的数组。

要创建 AR Candidate Image，首先需要将要跟踪的图像导入为纹理资产到 Content 文件夹中。创建的纹理资产应在压缩设置中选择 UserInterface2D (RGBA)，并建议关闭 mip maps。

接下来需要创建 AR Candidate Image 资产，其中 Candidate Texture 字段需要引用已创建的纹理资产，每个 AR Candidate Image 应该有一个唯一的标识符，可以在 Friendly Name 字段中设置，如果在同一个 AR Session Config 中使用了相同的名称，将会导致哈希码冲突。

最后一步是通过宽度/高度字段定义图像的物理尺寸（以厘米为单位），准确的尺寸对于正确的姿态估计和后续的增强显示非常重要。这些数据会根据图像的比例和 Orientation 字段中定义的方向自动填充，不幸的是，Unreal Engine 当前的方向设置是颠倒的，因此开发者需要将 Portrait 设置为用于横向图像，将 Landscape 设置为用于纵向图像。

如果 AR Candidate Image 资产的父级是 Spaces AR Candidate Image，Snapdragon Spaces 插件提供了几种不同的跟踪模式供选择：

● 动态模式：每帧更新跟踪图像的位置，适用于移动和静态目标。如果无法找到跟踪图像，则不会报告位置或姿态。默认使用此模式。

● 自适应模式：周期性地更新静态图像的位置（大约每 5 帧更新一次），当图像稍微移动时进行更新。这在静态图像的功耗和准确性之间找到平衡。

● 静态模式：适用于已知为静态的图像，在此模式下，图像在首次检测时会固定位置，之后不会更新，这可以减少功耗并提高性能，但如果图像发生漂移，位置将不会更新。

跟踪模式可以在应用程序运行时通过以下节点更改，而无需停止或重启 AR 会话：

● 按友好名称设置图像目标跟踪模式（Set Image Target Tracking Mode by Friendly Name）

● 按候选图像设置图像目标跟踪模式（Set Image Target Tracking Mode by Candidate Image）

● 按友好名称设置图像目标跟踪模式（Set Image Targets Tracking Mode by Friendly Name）

● 按候选图像设置图像目标跟踪模式（Set Image Targets Tracking Mode by Candidate Image）

SetImageTrackedModeByID 已在 0.15.0 版本中弃用。

示例使用了 D_SpacesARCandidateImage_SpaceTown 蓝图资产（位于 SnapdragonSpacesSamples Content > SnapdragonSpaces > Samples > ImageTracking > Placeable）。该图像目标在打印成 DIN A4 或 US letter 尺寸时，高度为 26 厘米。BP_Gizmo_AugmentedImage 蓝图资产（位于 SnapdragonSpacesSamples Content > SnapdragonSpaces > Samples > ImageTracking > Placeable）在物理图像目标上渲染一个 gizmo，指示其在识别和跟踪后的方向。