Table of Contents

Mega 定位失败排查指南

Mega 基于先进的视觉定位算法，通过云端 Mega Block 检索、视觉特征匹配解算实现高精度定位。因此实际使用过程中，因配置错误、环境变化或网络波动等多种原因，可能会导致定位失败。

本文档旨在帮助您快速判断定位状态，区分“正常等待”与“异常错误”，并根据配置、环境、服务三大类因素进行快速诊断。

定位流程

需要您在目标区域内采集建图数据并构建 Mega Block，将已经重建的 Mega Block 添加至定位库中，并确定定位库可用。

在已经构建 Mega Block 的覆盖的区域内，且环境光线良好、特征丰富，网络正常，通常数秒内即可定位成功。定位成功后会返回当前设备在 Mega Block 中的位置以及姿态。

判断定位状态

  • 若您使用 Mega Toolbox 验证定位结果，可以直接查看定位状态

    诊断信息

  • 若您是 Unity 开发者，出现无法定位时，可以在屏幕上查看定位返回的具体信息 MegaTrackerLocalizationStatus，如屏幕上没有该信息，需要打开诊断信息。

    诊断信息

MegaTrackerLocalizationStatus 可能的值

Constant Value Description
UnknownError 0 未知错误
Found 1 定位到 Block
NotFound 2 没有定位到 Block
RequestTimeout 3 请求超时(超过 1 分钟)
RequestIntervalTooLow 4 请求间隔过短
QpsLimitExceeded 5 QPS 超过限制
WakingUp 6 服务正在唤醒中
MissingSpotVersionId 7 缺少 SpotVersionId，可能是没有设置
ApiTokenExpired 8 API Token 过期

出现以上异常的解决办法：

  • 请求超时：查看并修复网络情况，如有必要可以调高请求超时时间 MegaRequestTimeParameters.Timeout，但网络情况不好也会对跟踪效果产生影响，因此需要尽量解决网络问题
  • 请求间隔过短：降低请求间隔
  • 连接或传输失败：查看并修复网络情况
  • QPS 超过限制：联系 EasyAR 商务同学，进行 QPS 扩容
  • 服务正在唤醒中：系统正在唤醒中，请等待一段时间再进行重试
  • 缺少 SpotVersionId：请配置 SpotVersionId
  • API Token 过期：请在 EasyAR 管理后台重新生成 API Token

UnknownError 常见有两种情况

  • 连接或传输失败
  • 服务返回异常

对于UnknownError，可以通过 MegaLocalizationResponse.ErrorMessage 获取详细信息

常见错误分类排查

根据定位返回的状态及现象，常见问题可分为以下三类：配置问题、环境因素、服务本身。

配置问题

此类问题通常发生在开发接入阶段，表现为服务完全无法启动。

License 相关

若您在开发或者测试过程中，日志或屏幕提示 License、 Invalid Key 等问题，可能原因：AppID/BundleID 不匹配、License 过期、套餐不符等，请对照下表检查您的 License 设置。

错误 解决方法
Invalid Key: No matched Bundle ID Bundle ID 与 license key 不匹配，请修改其中的任意一个，使其匹配
Invalid Key: No matched Package Name Bundle ID 与 license key 不匹配，请修改其中的任意一个，使其匹配
Invalid Key: License does not apply to current variant 使用了企业包的 SDK 但非企业版的 license key，或使用了非企业包的 SDk 但使用了企业包的 license key
Invalid Key: License for an old version does not apply license 版本太老，应重新创建新的license
Invalid Key: Invalid format license 格式错误，比如没有复制全
Invalid Key: Server verification failed license 已删除或无设备使用权限，如果是头显使用，请联系商务添加权限
License does not apply to eyewear license 不能在头显上使用，请更换 xr license
License is expired license 已过期

此外，您应当注意试用版本的 License 会有一些限制，使用付费版本的 EasyAR Sense 和付费的 EasyAR Mega 服务可以解决这个问题。如果您已经在使用付费版的 EasyAR Sense，可以忽略或直接从 sample 中删除相关文字。

相机画面异常

在开发或者测试 EasyAR Mega 应用的过程中，如出现黑屏、闪退、相机无画面等异常问题，请按照以下步骤系统排查和收集信息。

  1. 尝试自行解决

  • 如您使用 Unity 开发测试，请确保已经在 AR Session (EasyAR) -> Inspector 中勾选 Diagnostics Controller (Script) 开启诊断信息。

    诊断信息

  • 查看屏幕或者日志显示的内容，检查 UI 上是否有明确的文字提示。

  • 多数情况中，错误信息都有自说明，如果屏幕信息或日志已经说明了出错原因，可以根据具体原因去解决。如： cameraDevice.openWithPreferredType fail（需要检查相机是否可用）。

  • 如果提示“不支持”（如设备不支持 ARCore、或者其他特性），属于正常限制，无需进一步排查。

  1. 无法自行解决

    请先根据已有信息尝试自行解决，如果无法自行解决，为帮助 EasyAR 工作人员快速定位问题，请务必提供纤细、可复现的技术信息，切勿只描述如“黑屏”现象，建议反馈的内容包括：

  • 完整的日志：Unity 或者 Sense
  • 屏幕截图或者录屏：黑屏时的完整屏幕，如有诊断信息，请确保可见并截图。
  • 详细的设备信息：设备型号（如 iPhone 15、 HUAWEi P40）、系统版本（如 iOS 17.1、 Android 14）、EasyAR Sense 版本、EasyAR Sense Unity Plugin 版本、Unity 版本等。

不在现场运行，持续 NotFound

开发者在办公室使用模拟器或录屏测试，但始终无法定位。可能的原因是 MegaLocationInputMode 模式设置为 Onsite，但并非在现场运行。需要根据 Mega 位置输入模式，在开发过程中选择正确的模式：

Constant Value Description
Onsite 0 在现场使用的情况的输入模式，位置数据通常从设备获取并输入到Mega，通常由FrameFilter内部处理
Simulator 1 远程使用的情况的输入模式，位置数据需要模拟成现场数据并通过对应接口输入Mega（可选）
FramePlayer 2 在使用 FramePlayer 时的输入模式。这个模式是只读的

环境因素引起

此类问题表现为服务正常，但是定位持续返回 NotFound。

对着白墙、地面持续 NotFound

当相机画面中是大面积白墙、玻璃或纯色地面，状态会持续返回 NotFound。

原因：视觉定位依赖纹理特征。弱纹理区域无法提取特征点。

解决方法：这是正常现象，需要将相机移向有丰富纹理的区域进行启动。

在现场且纹理丰富，但持续 NotFound

人在现场，对着有纹理的区域，但长时间无法成功定位。

可能原因：

  • 场景变化：现场环境（如装修、海报更换、光照剧烈变化）与建图时的场景差异过大。
  • 采集未覆盖：用户站立的位置超出了当初采集建图的覆盖范围。

解决方法：

  • 移动到当初采集的路线区域尝试。
  • 若场景已发生永久性巨大变化，需要重新采集并更新 Block。

服务本身引起

刚添加 Block，持续 WakingUp

刚配置完定位库或者刚启动定位库的时候，服务状态显示 WakingUp 或长时间 NotFound。因为 Mega 服务具有冷启动机制，首次加载需要从冷存储唤醒。保持网络通畅，等待 10~30 秒重试即可。

服务返回异常

Https status Status code 原因
200 21 QPS 超出限制
200 1040 x 参数、库或者地图数据不正确，见具体消息描述
200 4000 x 算法级别报错，见具体描述
401 - 认证失败，见具体消息描述
404 - URL 中的路径输入不正确
50x - 服务器程序报错

出现服务异常的解决方法：

  • 出现 QPS 限制：联系 EasyAR 商务同学，进行 QPS 扩容
  • 出现认证失败：根据具体消息描述解决，常见问题有设备时间与标准时间偏差过大、API Key没有CLS权限等
  • 其他情况：请反馈给 EasyAR 工作人员解决

问题反馈

若经过上述排查仍无法解决问题，请按以下步骤收集信息并反馈给 EasyAR 技术支持团队。

导出 Mega 定位服务 信息

在 Unity 的 Mega Studio 中登录您的账号，选择您定位异常的定位库后，找到下图中的Mega 定位服务导出按钮。您导出的文件格式应当是MegaStudio_ServiceInfo_username_YY-MM-DD_HH-MM-SS.json。Mega 定位服务中仅包含 Mega Block 以及定位库信息，不包含其他敏感信息。

导出 Mega 定位服务信息

录制 EIF 文件

在使用在手机测试遇到问题，请使用Toolbox 录制手机 EIF 文件

在使用在眼镜测试遇到问题，请使用Toolbox 录制眼镜 EIF 文件

若您是在自己的应用中遇到问题，可以使用您的应用录制 EIF 文件

在使用微信小程序时，可以使用小程序录制 EIF 文件

使用手机、眼镜等设备录制问题现象

在 AR 领域，文字描述通常很难传达准确的信息，每个人的理解可能会天差地别。与此同时，运行时的屏幕录像是非常有用的信息，可以让您和 EasyAR 工作人员建立共同的理解。可以使用手机、眼镜等设备自带功能或者借助第三方软件进行录制。需要注意的是，在录屏过程中一般会对运行效果产生影响，跟踪效果和性能都可能会受到影响。

注意

录屏之前，建议在运行时参考对应的 Sample，将一些必要的 Debug 信息显示在屏幕上。在提供录屏的同时，您应当提供录屏期间对应的EIF数据。

Unity 开发问题反馈

如果您在使用 Unity 开发过程中，遇到了一些异常的问题，您应当逐个检查是否已经完成下面 4 项检查。

  1. 已经尝试过最新版本的 EasyAR Sense Unity Plugin，新版本中通常包含 bug 修复及新功能，建议先升级到最新版本尝试
  2. 已经阅读过 EasyAR 开发文档 及 Mega 指南，文档中通常会有一些情况说明
  3. 已经阅读过系统及 Unity 日志，建议在提问时提供完整日志
  4. 已经尝试过在空的 Unity 工程中，在 Sample 中复现问题

若已经完成上述 4 项检查，仍然无法解决您的问题，您可以在 EasyAR Sense Unity Plugin 按照下面流程提供完整的信息，以供 EasyAR 技术人员分析并解决您的问题。

  1. 在 Unity -> EasyAR -> Sense 中选择提问

    提问

  2. 在 提问中需要提供以下信息

    • 选择出问题的运行环境，只支持选择单个环境
    • 复制设备信息，在 EasyAR Session 中将 DiagnosticsController.DumpSession 设置为 Log，复制一帧的输出并填写结果到下方 dump session
    • 选择您出问题时所用的所有 EasyAR 功能，支持多选
    • 确定已经完成上述 4 项检查，建议在提问时描述如何在 Sample 中复现的问题
    • 点击右上角的复制功能 导出 Unity 开发信息 刚打开提问窗口，下方的信息显示不全，需要您在选择使用的环境和功能后才会显示。 选择环境和功能

  3. 点击下方的前往 EasyAR 问答 将复制的信息反馈给 EasyAR 官方，或者直接反馈给 EasyAR 工作人员 问题反馈