使用新的 ARCore Geospatial API 构建增强现实 (AR) 应用

1. 概览

ARCore 是 Google 推出的一个框架，用于在智能手机上打造增强现实体验。借助全新的 ARCore Geospatial API，增强现实技术将迎来新的发展，让您可以在现实世界地标周围放置特定于位置的增强现实航点。

构建内容

在此 Codelab 中，您将开始使用 ARCore Geospatial API。您将了解 Geospatial API 可以为您的整体 AR 体验提供哪些信息，以及如何使用这些数据来打造简单的 AR 寻路体验。

学习内容

• 如何设置使用 Geospatial API 的 ARCore 项目。
• 如何从 Geospatial API 请求地理数据并使用 Google 地图显示这些数据。
• 如何放置附着到现实世界位置的锚点。

所需条件

• 一台支持 ARCore 的 Android 设备，且该设备已通过 USB 线连接到开发机器并配置了 USB 调试功能。
• 安装并配置了用于构建 Android 应用的 Android Studio。
• Android 开发设备上已安装面向 AR 的 Google Play 服务 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 会使用 StreetView 图像，并结合设备的磁力计和摄像头传感器信息来改进方向值。如需使用此服务，您需要设置 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.

在下方，检查地球对象是否可供使用。即，当它具有 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 中，点击播放。举起设备并四处移动，以帮助 ARCore 建立跟踪。过一会儿，您应该会在地图上看到一个绿色标记。此标记会随着您查看周围环境而旋转。它还应指向正确的方向：当您面向正北方时，箭头也指向正北方。

4. 使用地球坐标放置锚点

Geospatial API 可在现实世界中的任何坐标对和旋转位置放置锚点。这样，用户在访问特定地点时就能看到锚定内容。

在此步骤中，您将添加一种通过点按地图来放置锚点的方法。

设置点按地图时的操作

该项目附带一个 onMapClick 函数，当点击地图 fragment 时，系统会使用纬度和经度调用该函数。在 HelloGeoRenderer.kt 中查找 onMapClick 函数。

确保可以使用 Earth 对象

在地球上创建锚点之前，请确保地球对象的 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] 变量用于确定锚点的以四元数表示的旋转（在 East-Up-South [EUS] 坐标系中）。您可以使用不同的值来旋转锚点，但在本例中，请使用单位四元数作为默认旋转。单位四元数旋转的锚点方向如下：X+ 指向东，Y+ 指向远离地球中心的方向，Z+ 指向南。

在地图上显示放置的标记

最后，移动一个新标记，以指示标记的放置位置：

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

试试看

在 Android Studio 中，点击播放。举起设备，然后四处移动，以帮助 ARCore 建立跟踪。稍后，您应该会在地图上看到一个绿色标记，表示您当前的位置。

点按地图会使用 Geospatial API 放置一个锚点，该锚点固定在现实世界中的某个位置。尝试将锚点放置在离您当前位置较近的位置，以便您在 AR 视图中看到它。在您浏览环境时，它应保持稳定。

5. 总结

在此 Codelab 中，您学习了如何使用 Geospatial API 创建与现实世界相关联的简单 AR 体验。

所学内容

• 如何设置启用了 Geospatial API 的 Google Cloud 项目。
• 如何在 ARCore 项目中获取地理空间信息并将其显示在地图上。
• 如何使用地理定位功能放置位于现实世界中的锚点。

其他资源

如需详细了解此 Codelab 中使用的地理位置概念和 SDK，请参阅以下其他资源：

• ARCore Geospatial API 文档
• 世界大地测量系统 (WGS)
• Google Maps SDK for Android