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

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

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

启用 ARCore API

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

添加其他库依赖项

使用 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")
}

请求所需权限

如需在 ARCore 中使用 Jetpack XR 的 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>

请求权限

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

除非能确定用户的精确位置，否则地理空间 API 无法正常运行。因此，请遵循在运行时请求位置权限的指南，以便您的应用可以同时获得 ACCESS_FINE_LOCATION 和 ACCESS_COARSE_LOCATION 权限。

访问会话

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

配置会话

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

// Define the configuration object to enable Geospatial features.
val newConfig = session.config.copy(
  // Set the GeospatialMode to VPS_AND_GPS.
  geospatial = Config.GeospatialMode.VPS_AND_GPS
  // Set the DeviceTrackingMode to LAST_KNOWN.
  deviceTracking = Config.DeviceTrackingMode.LAST_KNOWN
)

// Apply the configuration to the session.
try {
    when (val configResult = session.configure(newConfig)) {
        is SessionConfigureGooglePlayServicesLocationLibraryNotLinked -> {
            // This case generally indicates a missing library dependency.
        }
        is SessionConfigureSuccess -> {
            // The session is now configured to use the Geospatial API.
        }
        else -> {
            // Catch-all for other configuration errors returned using the result class.
        }
    }
} catch (e: UnsupportedOperationException) {
    // Handle configuration failure. For example, if the specific mode is not supported on the current device or API version.
}

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

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

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

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

获取地理空间对象

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

// Get the Geospatial instance
var geospatial = Geospatial.getInstance(session)

只有当 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 and check if it has VPS
val latitude = getLatitudeFromGPS()
val longitude = getLongitudeFromGPS()

// Must be called from a coroutine.
val result = geospatial.checkVpsAvailability(latitude, longitude)
if (result is VpsAvailabilityAvailable) {
  // VPS is available
} else if (result is VpsAvailabilityUnavailable) {
  // VPS is not available
}

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

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

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

这有助于您：

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

使用 Geospatial.createGeospatialPoseFromPose() 将设备姿势转换为地理空间姿势：

// Get the current device Pose from the AR Session's state
// This is the device's position and orientation relative to the AR tracking origin.
val devicePose = ArDevice.getInstance(session).state.value.devicePose

// Convert the device Pose into a GeospatialPose
when (val geospatialPoseResult = geospatial.createGeospatialPoseFromPose(devicePose)) {
    is CreateGeospatialPoseFromPoseSuccess -> {
        val currentGeospatialPose = geospatialPoseResult.pose
        val horizontalAccuracy = geospatialPoseResult.horizontalAccuracy
        // ... use pose and accuracy
     val latitude = currentGeospatialPose.latitude
     val longitude = currentGeospatialPose.longitude
    // The orientation is stored as a Quaternion in the EUS (East-Up-South) system. The EUS coordinate system has X+ pointing east, Y+ pointing up, and Z+ pointing south. True North is aligned with the -Z axis.
     val eusQuaternion = currentGeospatialPose.eastUpSouthQuaternion

    }
    is CreateGeospatialPoseFromPoseNotTracking -> {
        // Geospatial is not currently tracking
    }
}

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

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

使用 Geospatial.createPoseFromGeospatialPose() 将地理空间姿势转换为设备姿势：

when (val poseResult = geospatial.createPoseFromGeospatialPose(geospatialPose)) {
    is CreatePoseFromGeospatialPoseSuccess -> {
        val devicePose = poseResult.pose
    // devicePose is now ready to be used
    }
    is CreatePoseFromGeospatialPoseNotTracking -> {
        // Geospatial is not currently tracking
    }
}