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

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

前提条件

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

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

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

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

请确保您的开发环境满足 ARCore SDK 要求，因为 Java 快速入门中的说明。

启用 ARCore API

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

首选无密钥授权，但也支持 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 时，应用可以获取 来自视觉定位系统 (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, 如上所示您必须 配置这两项位置信息权限。

但是，当用户指定粗略位置时，这样做会阻止地理空间 API 获取其所需的精确位置。地理空间服务 如果您的应用仅提供粗略位置，则不允许自行配置。 您的应用不能将 Geospatial API 用于粗略位置信息。

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

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

Geospatial API 也可用于没有 VPS 覆盖的区域。在顶部障碍很少或没有障碍物的户外环境中，GPS 可能足以生成高精度姿势。

后续步骤