診斷與修復：內容不顯示

本篇針對 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 官方論壇或技術支持提供日誌文件、錄屏等進一步分析。