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 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 :
ACCESS_INTERNET: obligatoire pour contacter le service cloud de l'API ARCore Geospatial.ACCESS_COARSE_LOCATION: obligatoire pour déterminer la position approximative d'un utilisateur.ACCESS_FINE_LOCATION: obligatoire pour déterminer la position précise d'un utilisateur.
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 = 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.
}
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
var geospatial = Geospatial.getInstance(session)
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 spatiale, elle peut être utilisée tant que l'appareil est en mesure de 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 un lieu est couvert 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 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
}
Votre application doit être correctement configurée pour communiquer avec l'API ARCore sur Google Cloud. Sinon, elle recevra un résultat VpsAvailabilityNotAuthorized.
Convertir une pose d'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
// 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
}
}
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 AR 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() :
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
}
}