使用 ARCore for Jetpack XR 处理地理空间姿势

适用的 XR 设备
本指南可帮助您为以下类型的 XR 设备打造优质体验。
了解 XR 设备类型 →
AI 眼镜
了解 XR 设备类型 →

借助 ARCore for Jetpack XR 中的 Geospatial API，您的应用可以远程将 内容附加到 Google 街景覆盖的任何区域，并打造全球范围内的 AR 体验。Geospatial API 使用设备传感器和 GPS 数据来检测设备的环境，然后将该环境中可识别的部分与 Google Visual Positioning System (VPS) 提供的本地化模型进行匹配，以确定用户设备的精确位置。该 API 还会负责将用户的本地坐标与 VPS 中的地理坐标合并，以便您可以在单个坐标系中工作。

启用 ARCore API

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

添加其他库依赖项

使用 Geospatial API 需要一些额外的库依赖项。将这些依赖项添加到应用的 build.gradle.kts 文件中：

Groovy

dependencies {
  // ... Other required dependencies for the Jetpack XR SDK
  implementation "com.google.android.gms:play-services-location:21.3.0"
}

Kotlin

dependencies {
  // ... Other required dependencies for the Jetpack XR SDK
  implementation("com.google.android.gms:play-services-location:21.3.0")
}

请求所需权限

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

声明应用权限

在运行时请求这些权限之前，您需要声明 它们在应用的清单中：

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

请求权限

声明所需权限后，您的应用必须在运行时 请求这些权限。请务必说明您的应用需要这些权限的原因。

Geospatial API 必须能够确定用户的精确位置，否则无法正常运行。因此，请按照有关在运行时请求位置 权限的指南操作，以便您的应用可以获得 ACCESS_FINE_LOCATION和ACCESS_COARSE_LOCATION权限。

访问会话

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

配置会话

默认情况下，XR 会话中未启用设备姿态信息。如需让您的 应用能够检索设备姿态信息，请配置会话并同时设置 GeospatialMode.VPS_AND_GPS 和 DeviceTrackingMode.LAST_KNOWN 模式：

// Define the configuration object to enable Geospatial features.
val newConfig = Config(
    // Set the GeospatialMode to VPS_AND_GPS.
    geospatial = GeospatialMode.VPS_AND_GPS,
    // Set the DeviceTrackingMode to LAST_KNOWN.
    deviceTracking = DeviceTrackingMode.LAST_KNOWN
)
// 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.
}
Geospatial.kt

GeospatialMode.VPS_AND_GPS 模式会同时利用Visual Positioning System (VPS) 和 全球定位系统 (GPS) 数据来准确确定设备的地理空间位置。

并非所有 XR 设备都支持 GeospatialMode.VPS_AND_GPS 和 DeviceTrackingMode.LAST_KNOWN 模式。如果 Session.configure() 成功， 则表示设备支持这些模式。

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

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

获取 Geospatial 对象

会话配置完成后，使用 Geospatial.getInstance(session)获取Geospatial对象：

// Get the Geospatial instance for the current session.
val geospatial = Geospatial.getInstance(session)
Geospatial.kt

Geospatial 对象只能在其状态为 State.RUNNING时使用。您可以使用 Geospatial.state StateFlow<Geospatial.State> 监控状态。

检查 VPS 可用性

由于 Geospatial API 结合使用了 VPS 和 GPS 来确定地理空间姿态，因此只要设备可以 确定其位置，该 API 即可使用。在 GPS 精度较低的区域（例如室内空间和密集的城市环境），该 API 依赖于 VPS 覆盖范围来生成高精度姿态。

在典型条件下，您可以预期 VPS 提供约 5 米的位置精度和 5 度的旋转精度。您可以使用挂起函数Geospatial.checkVpsAvailability(latitude, longitude)检查某个 位置是否具有 VPS 覆盖范围。此调用是 异步操作，不需要使用 GeospatialMode.VPS_AND_GPS 模式配置会话。

以下代码演示了如何从指定的纬度和经度检查 VPS 可用性：

// You can query the GPS to get the current device's location.
val latitude = 37.422
val longitude = -122.084

// Use the geospatial instance to check VPS availability for a specific location.
val result = geospatial.checkVpsAvailability(latitude, longitude)
when (result) {
    is VpsAvailabilityAvailable -> {
        // VPS is available at this location.
    }
    is VpsAvailabilityErrorInternal -> {
        // VPS availability check failed with an internal error.
    }
    is VpsAvailabilityNetworkError -> {
        // VPS availability check failed due to a network error.
    }
    is VpsAvailabilityNotAuthorized -> {
        // VPS availability check failed due to an authorization error.
    }
    is VpsAvailabilityResourceExhausted -> {
        // VPS availability check failed due to resource exhaustion.
    }
    is VpsAvailabilityUnavailable -> {
        // VPS is not available at this location.
    }
}
Geospatial.kt

您的应用必须正确设置为与 Google Cloud 上的 ARCore API 通信；否则，您的应用会收到 VpsAvailabilityNotAuthorized 结果。

将设备姿态转换为地理空间姿态

您可以将设备姿态转换为地理空间姿态，以使 AI 眼镜能够与位置感知数据进行交互和生成位置感知数据。此流水线会将设备在本地坐标系中的当前位置和方向（设备姿态）转换为全球认可的坐标。

这可以帮助您：

  • 创作持久性 AR 内容，其中用户放置的虚拟对象会准确锚定到全球位置，以便日后检索。
  • 通过在地图上不断更新用户的位置来触发基于位置的体验，以实现实时导航或地理围栏游戏。
  • 确定用户的精确真实世界情境，以触发与位置相关的应用逻辑。

如需使用 Geospatial.createGeospatialPoseFromPose()将设备姿态转换为地理空间姿态，请执行以下操作：

// Get the current device Pose from the AR Session's state.
val devicePose = ArDevice.getInstance(session).state.value.devicePose

// Convert the device Pose into a GeospatialPose.
when (val result = geospatial.createGeospatialPoseFromPose(devicePose)) {
    is CreateGeospatialPoseFromPoseSuccess -> {
        val geoPose = result.pose
        val lat = geoPose.latitude
        val lon = geoPose.longitude
        val alt = geoPose.altitude
        // Orientation is in the EUS (East-Up-South) coordinate system.
        val orientation = geoPose.eastUpSouthQuaternion
    }
    is CreateGeospatialPoseFromPoseNotTracking -> {
        // Geospatial is not currently tracking.
    }
}
Geospatial.kt

将地理空间姿态转换为设备姿态

您可以将地理空间姿态转换为设备姿态，以帮助在 AI 眼镜上提供情境化、位置感知体验。此转换会获取由真实世界坐标定义的信息（例如地标的位置、导航路径或持久性 AR 内容），并将其转换为用户眼镜的精确视觉空间。

如需使用 Geospatial.createPoseFromGeospatialPose()将地理空间姿态转换为设备姿态，请执行以下操作：

// Convert a GeospatialPose (lat/long/alt) back to a device-space Pose.
when (val result = geospatial.createPoseFromGeospatialPose(geoPose)) {
    is CreatePoseFromGeospatialPoseSuccess -> {
        val devicePose: Pose = result.pose
        // devicePose is now ready to be used relative to the tracking origin.
    }
    is CreatePoseFromGeospatialPoseNotTracking -> {
        // Geospatial is not currently tracking.
    }
}
Geospatial.kt