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 de l'appareil et du GPS 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 afin de déterminer la position précise 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 chargé d'héberger, de stocker et de résoudre les 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 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 lors de l'exécution, vous devez déclarer les 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 lors 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 instructions pour demander des autorisations de localisation lors 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 une 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 à la fois les données du système VPS (Visual Positioning System) et du GPS (Global Positioning System) pour déterminer avec précision 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 présenter à l'utilisateur une invite lui demandant d'accepter et d'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é du 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 positionnement d'environ 5 mètres et une précision de rotation de 5 degrés. Vous pouvez vérifier si un emplacement est couvert par le VPS à l'aide de la fonction suspendue Geospatial.checkVpsAvailability(latitude, longitude). Cet appel est une opération asynchrone et ne nécessite pas que la session soit configurée avec le GeospatialMode.VPS_AND_GPS mode.

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 reçoit un résultat VpsAvailabilityNotAuthorized.

Convertir une pose d'appareil en pose géospatiale

Vous pouvez convertir une pose d'appareil en pose géospatiale pour permettre aux lunettes IA d'interagir avec des données tenant compte de la position 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éer du contenu de RA persistant, où l'objet virtuel placé par un utilisateur est ancré avec précision à un emplacement mondial pour une récupération ultérieure ;
  • déclencher des expériences basées sur la position en mettant à jour en permanence la position de l'utilisateur sur une carte pour activer la navigation en temps réel ou le gameplay géolocalisé ;
  • déterminer le contexte précis de l'utilisateur dans le monde réel pour déclencher une logique d'application pertinente en fonction de la position.

Pour convertir une pose d'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 d'appareil

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

Pour convertir une pose géospatiale en pose d'appareil à l'aide 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