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 assegna un nuovo aspetto alla realtà aumentata, consentendoti di inserire waypoint di realtà aumentata specifici per località intorno a punti di riferimento del mondo reale.

Cosa creerai

In questo codelab, inizierai a utilizzare l'API ARCore Geospatial. Scoprirai quali informazioni l'API Geospatial può offrire alla tua esperienza AR complessiva e come questi dati possono essere utilizzati per facilitare una semplice esperienza di ricerca 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 collegata a un luogo reale.

Che cosa ti serve

• Un dispositivo Android ARCore supportato, collegato tramite un cavo USB al computer 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 nozioni di base di un progetto ARCore integrato con Google Maps SDK. Questo ti consente di iniziare rapidamente a utilizzare l'API Geospatial.

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

1. Crea un progetto nella console Google Cloud:
   • Consulta Creare un progetto nella piattaforma Google Cloud.
     
   • Inserisci un Nome progetto appropriato (ad esempio, "Progetto API ARCore Geospatial API") e scegli qualsiasi località.
   • Fai clic su Crea.
2. Abilita le API necessarie:
   • Nella barra laterale, seleziona API e Services, quindi 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:
   • Nella sezione API e Services, seleziona Credenziali.
   • Nella barra in alto, fai clic su Crea credenziali, quindi seleziona Chiave API.
   • Prendi nota della chiave che è stata creata se ti serve per il passaggio successivo. Torna alla pagina Credenziali se devi recuperarle.

Con questi passaggi, hai creato un progetto Google Cloud con autorizzazione alla chiave API e tutto è pronto per utilizzare l'API Geospatial.

Integra 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 l'app > src > AndroidManifest.xml.
2. Trova le seguenti voci di 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 progetto Google Cloud.

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

Verifica il progetto

Assicurati che il tuo progetto sia pronto per essere pubblicato. Esegui l'app in Android Studio. Dovresti riuscire a vedere la visualizzazione della videocamera, insieme a una mappa funzionante nella parte inferiore dello schermo.

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 l'utilizzo dell'API Geospatial

Per ottenere dati geospaziali, devi abilitare l'API Geospatial. Cambia il 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.

Richiedi 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 questo momento che 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 ad ARCore. Aggiungi questa riga:

val cameraGeospatialPose = earth.cameraGeospatialPose

In questo modo ottieni una GeospatialPose che contiene le seguenti informazioni:

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

Mostra informazioni di posizionamento sulla mappa

Puoi utilizzare la GeospatialPose memorizzata in cameraGeospatialPose per spostare un indicatore sulla mappa che mostra dove si trova l'utente. Continua da dove avevi interrotto e aggiungi quanto segue:

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

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

Prova

In Android Studio, fai clic su Riproduci. Solleva il tuo dispositivo e muovilo per consentire ad ARCore di stabilire il rilevamento. Dopo qualche istante, dovresti vedere un indicatore verde sulla mappa. Questo indicatore ruota mentre visualizzi l'area circostante. Inoltre, deve puntare nella direzione corretta: quando sei fisicamente rivolto a nord, anche la freccia punta a nord.

4. Posiziona un ancoraggio utilizzando le coordinate di Earth

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

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

Imposta un'azione quando viene toccata la mappa

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

Assicurati che l'oggetto Earth possa essere utilizzato

Prima di creare ancoraggi sulla Terra, assicurati che il valore TrackingState dell'oggetto Earth sia TRACKING, il che significa che la posizione della Terra è nota. Assicurati anche che EarthState sia ENABLED, il che significa che non sono stati riscontrati problemi con l'API Geospaziale. 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 è in fase di tracciamento, scollega l'elemento earthAnchor precedente, se esistente. Sostituisci earthAnchor con un nuovo ancoraggio nei passaggi successivi:

earthAnchor?.detach()

Quindi, utilizza cameraGeospatialPose per determinare l'altitudine della nuova ancoraggio. Usa la coppia di coordinate toccando 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 un campo Anchor fisso su coordinate geodetiche con una determinata rotazione. Questo ancoraggio cerca di rimanere stabile e fisso in base alle coordinate e all'altitudine specificate.

Le variabili [qx, qy, qz, qw] determinano la rotazione espressa in quaternioni dell'ancoraggio nel sistema di coordinate Est-Sud (EUS). Puoi utilizzare valori diversi per ruotare l'ancoraggio, ma in questo esempio viene utilizzata una quaternità unitaria per la rotazione predefinita. In una rotazione del quaternione unitario, l'ancora è orientata in modo che X+ punti a est, Y+ in alto dal centro della Terra e Z+ a sud.

Mostra l'indicatore posizionato sulla mappa

Infine, sposta un nuovo indicatore che indichi la posizione dell'indicatore:

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

Prova

In Android Studio, fai clic su Riproduci. Solleva il tuo dispositivo e muovilo per consentire ad ARCore di stabilire il rilevamento. Dopo qualche istante, dovresti vedere un indicatore verde sulla mappa che indica la tua posizione corrente.

Quando tocchi la mappa, viene utilizzata l'API Geospaziale per posizionare un ancoraggio, che è fisso su una posizione reale. Prova a posizionare l'ancoraggio vicino alla tua posizione corrente in modo da vederlo nella visualizzazione AR. Dovrebbe rimanere stabile mentre esplori l'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
• Sistema geodetico mondiale (WGS)
• SDK Google Maps per Android