使用地理空间姿势

适用的 XR 设备
本指南可帮助您为以下类型的 XR 设备打造优质体验。
了解 XR 设备类型 →
有线扩展现实眼镜
音频和
显示眼镜
了解 XR 设备类型 →

GeospatialPose 描述了空间中相对于地球的位置。它由以下组件组成：

  • 纬度和经度，以度为单位，如 WGS84 规范中所定义。
  • 海拔高度，以 WGS84 椭球体上方的米数指定，或大致相当于海拔高度。
  • 方向，大致表示姿态在 EUS 坐标系中的朝向。EUS 坐标系的 X+ 指向东，Y+ 指向上，Z+ 指向南。

Geospatial API 可提供对设备地理空间姿态的访问权限，并提供地理空间姿态与设备本地姿态之间的转换。

前提条件

为了获取和转换地理空间姿态，您的应用必须设置为使用 Geospatial API。只有当 Geospatial API 处于 RUNNING 状态时，才能获取地理空间姿态。

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

设备本地 Pose 可以转换为 GeospatialPose，例如，用于确定用户设备相对于地球的位置。这有助于您：

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

以下代码示例演示了如何使用 Geospatial.createGeospatialPoseFromPose() 将 Pose 转换为 GeospatialPose。

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.
    }

    else -> {
        // A newer exception was added, but your app is using an old version of the library
    }
}

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

您还可以将 GeospatialPose 转换为设备本地 Pose。此转换会获取由现实世界坐标定义的信息（例如地标位置、导航路径或持久性 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.
    }
    is CreatePoseFromGeospatialPoseInternalError -> {
        // An internal error occurred.
    }
    else -> {
        // A newer exception was added, but your app is using an old version of the library
    }
}