使用新的 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 项目

Geospatial API 会将街景图片与设备的磁力计和摄像头传感器信息相结合，以改进方向值。如需使用此服务，您需要设置一个 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 Maps 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 中，点击 Play。拿起您的设备并四处移动，帮助 ARCore 建立跟踪。片刻之后，您应该会在地图上看到一个绿色标记。此标记会随着您查看周围环境而旋转。它还应指向正确的方向：当您实际面向北方时，箭头也应指向北方。

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

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

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

设置点按地图时的操作

该项目附带一个 onMapClick 函数，系统会在点击地图 fragment 时使用纬度和经度调用该函数。在 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。此锚点会尝试保持稳定，并固定在指定的坐标和海拔。

在地图上显示放置的标记

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

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

试试看

在 Android Studio 中，点击 Play。举起设备并移动设备，以帮助 ARCore 建立跟踪。片刻后，地图上应该会显示一个绿色标记，表示您当前的位置。

点按地图会使用 Geospatial API 来放置固定在实际地点上的锚点。请尝试将锚点放置在您当前位置附近，以便您在 AR 视图中看到它。在您浏览环境时，它应保持稳定。

5. 总结

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

所学内容

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

其他资源

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

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