使用全新的 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 開發裝置上已安裝 Google Play 服務 - AR 適用 1.31 以上版本。

2. 設定開發環境

設定 Android Studio

為協助您開始使用 Geospatial 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 專案

地理空間 API 會結合街景圖像、裝置的磁力儀和相機感應器資訊，提升方向值。如要使用這項服務，您必須設定 Google Cloud 專案。

1. 在 Google Cloud 控制台中建立專案：
   • 請參閱「在 Google Cloud Platform 中建立專案」一文。
     
   • 輸入適當的「專案名稱」 (例如「ARCore Geospatial API project」)，並選擇任何位置。
   • 點選「建立」。
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 地圖 SDK。

驗證專案

確認專案已準備就緒。在 Android Studio 中執行應用程式，螢幕底部應會顯示攝影機畫面和可運作的地圖。

3. 判斷使用者的位置

在本步驟中，您會將程式碼新增至範例專案，開始使用 Geospatial API。

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

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

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 函式。

確認可以使用 Earth 物件

在地球上建立錨點前，請確認地球物件的 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] 變數會以四元數表示錨點的旋轉，座標系統為東-上-南 (EUS)。您可以使用不同的值來旋轉錨點，但在本範例中，請使用單位四元數做為預設旋轉。單位四元數旋轉的錨點方向為 X+ 指向東方、Y+ 指向遠離地心的上方，而 Z+ 指向南方。

在地圖上顯示放置的標記

最後，移動新標記，指出標記的放置位置：

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

立即試用

在 Android Studio 中，按一下「Play」。舉起裝置並移動，協助 ARCore 建立追蹤功能。稍待片刻，地圖上就會出現綠色標記，指出您目前的位置。

輕觸地圖會使用 Geospatial API 放置錨點，錨點會固定在真實世界的位置。請將錨點放在目前位置附近，這樣就能在 AR 檢視畫面中看到錨點。在環境中瀏覽時，應保持穩定。

5. 結語

在本程式碼研究室中，您已瞭解如何使用 Geospatial API 建立與現實世界連結的簡單 AR 體驗。

涵蓋內容

• 如何設定 Google Cloud 專案並啟用 Geospatial API。
• 瞭解如何在 ARCore 專案中取得地理空間資訊，並在地圖上顯示。
• 瞭解如何使用地理位置資訊，在現實世界中放置錨點。

其他資源

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

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