Utilizzare le pose geospaziali con ARCore per Jetpack XR

Dispositivi XR applicabili
Queste indicazioni ti aiutano a creare esperienze per questi tipi di dispositivi XR.
Scopri di più sui tipi di dispositivi XR →
AI Glasses
Scopri di più sui tipi di dispositivi XR →

Con l'API Geospatial in ARCore per Jetpack XR, la tua app può collegare da remoto contenuti a qualsiasi area coperta da Street View di Google e creare esperienze AR su scala globale. L'API Geospatial utilizza i dati dei sensori del dispositivo e del GPS per rilevare l'ambiente del dispositivo, quindi associa le parti riconoscibili di questo ambiente a un modello di localizzazione fornito dal sistema di posizionamento visivo (VPS) di Google per determinare la posizione esatta del dispositivo di un utente. L'API si occupa anche di unire le coordinate locali dell'utente con le coordinate geografiche del VPS, in modo da poter lavorare all'interno di un unico sistema di coordinate.

Attivare l'API ARCore

Prima di utilizzare il sistema di posizionamento visivo (VPS) nella tua app, devi prima attivare l'API ARCore in un progetto Google Cloud nuovo o esistente. Questo servizio è responsabile dell'hosting, dell'archiviazione e della risoluzione degli ancoraggi geospaziali.

Aggiungere dipendenze della libreria aggiuntive

L'utilizzo dell'API Geospatial richiede alcune dipendenze di librerie aggiuntive. Aggiungi questi elementi al file build.gradle.kts della tua 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")
}

Richiedere le autorizzazioni necessarie

Per utilizzare l'API Geospatial in ARCore con Jetpack XR, la tua app deve richiedere le seguenti autorizzazioni di runtime:

Dichiarare le autorizzazioni app

Prima di poter richiedere queste autorizzazioni al runtime, devi dichiararle nel file manifest della tua 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>

Richiedi autorizzazioni

Dopo aver dichiarato le autorizzazioni richieste, la tua app deve richiederle in fase di runtime. Assicurati di spiegare perché la tua app ha bisogno delle autorizzazioni.

L'API Geospatial non può funzionare a meno che non riesca a determinare la posizione precisa dell'utente. Per questo motivo, segui le indicazioni per richiedere le autorizzazioni di accesso alla posizione in fase di runtime, in modo che alla tua app possano essere concesse le autorizzazioni ACCESS_FINE_LOCATION e ACCESS_COARSE_LOCATION.

Accedere a una sessione

Accedi alle informazioni geospaziali tramite un runtime Jetpack XR Session, che la tua app deve creare.

Configurare la sessione

Le informazioni sulla postura del dispositivo non sono attivate per impostazione predefinita nelle sessioni XR. Per consentire alla tua app di recuperare le informazioni sulla postura del dispositivo, configura la sessione e imposta le modalità GeospatialMode.VPS_AND_GPS e 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

La modalità GeospatialMode.VPS_AND_GPS sfrutta sia i dati del Visual Positioning System (VPS) sia quelli del Global Positioning System (GPS) per determinare con precisione la posizione geospaziale del dispositivo.

Non tutti i dispositivi XR supportano le modalità GeospatialMode.VPS_AND_GPS e DeviceTrackingMode.LAST_KNOWN. Se Session.configure() ha esito positivo, il dispositivo supporta queste modalità.

Chiedere all'utente di consentire l'utilizzo dei dati del dispositivo

Le app che utilizzano l'API Geospatial con ARCore per Jetpack XR devono presentare all'utente una richiesta di conferma e autorizzazione all'utilizzo dei dati del dispositivo. Per saperne di più, consulta i requisiti per la privacy degli utenti.

Ottieni l'oggetto spaziale

Una volta configurata la sessione, ottieni l'oggetto Geospatial utilizzando Geospatial.getInstance(session):

// Get the Geospatial instance for the current session.
val geospatial = Geospatial.getInstance(session)
Geospatial.kt

L'oggetto Geospatial deve essere utilizzato solo quando il suo stato è State.RUNNING. Puoi monitorare lo stato utilizzando Geospatial.state StateFlow<Geospatial.State>.

Controllare la disponibilità del VPS

Poiché l'API Geospatial utilizza una combinazione di VPS e GPS per determinare una posa spaziale, l'API è disponibile ogni volta che il dispositivo può determinare la sua posizione. Nelle aree con bassa precisione GPS, come gli spazi interni e gli ambienti urbani densi, l'API si basa sulla copertura VPS per generare pose ad alta precisione.

In condizioni tipiche, puoi aspettarti che VPS fornisca una precisione posizionale di circa 5 metri e una precisione rotazionale di 5 gradi. Puoi verificare se una località ha copertura VPS utilizzando la funzione di sospensione Geospatial.checkVpsAvailability(latitude, longitude). Questa chiamata è un'operazione asincrona e non richiede che la sessione sia configurata con la modalità GeospatialMode.VPS_AND_GPS.

Il seguente codice mostra come verificare la disponibilità del VPS da una latitudine e longitudine specificate:

// 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

La tua app deve essere configurata correttamente per comunicare con l'API ARCore su Google Cloud; in caso contrario, la tua app riceve un risultato VpsAvailabilityNotAuthorized.

Convertire la posa di un dispositivo in una posa geospaziale

Puoi convertire la posa di un dispositivo in una posa geospaziale per consentire agli occhiali AI di interagire e generare dati sensibili alla posizione. Questa pipeline traduce la posizione e l'orientamento attuali del dispositivo nel suo sistema di coordinate locale (posa del dispositivo) in coordinate riconosciute a livello globale.

In questo modo puoi:

  • Crea contenuti AR persistenti, in cui l'oggetto virtuale posizionato da un utente è ancorato con precisione a una posizione globale per il recupero successivo.
  • Attiva esperienze basate sulla posizione aggiornando continuamente la posizione dell'utente su una mappa per consentire la navigazione in tempo reale o il gameplay con geofence.
  • Determinare il contesto reale preciso dell'utente per attivare la logica dell'applicazione pertinente alla posizione.

Per convertire la posa del dispositivo in una posa geospaziale utilizzando 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

Convertire una posa geospaziale in una posa del dispositivo

Puoi convertire una posa geospaziale in una posa del dispositivo per contribuire a offrire esperienze contestuali e basate sulla posizione sugli occhiali AI. Questa trasformazione prende le informazioni definite dalle coordinate del mondo reale, ad esempio la posizione di un punto di riferimento, un percorso di navigazione o contenuti AR persistenti, e le converte nello spazio visivo preciso degli occhiali dell'utente.

Per convertire una posa geospaziale in una posa del dispositivo utilizzando 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