瞭解如何在自己的應用程式中使用 Cloud Anchors。
必要條件
請務必瞭解基本 AR 概念 以及如何在繼續操作前設定 ARCore 工作階段。
如果您是第一次使用 Cloud Anchor，請務必瞭解錨點和 Cloud Anchors 的運作方式。
啟用 ARCore API
您必須先在應用程式中啟用 ARCore API，才能在應用程式中使用 Cloud Anchors。
在工作階段設定中啟用 Cloud Anchor 功能
在應用程式中啟用 Cloud Anchors 功能後，請在應用程式的 AR 工作階段設定中啟用 Cloud Anchors 功能，以便與 ARCore API 通訊：
// Create a new ARCore session.
ArSession* session = NULL;
CHECK(ArSession_create(env, context, &session) == AR_SUCCESS);
// Create a session config.
ArConfig* config = NULL;
ArConfig_create(session, &config);
ArSession_getConfig(session, config);
// Enable Cloud Anchor mode.
ArConfig_setCloudAnchorMode(session, config,
AR_CLOUD_ANCHOR_MODE_ENABLED);
// Configure the session.
ArSession_configure(session, config);
ArConfig_destroy(config);
託管 Cloud Anchor
開始時，只要呼叫 ArSession_hostCloudAnchorAsync() 即可。ARCore 會將視覺資料、裝置姿勢和錨點姿勢上傳到 ARCore API。接著，API 會處理這項資訊來建構 3D 功能對應，最終將錨定標記的專屬 Cloud Anchor ID 傳回裝置。
您也可以使用 ARCore Cloud Anchor Management API 延長代管錨點的生命週期。
應用程式應按照下列步驟完成 Cloud Anchor 的託管：
- 呼叫
ArSession_hostCloudAnchorAsync()。 - 等待回呼，或者持續查看 Future 狀態，直到作業完成為止。
- 查看結果狀態 判斷作業是否成功；如果作業失敗，則解讀錯誤代碼。
- 與其他用戶端分享結果 Cloud Anchor ID，並使用該 ID 解析 Cloud Anchor：
ArSession_resolveCloudAnchorAsync()。
檢查地圖項目點的地圖品質
ArFeatureMapQuality 表示 ARCore 在指定相機姿勢之前幾秒前看到的特徵點品質。使用較高品質特徵託管的 Cloud Anchor 通常較能得到正確的解析。使用 ArSession_estimateFeatureMapQualityForHosting() 取得特定相機姿勢的地圖項目地圖品質估計值。
| 值 | 說明 |
|---|---|
INSUFFICIENT |
在前幾秒根據姿勢識別特徵點的品質偏低。這個狀態表示 ARCore 在解析 Cloud Anchor 可能較困難。鼓勵使用者移動裝置，以便從不同角度查看要放置的 Cloud Anchor 所需位置。 |
SUFFICIENT |
儘管在前幾秒根據姿勢辨識出特徵點的品質，ARCore 應該就能順利解析 Cloud Anchor，但這可能會降低解決姿勢的準確度。鼓勵使用者移動裝置，以便從不同角度查看要放置的 Cloud Anchor 所需位置。 |
GOOD |
ARCore 能在前幾秒根據姿勢辨識出特徵點的品質，可能足以讓 ARCore 成功地解析出高度準確度的 Cloud Anchor。 |
解決先前代管的錨定廣告
呼叫 ArSession_resolveCloudAnchorAsync() 可解析託管的 Cloud Anchor。ARCore API 會定期比較場景中的視覺特徵與錨點 3D 功能地圖，找出使用者相對於錨點的位置和方向。如果找到相符項目，API 會傳回代管 Cloud Anchor 的姿勢。
您可以依序啟動多個 Cloud Anchor 的解析作業。一次最多可存在 40 個並行 Cloud Anchor 作業。
取消作業或移除 Cloud Anchor
呼叫 ArFuture_cancel() 來取消待處理的 Cloud Anchor 作業。
呼叫 ArAnchor_detach() 以停止追蹤，並清除已解決的 Cloud Anchor。錨點的參照必須分別透過呼叫 ArAnchor_release() 來釋放。
查看 Cloud Anchor 作業的結果狀態
使用 ArCloudAnchorState 查看託管或解決作業的結果狀態 (包括錯誤)。
| 值 | 說明 |
|---|---|
AR_CLOUD_ANCHOR_STATE_ERROR_CLOUD_ID_NOT_FOUND |
ARCore API 找不到您提供的 Cloud Anchor ID，因此導致解決失敗。 |
AR_CLOUD_ANCHOR_STATE_ERROR_HOSTING_DATASET_PROCESSING_FAILED |
代管失敗，因為伺服器無法成功處理指定錨點的資料集。請在裝置從環境收集更多資料後再試一次。 |
AR_CLOUD_ANCHOR_STATE_ERROR_HOSTING_SERVICE_UNAVAILABLE |
無法連線至 ARCore API。導致這個問題的原因可能不只一個。裝置可能處於飛航模式或未連上網際網路。傳送至伺服器的要求可能已逾時，且沒有回應。可能是因為網路連線不穩定、DNS 無法使用、防火牆問題，或是其他因素可能會影響裝置連線至 ARCore API 的能力。 |
AR_CLOUD_ANCHOR_STATE_ERROR_INTERNAL |
這個錨點的代管或解析工作已完成，但發生內部錯誤。應用程式不應嘗試從此錯誤中復原。 |
AR_CLOUD_ANCHOR_STATE_ERROR_NOT_AUTHORIZED |
請參閱排解 ARCore API 授權問題。 |
AR_CLOUD_ANCHOR_STATE_ERROR_RESOLVING_SDK_VERSION_TOO_NEW |
無法解析 Cloud Anchor，因為用於解析錨點的 SDK 版本比託管錨點的版本還新，也不相容。 |
AR_CLOUD_ANCHOR_STATE_ERROR_RESOLVING_SDK_VERSION_TOO_OLD |
無法解析 Cloud Anchor，因為用於解析錨點的 SDK 版本比代管錨點的版本更舊，也與託管時使用的版本不相容。 |
AR_CLOUD_ANCHOR_STATE_ERROR_RESOURCE_EXHAUSTED |
應用程式已用盡指定 Google Cloud 專案的要求配額。請透過 Google Developers Console 為專案申請更多 ARCore API 配額。 |
AR_CLOUD_ANCHOR_STATE_SUCCESS |
已成功完成這個錨點的代管或解析工作。 |
主機和解析要求的 API 配額
ARCore API 的要求頻寬配額如下：
| 配額類型 | 上限 | 持續時間 | 套用對象 |
|---|---|---|---|
| 錨點數量 | 無限制 | 不適用 | 專案 |
| 錨定主機要求 | 30 | 分鐘 | IP 位址與專案 |
| 錨定解決要求 | 300 | 分鐘 | IP 位址與專案 |
打造良好使用者體驗的最佳做法
請引導使用者執行下列操作，確保應用程式提供良好的使用者體驗：
- 請在工作階段開始後等待幾秒，再嘗試代管錨點 (透過放置物件等方式)。如此一來，追蹤就會一段時間趨於穩定。
- 選取放置錨點的位置時，請設法找出視覺元素彼此之間最容易區別的區域。為獲得最佳效果，請避免使用缺乏視覺特徵的表面或表面，例如空白白牆。
持續訓練相機以搜尋你感興趣的位置，並沿著裝置四處移動 這個搜尋中心可從不同角度繪製環境地圖，且維持大致相同的實際距離。這樣有助於擷取更多視覺化資料，進而提升解決方法。
確保實際環境中的照明充足，同時託管及解決 Cloud Anchors。
廢止政策
- 使用 ARCore SDK 1.12.0 以上版本建構的應用程式適用 Cloud Anchor API 廢止政策。
- 使用 ARCore SDK 1.11.0 以下版本建構的應用程式無法代管或解析 Cloud Anchor，因為 SDK 使用了已淘汰的舊版 ARCore API。
後續步驟
- 請參閱 Android NDK 參考說明文件，進一步瞭解如何在應用程式中使用 ARCore。