Table of Contents

诊断与修复：应用中内容不显示的问题

“我能看到真实世界，但虚拟内容没有出现。” 这是 AR 开发中最常见的问题之一。这个问题可能源于多个环节，从 Mega 定位本身到您的渲染逻辑都有可能。

本篇将引导您系统地排查和解决这个问题。

排查流程：从外部到内部

遵循“先外部，后内部”的原则，可以高效地定位问题。请按顺序执行以下步骤：

步骤一：使用外部工具验证 Mega 定位状态 (无需修改代码)

在深入您的应用代码之前，首先确认 Mega 定位服务本身是否正常工作。这是最关键的一步，可以帮您判断问题是出在 Mega 定位本身还是渲染等应用开发集成问题。

  1. 使用 Mega Toolbox (手机端)

    • 在您的测试手机上安装 Mega Toolbox App (如果尚未安装)。
    • 打开 App，进入“现场定位测试”或类似功能。
    • 登录您的账号并选择与您应用相同的定位库。
    • 将手机带到您应用测试时无法显示内容的相同位置。
    • 观察结果：
      • 如果 Toolbox 定位成功（界面上状态显示 Found）：恭喜！ Mega 定位服务是正常的。问题出在您的应用内部，特别是渲染和内容显示逻辑上。请跳转到 步骤二。
      • 如果 Toolbox 定位失败（界面上状态显示 NotFound 或其他）：问题出在定位服务本身。请参考 下一节 进行深入分析。

  2. 使用 PC 端模拟运行 (如果已采集 EIF)

    • 如果您已经为该场景录制了 EIF 数据，可在 PC 端的 Unity 编辑器中使用 session 验证工具回放该数据。
    • 观察结果：
      • 如果回放时定位成功（界面上状态显示 Found）：问题出在您的应用代码或设备特定环境上。
      • 如果回放时定位失败（界面上状态显示 NotFound 或其他）：问题出在定位服务本身。请参考 下一节 进行深入分析。

步骤二：检查应用内部的渲染与内容逻辑

如果步骤一确认 Mega 定位服务本身是正常的，那么问题就出在您的应用代码中。请检查以下几点：

  1. 内容是否摆在正确的节点之下：

    • 您是否正确将 3D 物体摆放在工具自动生成的 MegaBlocks > Block_* 节点之下？
    • 检查内容与 Block 节点的层级关系，以确保在运行时虚拟内容的渲染位置是正确的。

  2. MegaTracker 的 Block Root 是否正确设置：

    • 展开 AR Session，检查 Mega Tracker 中的 Block Root 是否为工具生成的 MegaBlocks 节点。

  3. MegaBlocks 节点是否有改动：

    • 确保没有修改 Block_* 节点的名字，且没有修改 local transform 属性中的任何数值。

  4. 事件监听是否正确：

    • 您是否修改过 MegaTracker 的定位回调处理逻辑？
    • 您的代码是否在定位状态成功事件触发后，才执行了实例化或显示虚拟内容的操作？

  5. 头显渲染与透明度：

    • 您的虚拟物体是否被其他物体遮挡？检查渲染队列和 Shader。
    • 如果使用了 VST (视频透视) 设备，检查您的渲染是否被正确地叠加在了视频流之上。
    • 如果使用了 OST (光透视) 设备，检查内容是否因为环境光过强而看不清。

  6. 内容本身的问题：

    • 您实例化的预制体（Prefab）本身是否有问题？例如，模型文件丢失、Shader 错误、缩放为 0 等。尝试在场景中手动放置一个相同的物体，看它是否能正常显示。

常见定位失败原因分析与改善建议

如果在 步骤一 中发现 Mega Toolbox 也无法定位，那么需仔细查看并解决定位问题。以下是常见原因和对策：

  • 原因一：地图与环境不匹配
    现场环境与采集建图时相比已经发生了巨大变化，或者体验的区域在采集时未能覆盖，或地图本身就是错误的。
    改善建议：

    • 确保您定位库中加载的地图与当前物理空间在场景上是一致的。
    • 如果环境已改造（如装修、更换陈列），需要重新采集和生成地图。
    • 如果采集建图时未覆盖发生问题的区域，需要通过补充更新的方式重新生成地图。

  • 原因二：初始化环境不佳
    在纹理稀少的区域（如纯色墙壁、对着地面）启动应用。
    改善建议：

    • 引导用户在纹理丰富的区域启动应用，以帮助系统快速完成初始定位。
    • 在应用 UI 中给出明确的提示，如“抬起手机环视左右”。

  • 原因三：网络或服务问题
    网络延时导致定位服务请求超时，或者定位服务本身出现了故障、或超出了并发使用上限等。对于后者请及时与我们反馈。

  • 原因四：到达算法能力边界
    Mega 定位基于先进的计算机视觉、AI 等算法，但其并不是万能的，存在一定的算法能力边界。当在某些场景或点位出现定位持续失败时，可通过录屏、录制 EIF 数据等方式与我们进行反馈，帮助我们持续改进和迭代算法。

另外，需要特别说明的是，Mega 定位需要一个过程，通常在 1-2 秒左右。考虑到现实场景的复杂性如网络拥堵、高并发、手机发热降频等情形，该时间可能会更久。因此，在应用中可以设计一个清晰的加载/等待界面，告知用户“正在定位中...”，避免用户因等待而误以为服务挂了或定位不到。

注意
  • 首次定位通常比后续定位慢，因为系统在初次定位成功后需要加载相应的内容。这是正常现象。
  • 快速移动设备会可能导致定位丢失。请引导用户平稳移动设备。

总结与最佳实践

  • 始终使用外部工具先行验证：这能最快地将问题范围缩小到“定位”或“渲染”。
  • 建立合理的用户预期：通过 UI 提示，让用户知道定位需要时间，并引导他们到合适的环境。
  • 关注内容逻辑：确保您的内容绑定等设置正确。
  • 善用日志：在关键节点（如事件触发、姿态获取、响应状态）打印日志，可以帮助您快速定位代码逻辑问题。

通过以上系统性的排查，您应该能够解决绝大多数“内容不显示”的问题。如果问题依然存在，请准备好 EIF 数据和日志，通过 问题报告 的方式向我们提交详细报告。