Table of Contents

診斷與修復：應用中內容不顯示的問題

「我能看到真實世界，但虛擬內容沒有出現。」 這是 AR 開發中最常見的問題之一。這個問題可能源於多個環節，從 Mega 定位本身到您的渲染邏輯都有可能。

本篇將引導您系統地排查和解決這個問題。

排查流程：從外部到內部

遵循「先外部，後內部」的原則，可以高效地定位問題。請按順序執行以下步驟：

步驟一：使用外部工具驗證 Mega 定位狀態 (無需修改代碼)

在深入您的應用代碼之前，首先確認 Mega 定位服務本身是否正常工作。這是最關鍵的一步，可以幫您判斷問題是出在 Mega 定位本身還是渲染等應用開發集成問題。

  1. 使用 Mega Toolbox (手機端)

    • 在您的測試手機上安裝 Mega Toolbox App (如果尚未安裝)。
    • 打開 App，進入現場驗證與診斷工具。
    • 登錄您的賬號並選擇與您應用相同的定位庫。
    • 將手機帶到您應用測試時無法顯示內容的相同位置。
    • 觀察結果：
      • 如果 Toolbox 定位成功（界面上狀態顯示 Found）：恭喜！ Mega 定位服務是正常的。問題出在您的應用內部，特別是渲染和內容顯示邏輯上。請跳轉到 步驟二。
      • 如果 Toolbox 定位失敗（界面上狀態顯示 NotFound 或其他）：問題出在定位服務本身。請參考 下一節 進行深入分析。

  2. 使用 PC 端模擬運行 (如果已採集 EIF)

    • 如果您已經為該場景錄製了 EIF 數據，可在 PC 端的 Unity 編輯器中使用 session 驗證工具回放該數據。
    • 觀察結果：
      • 如果回放時定位成功（界面上狀態顯示 Found）：問題出在您的應用代碼或設備特定環境上。
      • 如果回放時定位失敗（界面上狀態顯示 NotFound 或其他）：問題出在定位服務本身。請參考 下一節 進行深入分析。

步驟二：檢查應用內部的渲染與內容邏輯

如果步驟一確認 Mega 定位服務本身是正常的，那麼問題就出在您的應用代碼中。請檢查以下幾點：

  1. 內容是否擺在正確的節點之下：

    • 您是否正確將 3D 物體擺放在工具自動生成的 MegaBlocks > Block_* 節點之下？
    • 檢查內容與 Block 節點的層級關係，以確保在運行時虛擬內容的渲染位置是正確的。

  2. MegaTracker 的 Block Root 是否正確設置：

    • 展開 AR Session，檢查 Mega Tracker 中的 Block Root 是否為工具生成的 MegaBlocks 節點。

  3. MegaBlocks 節點是否有改動：

    • 確保沒有修改 Block_* 節點的名字，且沒有修改 local transform 屬性中的任何數值。

  4. 事件監聽是否正確：

    • 您是否修改過 MegaTracker 的定位回調處理邏輯？
    • 您的代碼是否在定位狀態成功事件觸發後，才執行了實例化或顯示虛擬內容的操作？

  5. 頭顯渲染與透明度：

    • 您的虛擬物體是否被其他物體遮擋？檢查渲染隊列和 Shader。
    • 如果使用了 VST (視頻透視) 設備，檢查您的渲染是否被正確地疊加在了視頻流之上。
    • 如果使用了 OST (光透視) 設備，檢查內容是否因為環境光過強而看不清。

  6. 內容本身的問題：

    • 您實例化的預製體（Prefab）本身是否有問題？例如，模型文件丟失、Shader 錯誤、縮放為 0 等。嘗試在場景中手動放置一個相同的物體，看它是否能正常顯示。

常見定位失敗原因分析與改善建議

如果在 步驟一 中發現 Mega Toolbox 也無法定位，那麼需仔細查看並解決定位問題。以下是常見原因和對策：

  • 原因一：地圖與環境不匹配
    現場環境與採集建圖時相比已經發生了巨大變化，或者體驗的區域在採集時未能覆蓋，或地圖本身就是錯誤的。
    改善建議：

    • 確保您定位庫中加載的地圖與當前物理空間在場景上是一致的。
    • 如果環境已改造（如裝修、更換陳列），需要重新採集和生成地圖。
    • 如果採集建圖時未覆蓋發生問題的區域，需要通過補充更新的方式重新生成地圖。

  • 原因二：初始化環境不佳
    在紋理稀少的區域（如純色牆壁、對著地面）啟動應用。
    改善建議：

    • 引導用戶在紋理豐富的區域啟動應用，以幫助系統快速完成初始定位。
    • 在應用 UI 中給出明確的提示，如「抬起手機環視左右」。

  • 原因三：網絡或服務問題
    網絡延時導致定位服務請求超時，或者定位服務本身出現了故障、或超出了並發使用上限等。對於後者請及時與我們反饋。

  • 原因四：到達算法能力邊界
    Mega 定位基於先進的計算機視覺、AI 等算法，但其並不是萬能的，存在一定的算法能力邊界。當在某些場景或點位出現定位持續失敗時，可通過錄屏、錄製 EIF 數據等方式與我們進行反饋，幫助我們持續改進和迭代算法。

另外，需要特別說明的是，Mega 定位需要一個過程，通常在 1-2 秒左右。考慮到現實場景的複雜性如網絡擁堵、高並發、手機發熱降頻等情形，該時間可能會更久。因此，在應用中可以設計一個清晰的加載/等待界面，告知用戶「正在定位中...」，避免用戶因等待而誤以為服務掛了或定位不到。

附註
  • 首次定位通常比後續定位慢，因為系統在初次定位成功後需要加載相應的內容。這是正常現象。
  • 快速移動設備會可能導致定位丟失。請引導用戶平穩移動設備。

總結與最佳實踐

  • 始終使用外部工具先行驗證：這能最快地將問題範圍縮小到「定位」或「渲染」。
  • 建立合理的用戶預期：通過 UI 提示，讓用戶知道定位需要時間，並引導他們到合適的環境。
  • 關注內容邏輯：確保您的內容綁定等設置正確。
  • 善用日誌：在關鍵節點（如事件觸發、姿態獲取、響應狀態）打印日誌，可以幫助您快速定位代碼邏輯問題。

通過以上系統性的排查，您應該能夠解決絕大多數「內容不顯示」的問題。如果問題依然存在，請準備好 EIF 數據和日誌，通過 問題報告 的方式向我們提交詳細報告。