使用新的 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 导入项目。
   • 如果您已经打开了一个项目，请使用文件 >新建 >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 Console 中创建项目：
   • 参阅在 Google Cloud Platform 中创建项目。
     
   • 输入适当的项目名称（例如“ARCore Geospatial API project”），然后选择任意位置。
   • 点击创建。
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. 打开应用程序 >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 地球对象

在 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。此锚点尝试保持稳定并固定在指定坐标和海拔高度。

[qx, qy, qz, qw] 变量用于确定锚点在东上南 (EUS) 坐标系中以四元数表示的旋转角度。您可以使用不同的值来旋转锚点，但在此示例中，请使用单位四元数进行默认旋转。单位四元数旋转的锚点朝向：X+ 指向东，Y+ 指向远离地球中心，Z+ 指向南。

在地图上显示放置的标记

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

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)
• Google Maps SDK for Android