診斷與修復：內容不顯示

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