Utiliser des poses géospatiales avec ARCore pour Jetpack XR

Appareils XR concernés
Ces conseils vous aident à créer des expériences pour ces types d'appareils XR.
En savoir plus sur les types d'appareils XR →
Lunettes IA
En savoir plus sur les types d'appareils XR →

Avec l'API Geospatial dans ARCore pour Jetpack XR, votre application peut associer à distance du contenu à n'importe quelle zone couverte par Google Street View et créer des expériences de RA à l'échelle mondiale. L'API Geospatial utilise les données des capteurs et du GPS de l'appareil pour détecter l'environnement de l'appareil, puis fait correspondre les parties reconnaissables de cet environnement à un modèle de localisation fourni par le système VPS (Visual Positioning System) de Google pour déterminer la position exacte de l'appareil d'un utilisateur. L'API se charge également de fusionner les coordonnées locales de l'utilisateur avec les coordonnées géographiques du VPS afin que vous puissiez travailler dans un seul système de coordonnées.

Activer l'API ARCore

Avant d'utiliser le système VPS (Visual Positioning System) dans votre application, vous devez d'abord activer l'API ARCore dans un projet Google Cloud nouveau ou existant. Ce service est responsable de l'hébergement, du stockage et de la résolution des ancres géospatiales.

Ajouter des dépendances de bibliothèque supplémentaires

L'utilisation de l'API Geospatial nécessite des dépendances de bibliothèque supplémentaires. Ajoutez les éléments suivants au fichier build.gradle.kts de votre application :

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

Demander les autorisations requises

Pour utiliser l'API Geospatial dans ARCore avec Jetpack XR, votre application doit demander les autorisations d'exécution suivantes :

Déclarer des autorisations d'applications

Avant de pouvoir demander ces autorisations au moment de l'exécution, vous devez les déclarer dans le fichier manifeste de votre application :

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

Demander des autorisations

Après avoir déclaré les autorisations requises, votre application doit les demander au moment de l'exécution. Veillez à expliquer pourquoi votre application a besoin de ces autorisations.

L'API Geospatial ne peut pas fonctionner si elle ne peut pas déterminer la position précise de l'utilisateur. Pour cette raison, suivez les conseils pour demander des autorisations d'accéder à la position au moment de l'exécution afin que votre application puisse obtenir les autorisations ACCESS_FINE_LOCATION et ACCESS_COARSE_LOCATION.

Accéder à une session

Accédez aux informations géospatiales via un Session Jetpack XR Runtime que votre application doit créer.

Configurer la session

Les informations sur la pose de l'appareil ne sont pas activées par défaut dans les sessions XR. Pour permettre à votre application de récupérer des informations sur la pose de l'appareil, configurez la session et définissez les modes GeospatialMode.VPS_AND_GPS et DeviceTrackingMode.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.
}
Geospatial.kt

Le mode GeospatialMode.VPS_AND_GPS exploite les données du service de positionnement visuel (VPS) et du système de positionnement mondial (GPS) pour déterminer précisément la position géospatiale de l'appareil.

Tous les appareils XR ne sont pas compatibles avec les modes GeospatialMode.VPS_AND_GPS et DeviceTrackingMode.LAST_KNOWN. Si Session.configure() réussit, l'appareil est compatible avec ces modes.

Inviter l'utilisateur à autoriser l'utilisation des données de l'appareil

Les applications qui utilisent l'API Geospatial avec ARCore pour Jetpack XR doivent inviter l'utilisateur à confirmer et autoriser l'utilisation des données de son appareil. Pour en savoir plus, consultez les exigences concernant la confidentialité des utilisateurs.

Obtenir l'objet Geospatial

Une fois la session configurée, obtenez l'objet Geospatial à l'aide de Geospatial.getInstance(session) :

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

L'objet Geospatial ne doit être utilisé que lorsque son état est State.RUNNING. Vous pouvez surveiller l'état à l'aide de Geospatial.state StateFlow<Geospatial.State>.

Vérifier la disponibilité des VPS

Étant donné que l'API Geospatial utilise une combinaison de VPS et de GPS pour déterminer une pose géospatiale, elle est disponible chaque fois que l'appareil peut déterminer sa position. Dans les zones où la précision du GPS est faible, comme les espaces intérieurs et les environnements urbains denses, l'API s'appuie sur la couverture VPS pour générer des poses de haute précision.

Dans des conditions normales, vous pouvez vous attendre à ce que le VPS offre une précision de position d'environ 5 mètres et une précision de rotation de 5 degrés. Vous pouvez vérifier si une zone est couverte par le VPS à l'aide de la fonction de suspension Geospatial.checkVpsAvailability(latitude, longitude). Cet appel est une opération asynchrone et ne nécessite pas que la session soit configurée avec le mode GeospatialMode.VPS_AND_GPS.

Le code suivant montre comment vérifier la disponibilité du VPS à partir d'une latitude et d'une longitude spécifiées :

// 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.
    }
}
Geospatial.kt

Votre application doit être correctement configurée pour communiquer avec l'API ARCore sur Google Cloud. Sinon, elle recevra un résultat VpsAvailabilityNotAuthorized.

Convertir la pose d'un appareil en pose géospatiale

Vous pouvez convertir la pose d'un appareil en pose géospatiale pour permettre aux lunettes d'IA d'interagir avec des données tenant compte de la localisation et d'en générer. Ce pipeline traduit la position et l'orientation actuelles de l'appareil dans son système de coordonnées local (pose de l'appareil) en coordonnées reconnues à l'échelle mondiale.

Cela peut vous aider à :

  • Créez du contenu de RA persistant, où l'objet virtuel placé par un utilisateur est précisément ancré à un emplacement mondial pour une récupération ultérieure.
  • Déclenchez des expériences basées sur la position en actualisant en permanence la position de l'utilisateur sur une carte pour permettre la navigation en temps réel ou le gameplay géo-clôturé.
  • Déterminez le contexte précis de l'utilisateur dans le monde réel pour déclencher la logique d'application pertinente en fonction de la position.

Pour convertir une pose de l'appareil en pose géospatiale à l'aide de 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.
    }
}
Geospatial.kt

Convertir une pose géospatiale en pose de l'appareil

Vous pouvez convertir une pose géospatiale en pose d'appareil pour proposer des expériences contextuelles et géolocalisées sur des lunettes d'IA. Cette transformation prend les informations définies par des coordonnées réelles (comme l'emplacement d'un point de repère, un itinéraire de navigation ou du contenu RA persistant) et les convertit en espace visuel précis des lunettes de l'utilisateur.

Pour convertir une pose géospatiale en pose de l'appareil à l'aide de 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.
    }
}
Geospatial.kt