Table of Contents

诊断与修复：内容不显示

本篇针对平面图像跟踪中虚拟内容无法显示的常见问题，提供系统性排查方法和改善建议，帮助开发者快速定位并解决问题。

常见原因与排查方法

内容不显示通常涉及图像识别、功能实现错误或权限限制。以下是主要原因及排查步骤：

图像识别失败

现象：摄像头对准目标图像后，虚拟内容完全不出现。
排查方法：

  • 检查图像识别度：使用 目标图检测工具 上传图像，确认识别度评分（需达到 4~5 星）。
  • 验证图像质量：确保图像符合 最佳实践 中的纹理、尺寸和比例要求。
  • 检查目标图像实体：确保目标图像的实体（如海报、卡片）的表面没有反光，保持平整没有折叠。
  • 查看日志：检查应用日志，搜索 TargetLoad 事件，确认目标图像是否成功加载。

改善建议：

  • 优化图像：增加对比度、避免重复图案、确保主体占画面70%以上。
  • 替换图像：若优化图像后问题依然存在，换用官方 Sample 中的测试图（如 namecard.jpg）验证问题是否出在图像本身。
  • 确保实体：目标实体应尽量使用哑光或比较粗糙的表面，保持表面平整没有折叠、弯曲。
  • 检查逻辑：确保应用已经正确加载了测试所用的目标图像。

功能实现错误

现象：图像已识别，但虚拟内容未显示或位置异常。

排查方法：

  • 检查 ImageTarget 配置：
    • 根据 Source 类型检查其是否指向 StreamingAssets 文件夹中的正确文件。
    • Scale 是否设置为实际物理尺寸。
  • 确认预制体层级：虚拟内容（如Cube）必须是 ImageTarget 的子节点，且未被禁用。

改善建议：

  • 重置配置：删除并重新创建场景中的 ImageTarget，按规范拖入预制体并绑定图像。
  • 简化测试：暂时移除自定义脚本，仅保留基础 Cube，确认最小可运行场景。
  • 检查日志：搜索 ImageTargetController 相关错误，如 fail to load target data。

权限问题

现象：原本使用正常，但运行一段时间后内容消失。
排查方法：
确认您是否属于以下情形之一：

  • 在 XR 头显上使用
  • 使用了自定义相机
  • 在手机上使用 AR Engine/ARFoundation

如果是上述其中一种情形，那么您可能正在使用试用版的 License。

改善建议：

  • 使用正式版的 License。

虚拟内容问题

现象：内容原本显示正常，但当相机离目标物体很近/很远时看不到内容。
排查方法：

  • 检查近裁远裁设置：确保您在渲染虚拟内容时的近裁远裁设置在合理范围内。
  • 检查内容模型尺寸：当内容模型过大时，接近目标物体可能导致穿模从而看不到内容；当内容模型过小时，远离目标物体可能导致显示太小而看不清内容。

改善建议：

  • 设置合适的近裁远裁。
  • 虚拟内容相比目标图像实体的物理尺寸是大小合适的。

总结与最佳实践

内容不显示问题通常由图像、程序实现、权限或内容本身引起。建议按顺序排查：

  1. 检查 License 是否为正式版；
  2. 检查虚拟内容本身是否恰当；
  3. 验证目标图像质量；
  4. 确认程序实现或开发配置是否存在问题。

若问题持续，可通过 EasyAR 官方论坛或技术支持提供日志文件、录屏等进一步分析。