Android 適用的 Cloud Anchors 開發人員指南 (Kotlin/Java)

瞭解如何在自己的應用程式中使用 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 的託管作業:

  1. 呼叫 hostCloudAnchorAsync()
  2. 等待回呼,或持續檢查 Future 狀態,直到操作完成。
  3. 檢查結果狀態來判斷作業是否成功,失敗時則是解讀錯誤代碼。
  4. 與其他用戶端分享 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。

後續步驟