开始在 ARCore 中使用 Scene Semantics API 和 Geospatial Depth API

1. 准备工作

ARCore 是 Google 推出的一个框架，用于在智能手机上打造增强现实 (AR) 体验。Scene Semantics API 和 Geospatial Depth API 能够帮助您的 AR 体验了解用户周围的环境。

Scene Semantics API 使用机器学习 (ML) 模型来分析相机拍摄的图像并提供带像素标记的图像。它可以区分 11 种不同的户外标签。

Geospatial Depth API 将来自运动和任何有源硬件传感器的深度信息（例如飞行时间）与 Streetscape Geometry API 数据相结合，可以改善最远 65 米外的对深度的观测误差。

在本 Codelab 中，您将构建一个 AR 应用，将 Scene Semantics API 和 Geospatial Depth API 的结果进行可视化。

前提条件

• AR 基础知识

学习内容

• 如何激活 Scene Semantics API。
• 如何获取并可视化语义图像。
• 如何获取并可视化语义置信度图像。
• 如何确定某给定标签对应的像素百分值。
• 如何设置可以使用 ARCore Geospatial API 的 Google Cloud 项目。
• 如何启用 Geospatial Depth API。
• 如何可视化包含深度信息的图像。

所需条件

• 一台支持 ARCore 的 Android 设备，且该设备已通过 USB 线连接到开发机器并配置了 USB 调试功能。
• 该 Android 开发设备已安装面向 AR 的 Google Play 服务 1.37 或更高版本。
• 安装并配置了用于构建 Android 应用的 Android Studio。

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 机器学习模型的结果，该模型将 SemanticLabel Enum 分配给摄像头画面中的每一个像素。

要获取语义图像并将其显示在屏幕上，请按照下列步骤操作：

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. 在该行后，获得所选标签的普遍性：

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

3. 运行您的应用，并将摄像头对准外面不同的对象。当您查看不同类型的对象时，语义置信度的显示会发生变化。
4. 点按 设置启用语义置信度图像叠加层。

4. 可视化 Geospatial Depth API 数据

启用 Geospatial API 和 Streetscape Geometry API 后，Geospatial Depth API 可改进深度的测量。要将 Geospatial Depth API 与 Kotlin 和 Android Studio 结合使用，您需要一个 Google Cloud 项目。

设置 Google Cloud 项目

将 ARCore Geospatial API 关联到 Google Cloud，从而在 Google 街景覆盖的区域提供来自 Google Visual Positioning System (VPS) 的定位信息。

要在您的项目中使用此服务，请按照以下步骤操作：

1. 在 Google Cloud 中创建一个项目。
   
   
2. 在项目名称字段中，输入合适的名称，例如 ARCore Geospatial API project，然后选择任意位置。
3. 点击创建。
4. 在 Google Cloud 控制台的项目选择器页面中，点击创建项目。
5. 点击以下链接查看此项目的 ARCore API，然后点击 Enable:
   Enable ARCore API
6. 为您的项目创建一个 API 密钥：
   1. 在 API 和服务下，选择凭据。
   2. 点击创建凭据，然后选择 API 密钥。
   3. 请记录此密钥，因为稍后需要用到。

您已创建了用 API 密钥进行授权的 Google Cloud 项目，并且已准备好在示例项目中使用 Geospatial API。

将 API 密钥与 Android Studio 项目集成

要将 API 密钥从 Google Cloud 关联到您的项目，请按照以下步骤进行操作：

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 未初始化，请确保已精确按照 Google Cloud 中所示将 API 密钥插入到您的 AndroidManifest.xml 文件中。

启用所需配置

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. 在 CodelabRenderer.kt 文件中找到以下行：

   // TODO: Obtain depth information and display it.
   

2. 在下一行中，添加以下代码：

   try {
     frame.acquireDepthImage16Bits().use { image ->
       backgroundRenderer.updateCameraDepthTexture(depthImage)
     }
   } catch (e: NotYetAvailableException) {
     // No depth information is available.
   }
   

3. 运行您的应用并访问您所在区域的一个建筑物。
4. 完成地理空间定位之后，点按 设置，然后启用地理空间深度可视化。
5. 在 AR 中查看选定的建筑物，并将它与没有地理空间深度的深度信息进行比较。

5. 总结

恭喜！您构建了可以直观呈现场景语义和地理空间深度的 AR 应用！

了解详情

• Scene Semantics API 开发者指南
• Geospatial Depth API 开发者指南