Creare un'app di realtà aumentata (AR) utilizzando la nuova API ARCore Geospatial

1. Panoramica

ARCore è il framework di Google per la creazione di esperienze di realtà aumentata sugli smartphone. La nuova API ARCore Geospatial aggiunge un nuovo aspetto alla realtà aumentata, consentendoti di posizionare waypoint di realtà aumentata specifici per la posizione intorno a punti di riferimento del mondo reale.

Cosa creerai

In questo codelab, inizierai a utilizzare l'API ARCore Geospatial. Scoprirai quali informazioni può offrire l'API Geospatial alla tua esperienza AR complessiva e come questi dati possono essere utilizzati per potenziare una semplice esperienza di orientamento AR.

Obiettivi didattici

• Come configurare un progetto ARCore che utilizza l'API Geospatial.
• Come richiedere dati geografici dall'API Geospatial e visualizzarli utilizzando Google Maps.
• Come posizionare un ancoraggio collegato a una posizione del mondo reale.

Che cosa ti serve

• Un dispositivo Android ARCore supportato, collegato tramite cavo USB alla macchina di sviluppo e configurato con il debug USB.
• Android Studio installato e configurato per creare app per Android.
• Google Play Services per AR 1.31 o versioni successive, installato sul dispositivo di sviluppo Android.

2. Configurazione dell'ambiente di sviluppo

Configurare Android Studio

Per iniziare a utilizzare l'API Geospatial, abbiamo fornito un progetto iniziale che include le basi di un progetto ARCore integrato con l'SDK Google Maps. In questo modo, puoi iniziare rapidamente a utilizzare l'API Geospatial.

1. Avvia Android Studio e importa un progetto da VCS.
   • Se hai già aperto un progetto, usa File > Nuovo > Progetto dal controllo della versione….
   • Se visualizzi la finestra Benvenuto in Android Studio, utilizza Ottieni da VCS.
2. Seleziona Git e utilizza l'URL https://github.com/google-ar/codelab-geospatial.git per importare il progetto.

Configura un progetto Google Cloud

L'API Geospatial utilizza le immagini di Street View combinate con le informazioni del magnetometro e del sensore della videocamera del dispositivo per migliorare i valori di orientamento. Per utilizzare questo servizio, devi configurare un progetto Google Cloud.

1. Crea un progetto in Google Cloud Console:
   • Visita la pagina Crea un progetto in Google Cloud Platform.
     
   • Inserisci un nome del progetto appropriato (ad esempio, "Progetto API ARCore Geospatial") e scegli una posizione qualsiasi.
   • Fai clic su Crea.
2. Abilita le API necessarie:
   • Nella barra laterale, seleziona API e servizi e poi Libreria.
   • Cerca l'API ARCore.
   • Fai clic su Abilita.
   • Torna alla Raccolta.
   • Cerca Maps SDK for Android.
   • Fai clic su Abilita.
3. Crea credenziali della chiave API:
   • In API e servizi, seleziona Credenziali.
   • Nella barra in alto, fai clic su Crea credenziali, poi seleziona Chiave API.
   • Prendi nota della chiave creata, perché ti servirà per il passaggio successivo. Torna alla pagina Credenziali se devi recuperarla.

Con questi passaggi, hai creato un progetto Google Cloud con l'autorizzazione della chiave API e puoi utilizzare l'API Geospatial.

Integrare la chiave API con il progetto Android Studio

Per associare la chiave API di Google Cloud al tuo progetto, apri il progetto che hai creato in Android Studio e modifica le chiavi API:

1. Apri app > src > AndroidManifest.xml.
2. Trova le seguenti voci meta-data:

   <meta-data
       android:name="com.google.android.ar.API_KEY"
       android:value="PLACEHOLDER_API_KEY" />
   
   <meta-data
       android:name="com.google.android.geo.API_KEY"
       android:value="PLACEHOLDER_API_KEY" />
   

3. Sostituisci PLACEHOLDER_API_KEY con la chiave API che hai creato nel tuo progetto Google Cloud.

Il valore memorizzato in com.google.android.ar.API_KEY autorizza questa app a utilizzare l'API Geospatial, mentre il valore memorizzato in com.google.android.geo.API_KEY autorizza questa app a utilizzare l'SDK di Google Maps.

Verifica del progetto

Assicurati che il progetto sia pronto. In Android Studio, esegui l'app. Dovresti vedere una visualizzazione della videocamera, insieme a una mappa funzionante nella parte inferiore dello schermo.

3. Determinare la posizione dell'utente

In questo passaggio, aggiungi codice al progetto di esempio per iniziare a utilizzare l'API Geospatial.

Configura la sessione ARCore per utilizzare l'API Geospatial

Per ottenere dati geospaziali, devi abilitare l'API Geospatial. Modifica GeospatialMode nella configurazione della sessione in ENABLED modificando la funzione configureSession in HelloGeoActivity.kt:

fun configureSession(session: Session) {
  session.configure(
    session.config.apply {
      // Enable Geospatial Mode.
      geospatialMode = Config.GeospatialMode.ENABLED
    }
  )
}

Mentre la modalità Geospaziale è ENABLED, l'applicazione può ottenere informazioni geospaziali.

Richiedere dati dall'API Geospatial

In HelloGeoRenderer.kt, trova la seguente riga:

// TODO: Obtain Geospatial information and display it on the map.

Sotto, verifica che l'oggetto Earth sia disponibile per l'utilizzo. In questo caso, ha trackingState TrackingState.ENABLED.

val earth = session.earth
if (earth?.trackingState == TrackingState.TRACKING) {
  // TODO: the Earth object may be used here.
}

Sotto TODO, richiedi informazioni geospaziali da ARCore. Aggiungi questa riga:

val cameraGeospatialPose = earth.cameraGeospatialPose

In questo modo, otterrai un GeospatialPose che contiene queste informazioni:

• Posizione, espressa in latitudine e longitudine. Viene fornita anche una stima della precisione della localizzazione.
• Elevazione e una stima della precisione dell'elevazione.
• Direzione, un'approssimazione della direzione in cui è rivolto il dispositivo e una stima dell'accuratezza della direzione.

Visualizzare le informazioni sul posizionamento sulla mappa

Puoi utilizzare GeospatialPose memorizzato in cameraGeospatialPose per spostare un indicatore sulla mappa che mostra la posizione dell'utente. Continua da dove avevi interrotto e aggiungi quanto segue:

activity.view.mapView?.updateMapPosition(
  latitude = cameraGeospatialPose.latitude,
  longitude = cameraGeospatialPose.longitude,
  heading = cameraGeospatialPose.heading
)

Aggiorna continuamente la posizione della mappa utilizzando i valori ottenuti dall'API Geospatial.

Prova

In Android Studio, fai clic su Play. Tieni sollevato il dispositivo e muovilo per aiutare ARCore a stabilire il tracciamento. Dopo un po', dovresti vedere un indicatore verde sulla mappa. Questo indicatore ruota mentre visualizzi l'ambiente circostante. Inoltre, deve puntare nella direzione corretta: quando sei rivolto a nord, anche la freccia deve puntare a nord.

4. Posizionare un ancoraggio utilizzando le coordinate di Earth

L'API Geospatial può posizionare gli ancoraggi in qualsiasi coppia di coordinate e rotazione nel mondo reale. In questo modo, gli utenti possono visualizzare i contenuti ancorati quando visitano località specifiche.

In questo passaggio, aggiungi un modo per posizionare un ancoraggio toccando la mappa.

Impostare un'azione quando viene toccata la mappa

Il progetto include una funzione onMapClick, che viene chiamata con una latitudine e una longitudine quando si fa clic sul frammento di mappa. Trova la funzione onMapClick in HelloGeoRenderer.kt.

Assicurarsi che l'oggetto Earth possa essere utilizzato

Prima di creare ancore sulla Terra, assicurati che il TrackingState dell'oggetto Terra sia TRACKING, il che significa che la posizione della Terra è nota. Assicurati inoltre che il relativo EarthState sia ENABLED, il che significa che non sono stati riscontrati problemi con l'API Geospatial. Aggiungi queste righe all'interno di onMapClick:

val earth = session?.earth ?: return
if (earth.trackingState != TrackingState.TRACKING) {
  return
}

Determina il posizionamento del nuovo ancoraggio

Dopo aver verificato che l'oggetto Terra è in monitoraggio, scollega il precedente earthAnchor, se esistente. Nei passaggi successivi, sostituirai earthAnchor con un nuovo ancoraggio:

earthAnchor?.detach()

Poi, utilizza cameraGeospatialPose per determinare l'altitudine del nuovo punto di ancoraggio. Utilizza la coppia di coordinate ottenuta toccando la mappa come posizionamento dell'ancora.

// Place the earth anchor at the same altitude as that of the camera to make it easier to view.
val altitude = earth.cameraGeospatialPose.altitude - 1
// The rotation quaternion of the anchor in the East-Up-South (EUS) coordinate system.
val qx = 0f
val qy = 0f
val qz = 0f
val qw = 1f
earthAnchor =
  earth.createAnchor(latLng.latitude, latLng.longitude, altitude, qx, qy, qz, qw)

createAnchor crea un Anchor fissato alle coordinate geodetiche con una determinata rotazione. Questo ancoraggio tenta di rimanere stabile e fissato alle coordinate e all'altitudine specificate.

Le variabili [qx, qy, qz, qw] determinano la rotazione dell'ancora espressa in quaternioni, nel sistema di coordinate Est-Su-Sud (EUS). Utilizzi valori diversi per ruotare l'ancora, ma in questo esempio utilizza un quaternione unitario per la rotazione predefinita. Una rotazione del quaternione unitario ha l'ancora orientata in modo che X+ punti a est, Y+ punti verso l'alto lontano dal centro della Terra e Z+ punti a sud.

Mostrare l'indicatore posizionato sulla mappa

Infine, sposta un nuovo indicatore che indica dove è stato posizionato l'indicatore:

activity.view.mapView?.earthMarker?.apply {
  position = latLng
  isVisible = true
}

Prova

In Android Studio, fai clic su Play. Tieni sollevato il dispositivo e muovilo per aiutare ARCore a stabilire il tracciamento. Dopo un breve periodo di tempo, sulla mappa dovrebbe apparire un indicatore verde che indica la tua posizione attuale.

Se tocchi la mappa, l'API Geospatial viene utilizzata per posizionare un ancoraggio, che viene fissato a una posizione del mondo reale. Prova a posizionare l'ancora vicino alla tua posizione attuale in modo da poterla vedere nella visualizzazione AR. Dovrebbe rimanere stabile mentre ti muovi nell'ambiente.

5. Conclusione

In questo codelab hai imparato a utilizzare l'API Geospatial per creare una semplice esperienza AR legata al mondo reale.

Argomenti trattati

• Come configurare un progetto Google Cloud con l'API Geospatial abilitata.
• Come ottenere informazioni geospaziali in un progetto ARCore e visualizzarle su una mappa.
• Come posizionare un ancoraggio posizionato nel mondo reale utilizzando il posizionamento geografico.

Risorse aggiuntive

Per ulteriori dettagli sui concetti geografici e sugli SDK utilizzati in questo codelab, consulta queste risorse aggiuntive:

• Documentazione dell'API ARCore Geospatial
• World Geodetic System (WGS)
• SDK Google Maps per Android