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

1. 概览

ARCore 是 Google 推出的一个框架,用于在智能手机上打造增强现实体验。全新的 ARCore Geospatial API 为增强现实赋予了全新的面貌,让您能够在真实地标周围放置特定于位置的增强现实航点。

构建内容

在此 Codelab 中,您首先会了解如何使用 ARCore Geospatial API。您将探索 Geospatial API 可以为您的整体 AR 体验提供哪些信息,以及如何利用这些数据为简单的 AR 寻路体验提供支持。

学习内容

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

所需条件

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“Get from VCS”的位置
  2. 选择 Git,然后使用网址 https://github.com/google-ar/codelab-geospatial.git 导入项目。

设置 Google Cloud 项目

Geospatial API 将街景图像与设备的磁力计和相机传感器信息相结合,以改进屏幕方向值。如需使用此服务,您需要设置一个 Google Cloud 项目。

  1. 在 Google Cloud 控制台中创建一个项目:
  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.

在它下方,检查地球对象是否可供使用。那时候可以有 trackingStateTrackingState.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. 使用地球坐标放置锚点

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

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

设置用户点按地图时执行的操作

该项目包含一个 onMapClick 函数,当用户点击地图 fragment 时,系统会通过纬度和经度调用该函数。在 HelloGeoRenderer.kt 中查找 onMapClick 函数。

确保 Google 地球对象可以使用

在 Google 地球上创建锚点之前,请确保地球对象的 TrackingStateTRACKING,这意味着地球的位置是已知的。此外,还要确保其 EarthStateENABLED,这意味着使用 Geospatial API 时不会遇到问题。在 onMapClick 中添加以下代码行:

val earth = session?.earth ?: return
if (earth.trackingState != TrackingState.TRACKING) {
  return
}

确定新锚点的定位

确认 Google 地球对象正在跟踪后,分离之前的 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,请参阅下列其他资源: