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 abbina le parti riconoscibili di quell'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 libreria aggiuntive. Aggiungi queste righe
al file build.gradle.kts dell'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:
ACCESS_INTERNET: obbligatorio per contattare il servizio cloud dell'API ARCore Geospatial.ACCESS_COARSE_LOCATION: obbligatorio per determinare la posizione approssimativa di un utente.ACCESS_FINE_LOCATION: obbligatorio per determinare la posizione precisa di un utente.
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.
Configura 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 = 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.
}
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
var geospatial = Geospatial.getInstance(session)
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 può essere utilizzata finché il dispositivo è in grado di determinare la sua posizione. Nelle aree con bassa precisione del 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 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
}
La tua app deve essere configurata correttamente per comunicare con l'API ARCore su Google
Cloud; in caso contrario, riceverà 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
// 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
}
}
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():
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
}
}