開始使用 ARCore 中的 Streetscape Geometry 和 Rooftop anchors API

1. 事前準備

ARCore 是 Google 的架構，可讓您在智慧型手機上打造擴增實境 (AR) 體驗。透過 Geospatial Streetscape Geometry 和 Rooftop anchor API，AR 體驗可瞭解使用者周遭的建築物。

在本程式碼研究室中，您將建構 AR 應用程式，在您所在區域顯示街景幾何圖形，並裝飾兩側。接著，使用屋頂錨點在周圍屋頂頂端新增裝飾。

必要條件

• 具備 AR 基本知識
• ARCore Geospatial API 的基本知識

課程內容

• 如何設定可使用 ARCore 地理空間 API 的 Google Cloud 專案。
• 如何透過 Geospatial API 取得街景幾何圖形。
• 如何以街景幾何圖形取得的建築物和地形資料，製作視覺化效果。
• 如何對取得的多邊形執行基本計算。
• 如何對幾何圖形執行命中測試。
• 如何使用屋頂錨點將內容附加至建築物頂端。

軟硬體需求

• 支援 ARCore 的 Android 裝置，透過 USB 傳輸線連接至開發機器，並已設定 USB 偵錯。
• Android 開發裝置上已安裝 Google Play 服務 - AR 適用 1.37 以上版本。
• 已安裝 Android Studio，並設定為建構 Android 應用程式。

2. 設定環境

如要搭配 Kotlin 和 Android Studio 使用 Geospatial API，您需要 Google Cloud 專案和我們的入門專案。

設定 Google Cloud 專案

ARCore Geospatial API 會連線至 Google Cloud，在 Google 街景服務涵蓋的區域，提供 Google 視覺定位系統 (VPS) 的定位資訊。

如要在專案中使用這個伺服器，請按照下列步驟操作：

1. 在 Google Cloud 中建立專案。
2. 在「專案名稱」欄位中輸入適當名稱 (例如 ARCore Geospatial API project)，然後選擇任意位置。
3. 點選「建立」。
4. 在 Google Cloud 控制台的專案選取器頁面中，按一下「建立專案」。
5. 按一下下列連結，查看這個專案的 ARCore API，然後點按「啟用」：
   啟用 ARCore API
6. 為專案建立 API 金鑰：
   1. 在「API 和服務」下方，選取「憑證」。
   2. 接著按一下「建立憑證」並選取「API 金鑰」。
   3. 記下金鑰，因為後續步驟會用到。

您已建立 Google Cloud 專案並啟用 API 金鑰授權，現在可以開始在範例專案中使用 Geospatial API。

設定 Android Studio

如要開始使用 Geospatial API，我們提供了一個入門專案，其中包含整合 Geospatial API 的 ARCore 專案基本概念。

如要設定 Android Studio，請按照下列步驟操作：

1. 開啟 Android Studio，然後執行下列任一操作：
   • 如果已開啟專案，請依序點選「File」>「New」>「Project from version control」。
   • 如果看到「Welcome to Android Studio」視窗，請按一下「Get from VCS」。
2. 選取「Git」，然後輸入 https://github.com/google-ar/codelab-streetscape-geometry-rooftop-anchors.git 匯入專案。

將 API 金鑰與 Android Studio 專案整合

如要將 Google Cloud 的 API 金鑰與專案建立關聯，請按照下列步驟操作：

1. 在 Android Studio 中，依序點選「app」>「src」，然後按兩下 AndroidManifest.xml。
2. 找出下列 meta-data 項目：

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

3. 將 API_KEY 預留位置替換為您在 Google Cloud 專案中建立的 API 金鑰。com.google.android.ar.API_KEY 中儲存的值會授權這個應用程式使用 Geospatial API。

驗證專案

• 如要驗證專案，請在開發裝置上執行應用程式。螢幕頂端應會顯示攝影機畫面和地理空間偵錯資訊。您也會看到按鈕和控制項，但這些項目似乎沒有任何功能。在本程式碼研究室中，您將為專案編寫這些功能。

注意：如果 Geospatial API 未初始化，請確認您已將 API 金鑰插入 AndroidManifest.xml 檔案，且與 Google Cloud 中顯示的內容完全一致。

3. 以視覺化方式呈現街景幾何資料

確認 Geospatial API 可在裝置上運作後，即可從 Geospatial API 取得街景幾何圖形。

啟用街景幾何圖形

1. 在 StreetscapeGeometryActivity.kt 檔案中，找出下列程式碼行：

   // TODO: Enable Streetscape Geometry.
   

2. 在這行之後，啟用街景幾何模式：

   streetscapeGeometryMode = Config.StreetscapeGeometryMode.ENABLED
   

   啟用 Geospatial API 和街景幾何模式後，應用程式就能接收使用者周圍的街景幾何資訊。

取得街景幾何圖形

1. 在 StreetscapeGeometryActivity.kt 檔案中，找出下列程式碼行：

   // TODO: Obtain Streetscape Geometry.
   

2. 在這行之後，取得所有 Trackable 物件並依 StreetscapeGeometry 篩選，即可取得街景幾何：

   val streetscapeGeometry = session.getAllTrackables(StreetscapeGeometry::class.java)
   

   您可以在範例專案提供的簡單視覺化效果中使用這些幾何圖形。這項視覺化效果會以不同顏色顯示每個建築物或地形多邊形。
3. 在下一行中新增下列程式碼：

   streetscapeGeometryRenderer.render(render, streetscapeGeometry)
   

4. 執行應用程式，並前往您所在地區的建築物。
5. 完成地理空間定位後，輕觸「設定」，然後啟用街景幾何圖形視覺化功能。
6. 在 AR 中查看建築物。每個區隔建築物都有自己的顏色，並顯示最中央幾何體的 Quality 和 Type 列舉。

注意：如果看不到街景幾何圖形，或輕觸螢幕時沒有顯示任何裝飾，請按照下列步驟從程式碼研究室檢查點重設：

1. 在 Android Studio 中，依序點選「VCS」>「Git」>「Branches」>「Checkout」>「step-3」。這會返回第三個步驟。
2. 按照設定說明的詳細指示，將 API 金鑰加進 AndroidManifest.xml 檔案。

4. 使用街景幾何資料執行命中測試

現在您可以看到街景幾何圖形，可以透過命中測試裝飾建築物。命中測試會找出虛擬幾何圖形與射線的交集。您可以使用命中測試，找出使用者輕觸的幾何圖形。

執行命中測試

在本節中，當使用者輕觸建築物的幾何圖形時，您會在建築物外牆上放置星號。您可從使用者的角度在世界中進行命中測試，並註冊路徑上遇到的 AR 物件。接著，您可以使用這項資訊，檢查使用者是否輕觸建築物多邊形。

1. 在 StreetscapeCodelabRenderer.kt 檔案中，找出下列程式碼行：

   // TODO: determine the Streetscape Geometry at the center of the viewport
   

2. 在這行之後，新增下列程式碼：

   val centerHits = frame.hitTest(centerCoords[0], centerCoords[1])
   val hit = centerHits.firstOrNull {
     val trackable = it.trackable
     trackable is StreetscapeGeometry && trackable.type == StreetscapeGeometry.Type.BUILDING
   } ?: return
   

   這段程式碼會使用中心座標，尋找屬於建築物的街景幾何圖形。您可以使用這項結果新增裝飾。

輕觸即可新增星號裝飾

1. 在 StreetscapeCodelabRenderer.kt 檔案中，找出下列程式碼行：

   // TODO: Create an anchor for a star, and add it to the starAnchors object.
   

2. 在這行之後，新增下列程式碼：

   val transformedPose = ObjectPlacementHelper.createStarPose(hit.hitPose)
   val anchor = hit.trackable.createAnchor(transformedPose)
   starAnchors.add(anchor)
   

   ObjectPlacementHelper 類別會查看命中姿勢，判斷星星的適當位置。starAnchors 物件用於在 AR 檢視畫面中算繪星星。

立即試用

1. 執行應用程式，並前往您所在地區的建築物。
2. 完成地理空間定位後，將攝影機對準建築物並輕觸螢幕。畫面中央的建築物上會出現星星。

注意：如果看不到街景幾何圖形，或輕觸螢幕時沒有顯示任何裝飾，請按照下列步驟操作：

1. 在 Android Studio 中，依序點選「VCS」>「Git」>「Branches」>「Checkout」>「step-4」。
2. 按照設定說明的詳細指示，將 API 金鑰加進 AndroidManifest.xml 檔案。

5. 使用屋頂錨點資料

最後，您可以使用屋頂錨點，在建築物頂部新增裝飾。頂樓錨點可協助您將 AR 錨點附加至建築物頂部，並提供經緯度。您可以使用這些錨點，將氣球附加到使用者周圍的建築物。

在氣球模式中新增行為

這個專案有兩種素材資源放置模式：您已使用的向日葵模式和氣球模式。

如要為氣球模式設計行為，請按照下列步驟操作：

1. 在 StreetscapeCodelabRenderer.kt 檔案中，找出下列程式碼行：

   // TODO: Create an anchor for a balloon and add it to the balloonAnchors object.
   

2. 使用擊中姿勢為氣球打造絕佳位置：

   val transformedPose = ObjectPlacementHelper.createBalloonPose(frame.camera.pose, hit.hitPose)
   

3. 將 transformedPose 變數轉換為地理空間姿勢：

   val earth = session?.earth ?: return
   val geospatialPose = earth.getGeospatialPose(transformedPose)
   

4. 使用轉換後的緯度和經度建立屋頂錨點：

   earth.resolveAnchorOnRooftopAsync(
     geospatialPose.latitude, geospatialPose.longitude,
     0.0,
     transformedPose.qx(), transformedPose.qy(), transformedPose.qz(), transformedPose.qw()
   ) { anchor, state ->
     if (!state.isError) {
       balloonAnchors.add(anchor)
     }
   }
   

立即試用

1. 執行應用程式，並前往您所在地區的建築物。
2. 完成地理空間定位後，切換至氣球模式並輕觸建築物，建築物上方會出現氣球。

如果無法重現預期行為，請按照下列步驟操作：

1. 在 Android Studio 中，依序點選「VCS」>「Git」>「Branches」>「Checkout」>「step-5」。
2. 按照設定說明的詳細指示，將 API 金鑰加進 AndroidManifest.xml 檔案。

6. 結論

恭喜！您建構的 AR 應用程式會顯示您所在區域的街景幾何圖形，並讓您在兩側裝飾星星。您也使用屋頂錨點，在周圍屋頂頂端新增氣球。

瞭解詳情

• 街景幾何圖形開發人員指南
• 屋頂錨點開發人員指南
• Geospatial API 總覽