诊断与修复：内容不显示

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

常见原因与排查方法

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

物体识别失败

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

• 检查模型质量：确保 3D 模型及物体符合 模型准备 中的文件格式、纹理几何等要求。
• 检查目标物体：确保目标物体的表面没有反光或镜面材质。
• 查看日志：检查应用日志，检查目标模型是否成功加载。

改善建议：

• 优化模型：确保纹理足够丰富，几何结构没有孔洞。
• 检查逻辑：确保应用已经正确加载目标模型。如遇加载失败，参考 目标加载失败 章节进行检查和修复。

功能实现错误

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

• Unity
• 原生

排查方法：

• 检查 ObjectTarget 配置：
  • 根据 Source 类型检查其是否指向 StreamingAssets 文件夹中的正确文件。
  • Scale 是否根据实际物体的尺寸进行了修改（如根据模型文件计算得到的 BoundingBox 尺寸数值是 10 x 10 x 30，而物体的实际尺寸是 0.1m x 0.1m x 0.3m，则 Scale 应当设置为 0.01）。
• 确认预制体层级：
  • 虚拟内容必须与目标 3D 模型同级，且都属于 ObjectTarget 的子节点。虚拟内容不能被禁用。
  • 目标 3D 模型的 Rotation 属性需要将 Y 方向设为 180。
  • 虚拟内容的摆放需完全围绕目标 3D 模型的位置进行。

改善建议：

• 重置配置：删除并重新创建场景中的 ObjectTarget，按规范拖入预制体并绑定 3D 模型。
• 检查日志：搜索 ObjectTargetController 相关错误，如 fail to load target data。

权限问题

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

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

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

改善建议：

• 使用正式版的 License。

虚拟内容问题

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

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

改善建议：

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

总结与最佳实践

内容不显示问题通常由物体3D 模型、程序实现、权限或内容本身引起。建议按顺序排查：

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

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