使用全新的 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 應用程式。
• Google Play 服務 - AR 適用 1.31 以上版本，已安裝在 Android 開發人員裝置上。

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 專案

Geospatial API 會結合 Street View 影像與裝置的磁力儀和相機感應器資訊，以改善方向值。如要使用這項服務，您必須設定 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 地圖 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.

在下方，請確認 Earth 物件是否可供使用。即 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 地球物件

在地球上建立錨點之前，請確認地球物件的 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 建立追蹤功能。過不久，地圖上就會顯示綠色標記，標示目前位置。

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

5. 結語

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

涵蓋內容

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

其他資源

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

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