使用 ARCore for Jetpack XR 處理地理空間姿勢

適用 XR 裝置
這份指南可協助您為這類 XR 裝置打造體驗。
瞭解 XR 裝置類型 →
AI 眼鏡
瞭解 XR 裝置類型 →

透過 Jetpack XR 的 ARCore Geospatial API，您的應用程式可以將內容遠端附加至 Google 街景服務涵蓋的任何區域，並在全球範圍內建立 AR 體驗。Geospatial API 會使用裝置感應器和 GPS 資料偵測裝置環境，然後將環境中可辨識的部分與 Google 視覺定位系統 (VPS) 提供的本地化模型比對，判斷使用者裝置的精確位置。API 也會負責將使用者的本機座標與 VPS 的地理座標合併，讓您可以在單一座標系統中作業。

啟用 ARCore API

如要在應用程式中使用 Visual Positioning System (VPS)，請先在新的或現有的 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>

要求權限

宣告必要權限後，應用程式必須在執行階段要求權限。請務必說明應用程式需要這些權限的原因。

如果無法判斷使用者的精確位置，Geospatial 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() 成功，裝置就會支援這些模式。

提示使用者允許使用裝置資料

如果應用程式使用 ARCore for Jetpack XR 的 Geospatial API，就必須向使用者顯示提示，要求他們確認並允許使用裝置資料。詳情請參閱使用者隱私權規定。

取得 Geospatial 物件

設定工作階段後，請使用 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
    }
}