在应用中设置 Geospatial API

适用的 XR 设备

本指南可帮助您为以下类型的 XR 设备打造优质体验。

了解 XR 设备类型 →

了解 XR 设备类型 →

如需在应用中使用 Geospatial API，您必须将应用设置为访问 Google Cloud 上的 ARCore API。此 API 包含视觉定位服务，该服务使用来自 Google 街景的数据提供准确的定位。

本指南可帮助您设置已启用正确 API 和授权方法的 Google Cloud 云项目，以便访问该 API。

设置 Google Cloud 项目或使用现有项目

如果您已有 Google Cloud 项目，请选择该项目。

转到“项目选择器”

如果您还没有项目，请创建一个。

创建新项目

启用 ARCore API

如需使用 ARCore API，您必须在项目中启用它。

启用 ARCore API

为 Google Cloud 设置授权

Android 应用可以使用两种不同的授权方法与 ARCore API 通信：无密钥授权 (OAuth 2.0)（推荐方法）和 API 密钥授权：

• 无密钥授权结合使用应用的软件包名称和签名密钥的指纹来为应用授权。

• API 密钥是用于标识 Google Cloud 项目的字符串。API 密钥通常不被视为安全，因为客户端通常可以访问它们。考虑使用无密钥授权与 ARCore API 通信。

<meta-data
  android:name="com.google.android.ar.API_KEY"
  android:value="API_KEY"/>

请求所需权限

如需在 ARCore 中将 Geospatial API 与 Jetpack XR 搭配使用，您的应用需要请求以下运行时权限：

• ACCESS_FINE_LOCATION：确定用户的精确位置时需要。

在移动设备上，Geospatial API 还需要以下权限：

• android.permission.CAMERA：访问设备摄像头时需要。
• android.permission.INTERNET：与 Google Cloud 服务通信时需要。

访问会话

通过 Jetpack XR 运行时 Session 访问地理空间信息，该运行时必须由您的应用创建。

配置会话

默认情况下，XR 会话中未启用 Geospatial API。您的应用必须通过在 Session 上配置 GeospatialMode 来明确启用该功能。可用的模式有：

• GeospatialMode.SPATIAL：Geospatial API 已启用。Geospatial API 使用视觉定位系统 (VPS)、全球定位系统 (GPS) 数据和设备的移动传感器来确定设备的地理空间姿态。此模式不适用于智能眼镜设备。
• GeospatialMode.INERTIAL：Geospatial API 在低功耗模式下启用。Geospatial API 仅使用 GPS 和设备的移动传感器来确定设备的地理空间姿态。此模式仅适用于智能眼镜设备。
• GeospatialMode.DISABLED：Geospatial API 已停用；从其他模式转换到此模式时，Geospatial API 会释放所有获取的资源并停止跟踪。

并非所有设备都支持所有地理空间模式。如需了解详情，请参阅 GeospatialMode。使用 XrDevice.isGeospatialSupported 检查是否支持给定的 GeospatialMode。

以下代码示例演示了如何使用 Session.configure 设置 GeospatialMode。

// Define the configuration object to enable Geospatial features.
val newConfig = Config.Builder(session.config)
    .setGeospatial(GeospatialMode.SPATIAL)
    .build()
// Apply the configuration to the session.
try {
    when (val configResult = session.configure(newConfig)) {
        is SessionConfigureSuccess -> {
            // The session is now configured to use the Geospatial API.
        }

        else -> {
            // Handle other configuration errors (e.g., missing library dependencies).
        }
    }
} catch (e: UnsupportedOperationException) {
    // Handle configuration failure if the mode is not supported.
}
Setup.kt

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

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

使用 Geospatial 对象

会话配置完成后，使用 Geospatial.getInstance 获取 Geospatial 对象。仅当 Geospatial 对象的状态为 GeospatialTrackingState.RUNNING 时，才使用该对象。

以下代码示例演示了如何使用 Geospatial.state 监控地理空间状态。

val geospatial = remember { Geospatial.getInstance(session) }
val geospatialState by geospatial.state.collectAsStateWithLifecycle()
if (geospatialState.geospatialTrackingState == Geospatial.GeospatialTrackingState.RUNNING) {
    // Queries to the Geospatial API are only valid when the state is RUNNING.
}
Setup.kt

val geospatial = Geospatial.getInstance(session)
lifecycleScope.launch {
    geospatial.state.collect { geospatialState ->
        if (geospatialState == Geospatial.GeospatialTrackingState.RUNNING) {
            // Queries to the Geospatial API are only valid when the state is RUNNING.
        }
    }
}
Setup.kt

了解准确率值

启用 Geospatial API 后，它会提供三个精确度值：水平精确度、垂直精确度和方向精确度。这些准确度值会随着时间的推移而更新，并且随着获取的数据越来越多，这些值会变得更加精确。值越大，表示准确度越低，并定义为 68% 置信度的半径。换句话说，真实值在估计值的给定半径范围内的概率为 68%。

使用 Geospatial.State.horizontalAccuracy、verticalAccuracy 和 orientationYawAccuracy 可获取当前精确度值。

您的应用可能需要特定级别的精确度才能正常运行。例如，您的应用可能需要等到水平精确度小于 5 米时，再渲染虚拟内容。为了提高获得更高准确度数据的可能性，您的应用应指示用户环顾四周，最好是查看 Google 街景中存在的建筑物或其他具有高度视觉细节的特征。使用 Geospatial.checkVpsAvailability 确定 VPS 在给定位置是否可用。

后续步骤

在应用中正确设置 Geospatial API 后，您的应用可以执行以下操作：

• 在设备本地姿态和地理空间姿态之间转换
• 在地理空间姿态下渲染内容