使用地理空間姿勢

適用的 XR 裝置
本指南可協助您為這類 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
    }
}