Trabaja con poses geoespaciales usando ARCore para Jetpack XR

Dispositivos de realidad extendida correspondientes
Esta guía te ayuda a crear experiencias para estos tipos de dispositivos de realidad extendida.
Más información sobre los tipos de dispositivos de realidad extendida →
Lentes de IA
Más información sobre los tipos de dispositivos de realidad extendida →

Con la API de Geospatial en ARCore para Jetpack XR, tu app puede adjuntar contenido de forma remota a cualquier área cubierta por Google Street View y crear experiencias de RA a escala global. La API de Geospatial usa datos de GPS y sensores del dispositivo para detectar el entorno del dispositivo y, luego, hace coincidir las partes reconocibles de ese entorno con un modelo de localización que proporciona 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 bibliotecas adicionales. Agrega estas 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:

Cómo declarar permisos de la app

Antes de que puedas solicitar estos permisos en el tiempo de ejecución, debes declarar them 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 necesarios, 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 las instrucciones para solicitar permisos de ubicación en el tiempo de ejecución para que tu app pueda obtener los permisos ACCESS_FINE_LOCATION y ACCESS_COARSE_LOCATION.

Accede a una sesión

Accede a la información geoespacial a través de un Jetpack XR Runtime Session, que tu app debe crear.

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 de la posición del dispositivo, configura la sesión y establece los modos GeospatialMode.VPS_AND_GPS y DeviceTrackingMode.SPATIAL_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 sistema de posicionamiento visual (VPS) y del sistema de posicionamiento global (GPS) para determinar con precisión la posición geoespacial del dispositivo.

No todos los dispositivos de XR admiten los modos GeospatialMode.VPS_AND_GPS y DeviceTrackingMode.SPATIAL_LAST_KNOWN. Si Session.configure() tiene éxito, el dispositivo admite estos modos.

Solicita al usuario que permita el uso de datos del dispositivo

Las apps que usan la API de Geospatial con ARCore para Jetpack XR deben presentar al usuario un mensaje para que reconozca 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 Geospatial objeto 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 el Geospatial.state StateFlow<Geospatial.State>.

Verifica la disponibilidad del VPS

Debido a que la API de Geospatial usa una combinación de VPS y GPS para determinar una posición geoespacial, la API está disponible siempre que el dispositivo pueda determinar su ubicación. En áreas con baja precisión de GPS, como espacios interiores y entornos urbanos densos, la API se basa en la cobertura del VPS para generar posiciones 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 de VPS con la función suspendida Geospatial.checkVpsAvailability(latitude, longitude). Esta llamada es una operación asíncrona y no requiere que la sesión se configure con el GeospatialMode.VPS_AND_GPS modo.

En el siguiente código, se muestra cómo verificar la disponibilidad del VPS desde 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.

Convierte la posición de un dispositivo en una posición geoespacial

Puedes convertir la posición de un dispositivo en una posición geoespacial para permitir que los lentes de 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 (posición del dispositivo) en coordenadas reconocidas a nivel global.

Esto puede ayudarte a hacer lo siguiente:

  • Crear contenido de RA persistente, en el que el objeto virtual colocado por un usuario se ancle con precisión a una ubicación global para su recuperación posterior
  • Activar 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 geovalla
  • Determinar el contexto preciso del mundo real del usuario para activar la lógica de la aplicación relevante para la ubicación

Para convertir una posición de dispositivo en una posición geoespacial con 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.
    }
}

Convierte una posición geoespacial en la posición de un dispositivo

Puedes convertir una posición geoespacial en la posición de un dispositivo para ayudar a ofrecer experiencias contextuales y basadas en la ubicación en los lentes de IA. Esta transformación toma la información definida por las coordenadas del mundo real, como la ubicación de un punto de referencia, una ruta de navegación o contenido de RA persistente, y la convierte en el espacio visual preciso de los lentes del usuario.

Para convertir una posición geoespacial en la posición de un dispositivo con 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.
    }
}