Con la API de Geospatial en ARCore para Jetpack XR, tu app puede adjuntar contenido de forma remota a cualquier área cubierta por Street View de Google y crear experiencias de RA a escala global. La API de Geospatial usa los datos del GPS y los sensores del dispositivo para detectar el entorno del dispositivo y, luego, correlaciona las partes reconocibles de ese entorno con un modelo de localización proporcionado por el sistema de posicionamiento visual (VPS) de Google para determinar la ubicación precisa del dispositivo de un usuario. La API también se encarga de combinar las coordenadas locales del usuario con las coordenadas geográficas del VPS para que puedas trabajar dentro de un solo sistema de coordenadas.
Habilita la API de ARCore
Antes de usar el sistema de posicionamiento visual (VPS) en tu app, primero debes habilitar la API de ARCore en un proyecto de Google Cloud nuevo o existente. Este servicio es responsable de alojar, almacenar y resolver anclajes geoespaciales.
Agrega dependencias de bibliotecas adicionales
El uso de la API de Geospatial requiere algunas dependencias de biblioteca adicionales. Agrega lo siguiente al archivo build.gradle.kts de tu app:
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") }
Solicita los permisos necesarios
Para usar la API de Geospatial en ARCore con Jetpack XR, tu app debe solicitar los siguientes permisos de tiempo de ejecución:
ACCESS_INTERNET: Se requiere para comunicarse con el servicio en la nube de la API de ARCore Geospatial.ACCESS_COARSE_LOCATION: Se requiere para determinar la ubicación aproximada de un usuario.ACCESS_FINE_LOCATION: Se requiere para determinar la ubicación precisa de un usuario.
Cómo declarar permisos de la app
Antes de solicitar estos permisos en el tiempo de ejecución, debes declararlos en el manifiesto de tu app:
<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>
Solicita permisos
Después de declarar los permisos requeridos, tu app debe solicitarlos en el tiempo de ejecución. Asegúrate de explicar por qué tu app necesita los permisos.
La API de Geospatial no puede funcionar a menos que pueda determinar la ubicación precisa del usuario. Por este motivo, sigue la guía para solicitar permisos de ubicación en el tiempo de ejecución, de modo que se le puedan otorgar a tu app los permisos ACCESS_FINE_LOCATION y ACCESS_COARSE_LOCATION.
Cómo acceder a una sesión
Acceder a la información geoespacial a través de un Session de Jetpack XR Runtime, que debe crear tu app
Configura la sesión
La información de la posición del dispositivo no está habilitada de forma predeterminada en las sesiones de XR. Para permitir que tu app recupere información sobre la postura del dispositivo, configura la sesión y establece los modos GeospatialMode.VPS_AND_GPS y 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. }
El modo GeospatialMode.VPS_AND_GPS aprovecha los datos del Visual Positioning System (VPS) y del Global Positioning System (GPS) para determinar con precisión la posición geoespacial del dispositivo.
No todos los dispositivos XR admiten los modos GeospatialMode.VPS_AND_GPS y DeviceTrackingMode.LAST_KNOWN. Si Session.configure() se ejecuta correctamente, el dispositivo admite estos modos.
Solicitar al usuario que permita el uso de los datos del dispositivo
Las apps que usan la API de Geospatial con ARCore para Jetpack XR deben mostrarle al usuario un mensaje para que confirme y permita el uso de datos de su dispositivo. Consulta los requisitos de privacidad del usuario para obtener más información.
Obtén el objeto Geospatial
Una vez que se configura la sesión, obtén el objeto Geospatial con Geospatial.getInstance(session):
// Get the Geospatial instance for the current session. val geospatial = Geospatial.getInstance(session)
El objeto Geospatial solo debe usarse cuando su estado es State.RUNNING. Puedes supervisar el estado con Geospatial.state StateFlow<Geospatial.State>.
Verifica la disponibilidad de la VPS
Dado que la API de Geospatial usa una combinación de VPS y GPS para determinar una postura Geospatial, la API está disponible siempre que el dispositivo pueda determinar su ubicación. En las áreas con baja precisión del GPS, como los espacios interiores y los entornos urbanos densos, la API se basa en la cobertura del VPS para generar poses de alta precisión.
En condiciones típicas, se espera que el VPS proporcione una precisión posicional de aproximadamente 5 metros y una precisión rotacional de 5 grados. Puedes verificar si una ubicación tiene cobertura del VPS con la función de suspensión Geospatial.checkVpsAvailability(latitude, longitude). Esta llamada es una operación asíncrona y no requiere que la sesión se configure con el modo GeospatialMode.VPS_AND_GPS.
En el siguiente código, se muestra cómo verificar la disponibilidad del VPS a partir de una latitud y longitud especificadas:
// 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. } }
Tu app debe estar configurada correctamente para comunicarse con la API de ARCore en Google Cloud. De lo contrario, recibirá un resultado VpsAvailabilityNotAuthorized.
Cómo convertir la posición de un dispositivo en una posición geoespacial
Puedes convertir la postura del dispositivo en una postura geoespacial para permitir que los lentes con IA interactúen con los datos que tienen en cuenta la ubicación y los generen. Esta canalización traduce la posición y la orientación actuales del dispositivo en su sistema de coordenadas local (pose del dispositivo) en coordenadas reconocidas a nivel global.
Esto puede ayudarte a hacer lo siguiente:
- Crea contenido de RA persistente, en el que el objeto virtual que coloca un usuario se ancla con precisión a una ubicación global para su posterior recuperación.
- Activa experiencias basadas en la ubicación actualizando continuamente la posición del usuario en un mapa para habilitar la navegación en tiempo real o el juego con límites geográficos.
- Determina el contexto preciso del mundo real del usuario para activar la lógica de la aplicación pertinente para la ubicación.
Para convertir una posición del dispositivo en una posición geoespacial con Geospatial.createGeospatialPoseFromPose(), haz lo siguiente:
// 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. } }
Cómo convertir una posición geoespacial en una posición del dispositivo
Puedes convertir una postura geoespacial en una postura del dispositivo para ofrecer experiencias contextuales y basadas en la ubicación en lentes con IA. Esta transformación toma la información definida por coordenadas del mundo real, como la ubicación de un punto de referencia, una ruta de navegación o contenido persistente de RA, y la convierte en el espacio visual preciso de los lentes del usuario.
Para convertir una posición geoespacial en una posición del dispositivo con Geospatial.createPoseFromGeospatialPose(), haz lo siguiente:
// 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. } }