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 官方論壇或技術支援提供日誌檔案、錄屏等進一步分析。