開始使用 ARCore 的場景語意和地理空間深度 API

1. 事前準備

ARCore 是 Google 的架構，可讓您在智慧型手機上打造擴增實境 (AR) 體驗。場景語意和地理空間深度 API 可協助擴增實境體驗瞭解使用者周遭環境。

場景語意 API 會使用機器學習 (ML) 模型分析攝影機影像，並提供標示像素的影像。可區分 11 種不同的戶外標籤。

Geospatial Depth API 會結合動作的深度資訊、任何啟用的硬體感應器 (例如飛行時間) 的深度資訊，以及 Streetscape Geometry API 資料。可改善最遠 65 公尺的深度觀測錯誤。

在本程式碼研究室中，您將建構 AR 應用程式，以視覺化方式呈現場景語意和地理空間深度 API 的結果。

必要條件

• 具備 AR 基本知識

課程內容

• 如何啟用 Scene Semantics API。
• 如何取得及顯示語意圖片。
• 如何取得及顯示語意信賴度圖像。
• 如何判斷特定標籤對應的像素百分比。
• 如何設定可使用 ARCore 地理空間 API 的 Google Cloud 專案。
• 如何啟用 Geospatial Depth API。
• 如何以視覺化方式呈現深度圖像。

軟硬體需求

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

2. 設定環境

為協助您開始使用 Geospatial API，我們提供入門專案，其中包含 ARCore 專案的基本概念和一些輔助函式。

如要設定入門專案，請按照下列步驟操作：

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

3. 將 Scene Semantics API 資料視覺化

啟用 Scene Semantics API

為節省處理能力，Scene Semantics API 預設為停用。

如要啟用 Scene Semantics API，請按照下列步驟操作：

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

   // TODO: Enable the Scene Semantics API.
   

2. 在該行之後，如果裝置支援，請在工作階段的設定中啟用 Scene Semantics API：

   if (session.isSemanticModeSupported(Config.SemanticMode.ENABLED)) {
     semanticMode = Config.SemanticMode.ENABLED
   }
   

取得並顯示語意圖像

語意圖像是由 ARCore ML 模型產生，會為攝影機串流中的每個像素指派 SemanticLabel 列舉。

如要取得語意圖像並顯示在畫面上，請按照下列步驟操作：

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

   // TODO: Obtain the semantic image for this frame.
   

2. 在該行之後，取得語意圖片：

   frame.acquireSemanticImage().use { image ->
     semanticRenderer.updateCameraSemanticsTexture(image)
     activity.view.semanticLabelAtCenter = getLabelAt(image, image.width/2, image.height/2)
   }
   

   語意圖片會用於 SemanticRenderer 類別，在畫面上顯示。您會更新 semanticLabelAtCenter 變數，在應用程式檢視區塊的畫面中央顯示語意標籤。
3. 執行應用程式，並將相機對準室外的不同物體。查看不同類型的物件時，語意標籤的顯示方式會有所不同。
4. 輕觸「設定」，啟用語意信賴度圖像疊加功能。

取得並顯示語意信賴度圖片

語意信心圖像會指出 ARCore 對於相符像素的語意標籤有多有信心。

如要取得語意圖像並顯示在畫面上，請按照下列步驟操作：

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

   // TODO: Obtain the confidence image for this frame.
   

2. 在這行之後，取得語意圖片：

   frame.acquireSemanticConfidenceImage().use { image ->
     semanticRenderer.updateConfidenceSemanticsTexture(image)
     activity.view.confidenceAtCenter = getConfidenceAt(image, image.width/2, image.height/2)
   }
   

   語意信賴度圖片會用於 SemanticRenderer 類別，顯示在螢幕上。您會更新 confidenceAtCenter 變數，在應用程式檢視區塊的畫面中央顯示語意標籤。
3. 執行應用程式，並將相機對準室外的不同物體。查看不同類型的物件時，語意信賴度顯示畫面會隨之變更。
4. 輕觸「設定」，啟用語意信賴度圖像疊加功能。

判斷標籤的普遍程度

標籤的普遍程度是指與特定標籤相等的語意圖像所占百分比。舉例來說，如果圖片有 26% 的區域具有 SemanticLabel.SKY 值，則 SemanticLabel.SKY 值的普遍程度值為 0.26f。

如要取得標籤的普遍程度並顯示在畫面上，請按照下列步驟操作：

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

   // TODO: Obtain the prevalence of the selected label for this frame.
   

2. 在該行之後，取得所選標籤的普遍程度：

   activity.view.fractionOfLabel = frame.getSemanticLabelFraction(activity.view.selectedSemanticLabel)
   

3. 執行應用程式，並將相機對準室外的不同物體。查看不同類型的物件時，分數值會有所不同。輕觸「設定」，即可變更顯示的標籤分數。舉例來說，請嘗試 BUILDING，並嘗試在可視區域中填入建築物，看看這會如何影響分數。

4. 視覺化呈現 Geospatial Depth API 資料

啟用 Geospatial 和 Streetscape Geometry API 後，Geospatial Depth API 可提升深度讀數準確度。如要搭配 Kotlin 和 Android Studio 使用 Geospatial Depth 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。

將 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 中顯示的內容完全一致。

啟用必要設定

如要使用 Geospatial Depth API，您必須在應用程式的會期設定中啟用三項設定。

如要啟用這些通知，請按照下列步驟操作：

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

   // TODO: Enable the Geospatial API, the Streetscape Geometry API, and the Depth API.
   

2. 在下一行中新增下列程式碼：

   val isDepthSupported = session.isDepthModeSupported(Config.DepthMode.AUTOMATIC)
   val isGeospatialSupported = session.isGeospatialModeSupported(Config.GeospatialMode.ENABLED)
   if (isDepthSupported && isGeospatialSupported) {
     // These three settings are needed to use Geospatial Depth.
     geospatialMode = Config.GeospatialMode.ENABLED
     streetscapeGeometryMode = Config.StreetscapeGeometryMode.ENABLED
     depthMode = Config.DepthMode.AUTOMATIC
   }
   

以視覺化方式呈現深度資訊

1. 執行應用程式，並前往您所在地區的建築物。
2. 完成地理空間定位後，輕觸「設定」，然後啟用地理空間深度視覺化功能。
3. 以 AR 檢視建築物，並與沒有地理空間深度資訊的深度資訊進行比較。

5. 結語

恭喜！您已建構 AR 應用程式，可將場景語意和地理空間深度視覺化！

瞭解詳情

• Scene Semantics API 開發人員指南
• Geospatial Depth API 開發人員指南