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 = 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.
}
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
var 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, se puede usar la API siempre que el dispositivo pueda determinar su ubicación. En áreas con baja precisión del GPS, como espacios interiores y entornos urbanos densos, la API se basa en la cobertura del VPS para generar poses de alta precisión.
En condiciones típicas, puedes esperar 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 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
}
Tu app debe estar configurada correctamente para comunicarse con la API de ARCore en Google Cloud. De lo contrario, recibirá un resultado de 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 datos basados en 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
// 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
}
}
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:
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
}
}