使用全新的 ARCore Geospatial API 建構擴增實境 (AR) 應用程式

1. 總覽

ARCore 是 Google 用來在智慧型手機上建立擴增實境體驗的架構。新版 ARCore Geospatial API 為擴增實境技術提供了前所未有的觀點，方便您將特定地點的擴增實境路線控點圍繞在現實世界的地標上。

建構項目

在本程式碼研究室中，您將開始使用 ARCore Geospatial API。您將瞭解 Geo 空間 API 在整體 AR 體驗可提供的資訊，以及如何根據這些資料提供簡單的 AR 路線指引服務。

課程內容

• 如何設定使用 Geospatial API 的 ARCore 專案。
• 如何透過 Geospatial API 要求地理資料，並使用 Google 地圖顯示這些資料。
• 如何放置連接真實世界位置的錨點。

軟硬體需求

• 支援的 ARCore Android 裝置，使用 USB 傳輸線連接開發機器，並設定 USB 偵錯功能。
• 安裝並設定 Android Studio 以建構 Android 應用程式。
• Google Play 服務 - AR 適用：安裝在 Android 開發裝置上。1.31 以上版本。

2. 設定開發環境

設定 Android Studio

為開始使用地理空間 API，我們先提供了一個範例專案，其中包含與 Google Maps SDK 整合的 ARCore 專案基本概念。這可讓您快速開始使用 Geospatial API。

1. 啟動 Android Studio，並從 VCS 匯入專案。
   • 如果您已開啟專案，請依序點選「File」>「New」>「Project from Version Control...」。
   • 如果看到「Welcome to Android Studio」視窗，請使用「Get from VCS」。
2. 選取「Git」，並使用網址 https://github.com/google-ar/codelab-geospatial.git 匯入專案。

設定 Google Cloud 專案

Geospace API 使用街景服務圖像，結合裝置的磁力儀和相機感應器資訊，提高螢幕方向值。您需要設定 Google Cloud 專案，才能使用這項服務。

1. 在 Google Cloud 控制台中建立專案：
   • 前往在 Google Cloud Platform 中建立專案。
     
   • 輸入適當的專案名稱 (例如「ARCore Geospatial API 專案」)，並選擇任何地點。
   • 點選「建立」。
2. 啟用必要的 API：
   • 在側欄中，依序選取「API 和服務」和「程式庫」。
   • 搜尋「ARCore API」。
   • 點選「啟用」。
   • 返回「媒體庫」。
   • 搜尋 Maps SDK for Android。
   • 點選「啟用」。
3. 建立 API 金鑰憑證：
   • 選取「API 和服務」下方的「憑證」。
   • 按一下頂端列的「建立憑證」，然後選取「API 金鑰」。
   • 請記下您建立的金鑰，後續步驟將會用到。如需擷取，請返回「憑證」頁面。

完成這些步驟後，您建立了具備 API 金鑰授權的 Google Cloud 專案，也已準備好使用 Geospatial API。

將 API 金鑰與 Android Studio 專案整合

如要將 Google Cloud 的 API 金鑰與專案建立關聯，請開啟您在 Android Studio 中建立的專案，然後修改 API 金鑰：

1. 開啟「app」>「src」>「AndroidManifest.xml」。
2. 請找出下列 meta-data 項目：

   <meta-data
       android:name="com.google.android.ar.API_KEY"
       android:value="PLACEHOLDER_API_KEY" />
   
   <meta-data
       android:name="com.google.android.geo.API_KEY"
       android:value="PLACEHOLDER_API_KEY" />
   

3. 將 PLACEHOLDER_API_KEY 替換成您在 Google Cloud 專案中建立的 API 金鑰。

儲存在 com.google.android.ar.API_KEY 中的值會授權這個應用程式使用地理空間 API，而儲存在 com.google.android.geo.API_KEY 中的值則授權這個應用程式使用 Google Maps SDK。

驗證專案

請確認專案已準備就緒。在 Android Studio 中執行應用程式。畫面底部應該會顯示相機檢視畫面和實際地圖。

3. 判斷使用者的位置

在這個步驟中，您要在範例專案中加入程式碼，開始使用 Geospatial API。

設定 ARCore 工作階段以使用 Geospatial API

如要取得地理空間資料，您必須啟用 Geospatial API。修改 HelloGeoActivity.kt 中的 configureSession 函式，將工作階段設定中的 GeospatialMode 變更為 ENABLED：

fun configureSession(session: Session) {
  session.configure(
    session.config.apply {
      // Enable Geospatial Mode.
      geospatialMode = Config.GeospatialMode.ENABLED
    }
  )
}

當地理空間模式為 ENABLED 時，應用程式可以取得地理空間資訊。

透過 Geospatial API 要求資料

在 HelloGeoRenderer.kt 中，找出以下這行程式碼：

// TODO: Obtain Geospatial information and display it on the map.

在下方，檢查地球物件是否可供使用。這時 trackingState TrackingState.ENABLED 就能派上用場。

val earth = session.earth
if (earth?.trackingState == TrackingState.TRACKING) {
  // TODO: the Earth object may be used here.
}

在 TODO 下方，向 ARCore 要求地理空間資訊。新增此行：

val cameraGeospatialPose = earth.cameraGeospatialPose

這樣就能取得包含以下資訊的 GeospatialPose：

• 位置，以經緯度表示。另外，系統也會提供精確的定位精確度預估值。
• 高度和估算高度的準確性。
• 方向、裝置朝向的概略位置，以及方向準確的預估值。

在地圖上顯示位置資訊

您可以使用儲存在 cameraGeospatialPose 中的 GeospatialPose，在地圖上移動顯示使用者所在位置的標記。繼續從上次離開的地方新增下列內容：

activity.view.mapView?.updateMapPosition(
  latitude = cameraGeospatialPose.latitude,
  longitude = cameraGeospatialPose.longitude,
  heading = cameraGeospatialPose.heading
)

這個指令會使用從 Geospatial API 取得的值，持續更新地圖的位置。

立即體驗

在 Android Studio 中，按一下「Play」。請拿起裝置並四處移動，協助 ARCore 建立追蹤資料。不久之後，地圖上會顯示綠色標記。此標記會在您檢視周遭環境時旋轉。它也應指向正確的方向：當您面朝北時，箭頭也指向北方。

4. 使用地球座標放置錨點

地理空間 API 可在現實世界中將錨點放置在任何座標組和旋轉的位置。如此一來，當使用者造訪特定地點時，就能看到錨定內容。

在這個步驟中，您將新增在地圖上放置錨點的方法。

設定輕觸地圖時的動作

此專案隨附 onMapClick 函式，當使用者點選地圖片段時，系統會使用經緯度呼叫函式。在 HelloGeoRenderer.kt 中找出 onMapClick 函式。

確認可以使用 地球物件

在 Google 地球上建立錨點之前，請確認地球物件的 TrackingState 為 TRACKING，表示地球的位置已知。此外，請確認其 EarthState 為 ENABLED，這表示 Geospatial API 沒有問題。在 onMapClick 中新增以下幾行：

val earth = session?.earth ?: return
if (earth.trackingState != TrackingState.TRACKING) {
  return
}

決定新錨定標記的位置

確認地球物件正在追蹤後，請卸離前一個 earthAnchor (如果有的話)。您將在後續步驟中將 earthAnchor 替換成新的錨點：

earthAnchor?.detach()

接著，使用 cameraGeospatialPose 來判斷新錨點的海拔高度。使用輕觸地圖中的座標組做為錨點的位置。

// Place the earth anchor at the same altitude as that of the camera to make it easier to view.
val altitude = earth.cameraGeospatialPose.altitude - 1
// The rotation quaternion of the anchor in the East-Up-South (EUS) coordinate system.
val qx = 0f
val qy = 0f
val qz = 0f
val qw = 1f
earthAnchor =
  earth.createAnchor(latLng.latitude, latLng.longitude, altitude, qx, qy, qz, qw)

createAnchor 會根據指定旋轉的地理座標，建立固定的 Anchor。此錨點會嘗試保持穩定並固定於指定的座標和高度。

[qx, qy, qz, qw] 變數會決定在東向南 (EUS) 座標系統中錨點的旋轉角度以四元數表示。您可以用不同的值旋轉錨點，但本範例使用單位四元數做為預設旋轉角度。單位四元數旋轉的定位方向為 X+ 點往東，Y+ 點則離地球中心，Z+ 則指向南方。

在地圖上顯示放置的標記

最後，請移動一個指出標記位置的新標記：

activity.view.mapView?.earthMarker?.apply {
  position = latLng
  isVisible = true
}

立即體驗

在 Android Studio 中，按一下「Play」。拿起裝置然後四處移動，協助 ARCore 建立追蹤資料。不久之後，地圖上會顯示綠色標記，指出您目前的位置。

輕觸地圖會使用地理空間 API 放置固定在實際地點的錨點。試著將錨點放置在您所在位置附近，這樣您就可以在 AR 檢視中看到該錨點。在您瀏覽環境時，小工具應該會保持穩定。

5. 結論

在本程式碼研究室中，您學到瞭如何使用地理空間 API 建立與真實世界相關的簡易 AR 體驗。

涵蓋內容

• 如何在啟用 Geospatial API 的情況下設定 Google Cloud 專案。
• 如何在 ARCore 專案中取得地理空間資訊，並在地圖上顯示相關資訊。
• 如何透過地理定位將錨定在現實世界中的錨點放置。

其他資源

如要進一步瞭解本程式碼研究室使用的地理概念和 SDK，請參閱下列其他資源：

• ARCore Geospatial API 說明文件
• 世界大地測量系統 (WGS)
• Google Maps SDK for Android