为您的 Android NDK 应用启用 Geospatial API (C)

配置应用的设置，以便其可以使用 Geospatial API。

前提条件

在继续操作之前，请确保您了解基本 AR 概念以及如何配置 ARCore 会话。

如果您想运行演示此处所述功能的示例应用，请参阅适用于 Java 的 Android 版 ARCore 地理空间快速入门。快速入门中的示例应用是使用 Java 编写的。本文档中的代码示例针对使用 C 语言编写的相同功能。

如需详细了解 Geospatial API，请参阅 Geospatial API 简介。

如果您刚开始使用 ARCore 进行开发，请参阅使用入门，了解软件和硬件要求、前提条件以及特定于您所用平台的其他信息。

请确保您的开发环境符合 Java 版 快速入门中所述的 ARCore SDK 要求。

启用 ARCore API

在应用中使用 Visual Positioning System (VPS) 之前，您必须先在新建或现有的 Google Cloud 项目中启用 ARCore API。此服务负责托管、存储和解析地理空间锚点。

首选无密钥授权，但也支持 API 密钥授权。

将所需的库添加到您的应用

授权应用调用 ARCore API 后，您必须添加库才能在应用中启用地理空间功能。

在应用的 build.gradle 文件中，设置 Google Play 服务以添加 Play 服务位置信息库。

dependencies {
  // Apps must declare play-services-location version >= 16.
  // In the following line, substitute `16 (or later)` with the latest version.
  implementation 'com.google.android.gms:play-services-location:16 (or later)'
}

在会话配置中启用地理空间功能

在创建会话之前，请将会话配置中的 GeospatialMode 更改为 ENABLED：

// Create a session config.
ArConfig* ar_config = NULL;
ArConfig_create(ar_session, &ar_config);

// Enable the Geospatial API.
ArConfig_setGeospatialMode(ar_session, ar_config, AR_GEOSPATIAL_MODE_ENABLED);
CHECK(ArSession_configure(ar_session, ar_config) == AR_SUCCESS);

// Release config resources.
ArConfig_destroy(ar_config);

当地理空间模式设置为 ENABLED 时，应用可以从 Visual Positioning System (VPS) 获取地理信息。

提示用户允许使用设备数据

使用 ARCore Geospatial API 的应用必须向用户显示提示，以便用户确认并允许使用其设备中的数据。如需了解详情，请参阅用户隐私权要求。

检查设备兼容性

并非所有支持 ARCore 的设备都支持 Geospatial API，如 Java 版快速入门中所述。

如需检查用户设备的兼容性，请调用 ArSession_isGeospatialModeSupported()。如果此方法返回 false，请勿尝试配置会话（见下文），因为这样做会导致 ArStatus 报告 AR_ERROR_UNSUPPORTED_CONFIGURATION。

在运行时向用户请求位置信息权限

您的应用必须在运行时请求位置信息权限。

如需使用 ARCore Geospatial API，您的应用需要注册以下额外权限：

  • ACCESS_FINE_LOCATION，以准确确定用户的位置。

  • ACCESS_COARSE_LOCATION，以非精确地确定用户的位置并遵守用户隐私权要求。不过，Geospatial API 无法配置为使用粗略位置信息，并且当用户设置此权限时，API 请求将会失败。如需了解详情，请参阅下文。

  • ACCESS_INTERNET 与 ARCore Geospatial API 服务联系。

<manifest ... >
  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
  <uses-permission android:name="android.permission.INTERNET" />
</manifest>

在搭载 Android 12 或更高版本的设备上，用户可以要求您的应用只能访问大致位置信息。为了满足此请求，您的应用必须配置 ACCESS_COARSE_LOCATION 权限以及 ACCESS_FINE_LOCATION，如上所示。您必须同时配置这两项位置信息权限。

不过，如果用户指定粗略位置，则会导致 Geospatial API 无法获取所需的精确位置。如果您的应用仅向地理空间服务提供粗略位置信息，地理空间服务将不允许自行配置。您的应用无法将 Geospatial API 与粗略位置信息搭配使用。

检查设备当前位置的地理空间可用性

由于 Geospatial API 会结合使用 VPS 和 GPS 来确定地理空间姿势，因此只要设备能够确定其位置，就可以使用该 API。在 GPS 精度较低的区域（例如室内空间和密集的城市环境）中，该 API 将依赖于 VPS 覆盖范围来生成高精度姿势。在典型条件下，VPS 预计可提供约 5 米的位置精度和 5 度旋转精度。使用 ArSession_checkVpsAvailabilityAsync() 确定给定位置是否有 VPS 覆盖。

Geospatial API 还可在未覆盖 VPS 的区域使用。在头顶上方没有或几乎没有遮挡物的室外环境中，GPS 可能就足以生成高精度的姿势。

后续步骤