瞭解如何在自己的應用程式中使用 Cloud Anchor。
必備條件
請務必先瞭解基本 AR 概念,以及如何設定 ARCore 工作階段,然後再繼續操作。
如果您是第一次使用 Cloud Anchors:
- 請務必瞭解錨點和雲端錨點的運作方式。
- 詳閱 Cloud Anchors quickstart,瞭解系統需求、設定和安裝操作說明。
啟用 ARCore API
您必須先在應用程式中啟用 ARCore API,才能在應用程式中使用 Cloud Anchor。
在工作階段設定中啟用 Cloud Anchor 功能
一旦在應用程式中啟用 Cloud Anchors 功能,請在應用程式的 AR 工作階段設定中啟用 Cloud Anchors 功能,讓應用程式與 ARCore API 通訊:
Java
Config config = new Config(session); config.setCloudAnchorMode(Config.CloudAnchorMode.ENABLED); session.configure(config);
Kotlin
val config = Config(session) config.cloudAnchorMode = Config.CloudAnchorMode.ENABLED session.configure(config)
託管雲端錨點
「託管」程序首先會呼叫 hostCloudAnchorAsync()
。ARCore 會將視覺化資料、裝置姿勢和錨點姿勢上傳至 ARCore API,接著,API 會處理這些資訊來建構 3D 功能對應,最後將不重複的 Cloud Anchor ID 傳回至裝置。
您也可以使用 ARCore Cloud Anchor Management API 延長代管錨點的生命週期。
您的應用程式應執行下列步驟,完成 Cloud Anchor 的託管作業:
- 呼叫
hostCloudAnchorAsync()
。 - 等待回呼,或持續檢查 Future 狀態,直到操作完成。
- 檢查結果狀態來判斷作業是否成功,失敗時則是解讀錯誤代碼。
- 與其他用戶端分享 Cloud Anchor ID 結果,並使用
resolveCloudAnchorAsync()
解析 Cloud Anchor。
確認地圖項目點的對應品質
Session.FeatureMapQuality
表示 ARCore 在從特定相機姿勢中偵測到的特徵點品質。使用品質較高的功能託管的 Cloud Anchor 通常可更準確地解析。使用 Session.estimateFeatureMapQualityForHosting()
取得特定相機姿勢的地圖項目地圖品質預估值。
值 | 說明 |
---|---|
INSUFFICIENT |
在過去幾秒內,根據姿勢發現的特徵點品質偏低。這個狀態表示 ARCore 可能較難解析 Cloud Anchor。建議使用者移動裝置,以便從不同角度查看想託管的 Cloud Anchor 位置。 |
SUFFICIENT |
前幾秒的姿勢發現的特徵點品質足以讓 ARCore 成功解析 Cloud Anchor,不過解決姿勢的準確度可能會降低。建議使用者移動裝置,以便從不同角度查看想託管的 Cloud Anchor 位置。 |
GOOD |
前幾秒的姿勢發現的特徵點品質足以讓 ARCore 成功解析具有高準確度的 Cloud Anchor。 |
解析先前代管的錨定標記
呼叫 resolveCloudAnchorAsync()
即可解析託管的 Cloud Anchor。ARCore API 會定期比較場景中的視覺地圖項目與錨點的 3D 功能地圖,以找出使用者相對於錨點的位置和方向。找到相符項目時,API 會傳回託管 Cloud Anchor 的姿勢。
您可以依序啟動多個 Cloud 錨點的解析作業。一次最多可同時存在 40 個 Cloud Anchor 作業。
取消作業或移除 Cloud Anchor
呼叫 cancel()
以取消待處理的 Cloud Anchor 作業。呼叫 detach()
,將已解析的 Cloud Anchor 從應用程式中移除。
檢查 Cloud Anchor 作業的結果狀態
使用 Anchor.CloudAnchorState 查看託管或解析作業的結果狀態,包括錯誤。
值 | 說明 |
---|---|
ERROR_CLOUD_ID_NOT_FOUND |
ARCore API 找不到您提供的 Cloud 錨定 ID,因此無法解決這個問題。 |
ERROR_HOSTING_DATASET_PROCESSING_FAILED |
伺服器無法成功處理指定錨點的資料集,因此託管失敗。請在裝置從環境收集更多資料後再試一次。 |
ERROR_HOSTING_SERVICE_UNAVAILABLE |
無法連上 ARCore API,導致這個問題的原因可能不只一個。裝置可能處於飛航模式,或是未連上網路。傳送至伺服器的要求可能逾時,而且沒有回應。原因可能是網路連線狀況不佳、DNS 無法使用、防火牆問題或其他可能影響裝置連線至 ARCore API 的功能。 |
ERROR_INTERNAL |
這個錨點的代管或解析工作已完成,但發生內部錯誤。應用程式不應嘗試從這個錯誤中復原。 |
ERROR_NOT_AUTHORIZED |
應用程式提供的授權無效。請參閱「排解 ARCore API 授權問題」。 |
ERROR_RESOLVING_SDK_VERSION_TOO_NEW |
用於解析錨點的 SDK 版本較新且與用於託管錨點的版本不相容,因此無法解析 Cloud Anchor。 |
ERROR_RESOLVING_SDK_VERSION_TOO_OLD |
用於解析錨點的 SDK 版本比用於託管錨點的版本更舊且不相容,因此無法解析 Cloud Anchor。 |
ERROR_RESOURCE_EXHAUSTED |
應用程式已達到指定 Google Cloud 專案適用的要求配額。建議您透過 Google Developers Console 為專案申請額外的 ARCore API 配額。 |
SUCCESS |
這個錨點的代管或解析工作已順利完成。 |
主機和解析要求的 API 配額
ARCore API 要求頻寬的配額如下:
配額類型 | 上限 | 時間長度 | 套用對象 |
---|---|---|---|
錨點數量 | 無限制 | 不適用 | 專案 |
錨定 host 要求 | 30 | 分鐘 | IP 位址和專案 |
錨定resolve要求 | 300 | 分鐘 | IP 位址和專案 |
確保良好使用者體驗的最佳做法
請引導使用者執行下列操作,確保應用程式提供良好的使用者體驗:
- 在工作階段開始後稍候幾秒鐘,再嘗試代管錨點 (透過放置物件等)。如此才有時間穩定追蹤。
- 選取代管錨點的位置時,請盡量找出視覺特徵之間容易區別的區域。為獲得最佳效果,請避免使用缺少視覺特徵的反光錶面或表面,例如白色牆壁。
將攝影機保持在所需中心點,然後移動裝置中心點,從不同角度繪製環境地圖,保持大致相同的實際距離。這有助於擷取更豐富的圖像資料,並更完善地解析。
託管並解決 Cloud Anchor 時,請確保在現實環境中有足夠的光線。
廢止政策
- 使用 ARCore SDK 1.12.0 以上版本建構的應用程式適用 Cloud Anchor API 淘汰政策。
- 使用 ARCore SDK 1.11.0 以下版本建構的應用程式無法代管或解析 Cloud Anchor,原因是 SDK 使用了已淘汰的舊版 ARCore API。
後續步驟
- 透過 ARCore Cloud Anchors 與永久 Cloud Anchors 程式碼研究室建立 Cloud Anchors 應用程式。
- 透過 Cloud Anchors 快速入門導覽課程,逐步說明如何託管及解析 Cloud Anchor。
- 使用 Cloud Anchors Management API,管理 ARCore 應用程式以外的 Cloud Anchor。
- 歡迎參閱 Android 參考說明文件,進一步瞭解在應用程式中使用 ARCore 的方法。