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

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

前提条件

确保您了解 AR 基本概念 以及如何在继续之前配置 ARCore 现场录像。

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

请参阅 Geospatial API 简介，了解详情 有关 Geospatial API 的信息。

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

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

启用 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，因为 请参阅快速入门 。

如需检查用户设备的兼容性，请调用 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 可能足以生成高精度姿势。

后续步骤