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 conferisce un nuovo aspetto alla realtà aumentata, consentendoti di posizionare tappe di realtà aumentata specifiche della località intorno a punti di riferimento reali.

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 fornire una semplice esperienza di individuazione della posizione in realtà aumentata.

Obiettivi didattici

• Come configurare un progetto ARCore che utilizza l'API Geospatial.
• Come richiedere i dati geografici all'API Geospatial e visualizzarli tramite Google Maps.
• Come posizionare un ancoraggio collegato a un luogo reale.

Che cosa ti serve

• Un dispositivo Android ARCore supportato, collegato tramite cavo USB alla macchina di sviluppo e configurato con 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 di base che include le nozioni di base di un progetto ARCore integrato con l'SDK di Google Maps. Questo ti offre una guida rapida all'utilizzo dell'API Geospatial.

1. Avvia Android Studio e importa un progetto da VCS.
   • Se hai già un progetto aperto, seleziona File > Nuovo > Progetto da Controllo versione....
   • Se visualizzi la finestra Ti diamo il benvenuto in Android Studio, usa Scarica 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 immagini di Street View combinate con il magnetometro del dispositivo e le informazioni del sensore della fotocamera per migliorare i valori di orientamento. Per utilizzare questo servizio, devi configurare un progetto Google Cloud.

1. Crea un progetto nella console Google Cloud:
   • Visita Creare un progetto in Google Cloud.
     
   • Inserisci un Nome progetto appropriato (ad esempio "Progetto API ARCore Geospatial") e scegli una località 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 Libreria.
   • Cerca Maps SDK for Android.
   • Fai clic su Abilita.
3. Crea le credenziali della chiave API:
   • In API e servizi, seleziona Credenziali.
   • Nella barra superiore, fai clic su Crea credenziali e seleziona Chiave API.
   • Prendi nota della chiave creata in base alle tue esigenze nel passaggio successivo. Torna alla pagina Credenziali se devi recuperarle.

Con questi passaggi, hai creato un progetto Google Cloud con autorizzazione delle chiavi API ed è tutto pronto per 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 meta-data voci:

   <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 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 Google Maps.

Verificare il progetto

Assicurati che il tuo progetto sia pronto. In Android Studio, esegui l'app. Nella parte inferiore dello schermo dovresti vedere una visualizzazione della fotocamera e una mappa funzionante.

3. Determinare la posizione dell'utente

In questo passaggio, aggiungerai 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 il valore 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'uso. In quel momento, il valore TrackingState.ENABLED sarà trackingState.

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

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

val cameraGeospatialPose = earth.cameraGeospatialPose

In questo modo otterrai una GeospatialPose contenente queste informazioni:

• Posizione, espressa in latitudine e longitudine. Viene fornita anche una stima della precisione della posizione.
• Altitudine e una stima della precisione dell'altitudine.
• Direzione, un'approssimazione della direzione in cui è rivolto il dispositivo e una stima della precisione della direzione.

Mostra informazioni sul posizionamento sulla mappa

Puoi utilizzare l'GeospatialPose memorizzato in cameraGeospatialPose per spostare un indicatore sulla mappa che mostri 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
)

Questa operazione aggiorna continuamente la posizione della mappa utilizzando i valori ottenuti dall'API Geospatial.

Prova

In Android Studio, fai clic su Riproduci. Solleva il dispositivo e muovilo per aiutare ARCore a stabilire il rilevamento. Dopo un po' di tempo, sulla mappa dovrebbe apparire un indicatore verde. Questo indicatore ruota mentre visualizzi l'ambiente circostante. Inoltre, deve puntare nella direzione corretta: quando ti trovi fisicamente a nord, la freccia punta anche a nord.

4. Posizionare un ancoraggio utilizzando le coordinate di Earth

L'API Geospaziale può posizionare ancoraggi in qualsiasi coppia di coordinate e rotazione nel mondo reale. In questo modo, gli utenti possono visualizzare contenuti ancorati quando visitano luoghi specifici.

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

Imposta un'azione quando la mappa viene toccata

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

Assicurati che l'oggetto Earth possa essere utilizzato

Prima di creare ancoraggi su Earth, assicurati che il TrackingState dell'oggetto Earth sia TRACKING, il che significa che la posizione della Terra è nota. Assicurati inoltre che il valore 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 Earth stia monitorando, scollega il precedente earthAnchor, se esistente. Nei passaggi successivi devi sostituire earthAnchor con un nuovo ancoraggio:

earthAnchor?.detach()

Quindi, utilizza cameraGeospatialPose per determinare l'altitudine per la nuova ancoraggio. Utilizza la coppia di coordinate che consente di toccare la mappa come posizionamento dell'ancoraggio.

// 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 una Anchor fissa in coordinate geodetiche con una data rotazione. Questo ancoraggio cerca di rimanere stabile e fisso alle coordinate e all'altitudine specificate.

Le variabili [qx, qy, qz, qw] determinano la rotazione dell'ancoraggio espressa in quaternioni, nel sistema di coordinate Est-Su-Sud (EUS). Utilizzi valori diversi per ruotare l'ancoraggio, ma in questo esempio devi usare un quaternione di unità per la rotazione predefinita. In una rotazione unitaria di quaternione l'ancoraggio è orientato in modo tale che X+ punti a est, Y+ punti in alto rispetto al centro della Terra e Z+ punti a sud.

Mostra l'indicatore posizionato sulla mappa

Infine, sposta un nuovo indicatore che indichi dove si trovava l'indicatore:

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

Prova

In Android Studio, fai clic su Riproduci. Solleva il dispositivo e muovilo per aiutare ARCore a stabilire il rilevamento. Dopo un po' di tempo, sulla mappa dovrebbe apparire un indicatore verde che indica la tua posizione corrente.

Quando tocchi la mappa, viene utilizzata l'API Geospatial per posizionare un ancoraggio, che è fisso su una posizione reale. Prova a posizionare l'ancoraggio vicino alla tua posizione corrente in modo da poterlo vedere nella vista AR. Dovrebbe rimanere stabile mentre navighi 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 la posizione geografica.

Risorse aggiuntive

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

• Documentazione dell'API ARCore Geospatial
• Sistema geodetico mondiale (WGS)
• SDK Google Maps per Android