Jetpack XR 用 ARCore を使用して地理空間ポーズを操作する

対応する XR デバイス
このガイダンスは、次のようなタイプの XR デバイス向けのエクスペリエンスを構築する際に役立ちます。
AI グラス

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 アンカーのホスト、保存、解決を行います。

追加のライブラリの依存関係を追加する

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

GeospatialMode.VPS_AND_GPS モードでは、Visual Positioning System(VPS) データとグローバル ポジショニング システム(GPS) データの両方を利用して、デバイスの地理空間位置を正確に特定します。

すべての XR デバイスが GeospatialMode.VPS_AND_GPS モードと DeviceTrackingMode.LAST_KNOWN モードをサポートしているわけではありません。Session.configure() が成功した場合、 デバイスはこれらのモードをサポートしています。

デバイスデータの使用を許可するようユーザーに求める

Jetpack XR 用 ARCore で Geospatial API を使用するアプリは、デバイスのデータの使用を承認して許可するようユーザーに求めるプロンプトを表示する必要があります。 詳しくは、ユーザーのプライバシー要件をご覧ください。

Geospatial オブジェクトを取得する

セッションが構成されたら、Geospatial オブジェクトを Geospatial.getInstance(session) 使用して取得します。

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

Geospatial オブジェクトは、状態が State.RUNNINGの場合にのみ使用してください。状態は、 Geospatial.state StateFlow<Geospatial.State> を使用してモニタリングできます。

VPS の可用性を確認する

Geospatial API は VPS と GPS を組み合わせて Geospatial ポーズを特定するため、デバイスが 位置を特定できる場合は常に API を使用できます。屋内空間や密集した都市環境など、GPS の精度が低いエリアでは、API は VPS カバレッジに依存して高精度のポーズを生成します。

通常、VPS は位置精度が約 5 メートル、回転精度が 5 度です。位置に VPS カバレッジがあるかどうかは、一時停止関数 Geospatial.checkVpsAvailability(latitude, longitude)を使用して確認できます。この呼び出しは非同期オペレーションであり、 セッションを 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.
    }
}

アプリが 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.
    }
}

地理空間のポーズをデバイスのポーズに変換する

地理空間のポーズをデバイスのポーズに変換すると、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.
    }
}