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

1. 總覽

ARCore 是 Google 在智慧型手機上建構擴增實境體驗的架構。新版 ARCore Geospatial API 提供全新的擴增實境體驗，可讓您以現實世界地標，放置特定位置的擴增實境路線控點，

建構項目

在本程式碼研究室中，您將開始使用 ARCore Geospatial API。您將瞭解 Geospatial API 可以為整體 AR 體驗提供哪些資訊，以及如何運用這些資料提供簡單的 AR 路線搜尋體驗。

課程內容

• 如何設定使用 Geospatial API 的 ARCore 專案。
• 如何向 Geospatial API 要求地理資料，並使用 Google 地圖顯示。
• 如何放置附加至實際位置的錨點。

軟硬體需求

• 支援的 ARCore Android 裝置，使用 USB 傳輸線連接至開發機器，並透過 USB 偵錯進行設定。
• 安裝及設定 Android Studio，用來建構 Android 應用程式。
• 必須在 Android 開發裝置上安裝 AR 專用 Google Play 服務 1.31 以上版本。

2. 設定開發環境

設定 Android Studio

如要開始使用 Geospatial API，我們提供了一個範例專案，其中包含與 Google Maps SDK 整合的 ARCore 專案基本資訊。這有助您快速開始使用 Geospatial API。

1. 啟動 Android Studio，並從 VCS 匯入專案。
   • 如果已經開啟專案，請依序點選「檔案」>「檔案」新增 >來自版本管控的專案...
   • 如果看到「Welcome to Android Studio」視窗，請使用「Get from VCS」。
2. 選取「Git」，然後使用網址 https://github.com/google-ar/codelab-geospatial.git 匯入專案。

設定 Google Cloud 專案

Geospatial 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 中的值授權這個應用程式使用 Geospatial 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. 使用地球座標放置錨點

Geospatial API 可將錨點放在現實世界中任何座標組合與旋轉角度。這樣一來，使用者就能在造訪特定地點時看到錨定內容。

在此步驟中，您可以輕觸地圖新增放置錨點的方式。

設定輕觸地圖時執行的動作

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

確認可使用 Google 地球物件

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

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

決定新錨點的位置

確認 Earth 物件正在追蹤後，請卸離先前的 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] 變數可在「East-Up-South」(EUS) 座標系統中，決定錨點的以四元數表示的旋轉角度。使用不同的值旋轉錨定廣告，但在此範例中，使用單位四元組做為預設旋轉角度。單位四元旋轉的錨點方向為使 X+ 指向東方，Y+ 指向地球中心，Z+ 指向南方。

在地圖上顯示地點標記

最後，移動新標記來表示標記放置的位置：

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

立即試用

在 Android Studio 中按一下「Play」。拿起裝置並四處移動，即可協助 ARCore 建立追蹤功能。不久之後，你就會在地圖上看到一個綠色標記，表示你目前的位置。

輕觸地圖會使用 Geospatial API 放置錨點，並固定在實際位置。請嘗試將錨定標記放在目前位置附近，以便在 AR 檢視畫面中查看。瀏覽環境時，核心應用程式應會保持穩定。

5. 結語

在本程式碼研究室中，您已瞭解如何使用 Geospatial API，建立與真實世界息息相關的簡易 AR 體驗。

涵蓋內容

• 如何設定啟用 Geospatial API 的 Google Cloud 專案。
• 如何在 ARCore 專案中取得地理空間資訊，並將其顯示在地圖上。
• 如何透過地理位置定位在實際環境中放置錨點。

其他資源

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

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