Utilizzare gli ancoraggi geospaziali per posizionare contenuti reali su Android NDK

Gli ancoraggi geospaziali sono un tipo di ancoraggio che ti consentono di posizionare contenuti 3D nel mondo reale.

Tipi di ancore geospaziali

Esistono tre tipi di ancore geospaziali, che gestiscono l'altitudine in modo diverso:

1. Ancoraggi WGS84:
   gli ancoraggi WGS84 ti consentono di posizionare i contenuti 3D in qualsiasi latitudine, longitudine e altitudine.

2. Ancoraggi del terreno:
   Gli ancoraggi del terreno ti consentono di posizionare i contenuti utilizzando solo la latitudine e la longitudine con un'altezza relativa al terreno in quella posizione. L'altitudine viene determinata rispetto al suolo o al pavimento come noto da VPS.

3. Ancoraggie sul tetto:
   Gli ancoraggi sul tetto ti consentono di posizionare i contenuti utilizzando solo la latitudine e la longitudine con un'altezza relativa al tetto di un edificio in quella posizione. L'altitudine viene determinata in base alla sommità di un edificio, come indicato da Streetscape Geometry. Per impostazione predefinita, viene utilizzata l'altitudine del suolo se l'edificio non è presente.

	WGS84	Rilievo	Tetto
Posizione orizzontale	Latitudine, longitudine	Latitudine, longitudine	Latitudine, longitudine
Posizione verticale	Rispetto all'altitudine WGS84	In base al livello del suolo determinato da Google Maps	In base al livello del tetto determinato da Google Maps
Deve essere risolto dal server?	No	Sì	Sì

Prerequisiti

Prima di procedere, assicurati di abilitare l'API Geospatial.

Posiziona gli anchor geospaziali

Per ogni tipo di ancora esistono API dedicate per la loro creazione. Per ulteriori informazioni, consulta la sezione Tipi di ancore geospaziali.

Creare un'ancora da un test di hit

Puoi anche creare un'ancora geospaziale da un risultato del test di corrispondenza. Utilizza la posa dall'hit-test e convertila in un ArGeospatialPose. Utilizzalo per inserire uno dei tre tipi di ancoraggi descritti.

Ottenere una posa geospaziale da una posa AR

ArEarth_getGeospatialPose() fornisce un modo aggiuntivo per determinare la latitudine e la longitudine convertendo una posa AR in una posa geospaziale.

Ottenere una posa AR da una posa geospaziale

ArEarth_getPose() converte una posizione orizzontale, un'altitudine e una rotazione di quaternione specificati per la Terra rispetto a un sistema di coordinate est-alto-sud in una posa AR rispetto alle coordinate mondiali GL.

Scegli il metodo più adatto al tuo caso d'uso

Ogni metodo di creazione di un'ancora ha dei compromessi da tenere presenti:

• Quando utilizzi la geometria della strada, utilizza un test di hit per associare i contenuti a un edificio.
• Preferisci gli ancoraggi sul tetto o sul terreno rispetto a quelli WGS84 perché utilizzano i valori di altitudine determinati da Google Maps.

Determinare la latitudine e la longitudine di una località

Esistono tre modi per calcolare la latitudine e la longitudine di una località:

• Utilizza Geospatial Creator per visualizzare e migliorare il mondo con contenuti 3D senza doverti recare fisicamente in un luogo. In questo modo puoi posizionare visivamente contenuti immersivi 3D utilizzando Google Maps in Unity Editor. La latitudine, la longitudine, la rotazione e l'altitudine dei contenuti verranno calcolate automaticamente.
• Utilizza Google Maps
• Utilizza Google Earth. Tieni presente che l'ottenimento di queste coordinate utilizzando Google Earth, anziché Google Maps, ti darà un margine di errore fino a diversi metri.
• Vai alla sede fisica

Utilizza Google Maps

Per ottenere la latitudine e la longitudine di una posizione utilizzando Google Maps:

1. Vai su Google Maps sul computer.

   

2. Vai a Livelli > Altro.

   

   

3. Imposta Tipo di mappa su Satellitare e deseleziona la casella di controllo Visualizzazione globo nell'angolo in basso a sinistra dello schermo.

   

   In questo modo verrà forzata una prospettiva 2D ed eliminati i possibili errori che potrebbero derivare da una vista 3D inclinata.

4. Sulla mappa, fai clic con il tasto destro del mouse sulla posizione e seleziona la longitudine/latitudine per copiarla negli appunti.

Utilizzare Google Earth

Puoi calcolare la latitudine e la longitudine di una posizione da Google Earth facendo clic su una posizione nell'interfaccia utente e leggendo i dati dai dettagli del segnaposto.

Nota: se ottieni queste coordinate utilizzando Google Earth, anziché Google Maps, avrai un margine di errore fino a diversi metri. Ti consigliamo di utilizzare Google Maps e l'API Elevation per ottenere la latitudine e la longitudine di una località.

Per ottenere la latitudine e la longitudine di una località utilizzando Google Earth:

1. Vai su Google Earth sul computer.

2. Vai al menu a tre linee e seleziona Stile mappa.

   

3. Disattiva l'opzione Edifici in 3D.

   

4. Dopo aver disattivato l'opzione Edifici in 3D, fai clic sull'icona a forma di freccia per aggiungere un segnaposto nella posizione selezionata.

5. Specifica un progetto che contenga il segnaposto e fai clic su Salva.

6. Nel campo Titolo del segnaposto, inserisci un nome per il segnaposto.

7. Fai clic sulla freccia Indietro nel riquadro del progetto e seleziona il menu Altre azioni.

8. Scegli Esporta come file KML dal menu.

   

Il file KLM riporta la latitudine, la longitudine e l'altitudine di un segnaposto nel tag <coordinates> separati da virgole, come segue:

<coordinates>-122.0755182435043,37.41347299422944,7.420342565583832</coordinates>

Non utilizzare la latitudine e la longitudine dei tag <LookAt>, che specificano la posizione della videocamera, non la posizione.

Vai alla sede fisica

Puoi calcolare l'altitudine di una località recandoti sul posto ed effettuando un'osservazione locale.

Recupera il quaternione di rotazione

ArGeospatialPose_getEastUpSouthQuaternion() estrae l'orientamento da una posa geospaziale e restituisce un quaternione che rappresenta la matrice di rotazione che trasforma un vettore dal target al sistema di coordinate est-alto-sud (EUS). X+ punta a est, Y+ punta verso l'alto e Z+ punta a sud. I valori vengono scritti nell'ordine {x, y, z, w}.

Ancore WGS84

Un'ancora WGS84 è un tipo di ancora che ti consente di posizionare contenuti 3D in qualsiasi latitudine, longitudine e altitudine. Si basa su una posa e sull'orientamento per essere posizionato nel mondo reale. La posizione è costituita da latitudine, longitudine e altitudine, specificate nel sistema di coordinate WGS84. L'orientamento è costituito da una rotazione di quaternioni.

L'altitudine viene indicata in metri sopra l'ellissoide di riferimento WGS84, in modo che il livello del suolo non sia pari a zero. È responsabilità della tua app fornire queste coordinate per ogni ancora creata.

Posiziona un'ancora WGS84 nel mondo reale

Determinare l'altitudine di una località

Esistono diversi modi per determinare l'altitudine di una posizione per il posizionamento delle ancore:

• Se la posizione dell'ancora è fisicamente vicina all'utente, puoi utilizzare un'altitudine simile a quella del dispositivo dell'utente.
• Una volta ottenute la latitudine e la longitudine, utilizza l'API Elevation per ottenere un'elevazione in base alla specifica EGM96. Devi convertire l'elevazione EGM96 dell'API Maps in WGS84 per il confronto con l'altitudine ArGeospatialPose. Consulta GeoidEval, che dispone sia di una riga di comando sia di un'interfaccia HTML. L'API Maps registra la latitudine e la longitudine in base alla specifica WGS84.
• Puoi ottenere la latitudine, la longitudine e l'altitudine di una posizione da Google Earth. Questo ti darà un margine di errore fino a diversi metri. Utilizza la latitudine, la longitudine e l'altitudine dei tag <coordinates>, non dei tag <LookAt>, nel file KML.
• Se nelle vicinanze è presente un'ancora esistente e se non ti trovi su una salita ripida, potresti essere in grado di utilizzare l'altitudine del ArGeospatialPose della fotocamera senza utilizzare un'altra origine, come l'API Maps.

Crea l'ancora

Una volta ottenuti la latitudine, la longitudine, l'altitudine e il quaternione di rotazione, utilizza ArEarth_acquireNewAnchor() per ancorare i contenuti alle coordinate geografiche specificate.

float eus_quaternion_4[4] = {qx, qy, qz, qw};
if (ar_earth != NULL) {
  ArTrackingState earth_tracking_state = AR_TRACKING_STATE_STOPPED;
  ArTrackable_getTrackingState(ar_session, (ArTrackable*)ar_earth,
                               &earth_tracking_state);
  if (earth_tracking_state == AR_TRACKING_STATE_TRACKING) {
    ArAnchor* earth_anchor = NULL;
    ArStatus status = ArEarth_acquireNewAnchor(ar_session, ar_earth,
        /* location values */
        latitude, longitude, altitude,
        eus_quaternion_4, &earth_anchor);

    // Attach content to the anchor specified by geodetic location and
    // pose.
  }
}

Nota: la creazione di ancore a meno di 0,1 gradi dal Polo Nord o dal Polo Sud (90 gradi o -90 gradi) non è supportata. Se viene specificata un'ancora di questo tipo, la sua creazione non andrà a buon fine.

Ancore del terreno

Un'ancora del terreno è un tipo di ancora che ti consente di posizionare oggetti AR utilizzando solo latitudine e longitudine, sfruttando le informazioni del VPS per trovare l'altitudine esatta sopra il suolo.

Anziché inserire l'altitudine desiderata, fornisci l'altitudine sopra il terreno. Se il valore è zero, l'ancora sarà a livello del suolo.

Impostare la modalità di ricerca dell'aereo

La ricerca di aerei è facoltativa e non è necessaria per utilizzare le ancore. Tieni presente che vengono utilizzati solo piani orizzontali. I piani orizzontali favoriscono l'allineamento dinamico degli ancoraggi del terreno sul suolo.

Utilizza ArPlaneFindingMode per selezionare la modalità di rilevamento degli aerei da parte dell'app.

Creare un'ancora del terreno utilizzando la nuova API asincrona

Per creare e posizionare un'ancora del terreno, chiama ArEarth_resolveAnchorOnTerrainAsync().

L'ancora non sarà pronta immediatamente e dovrà essere risolta. Una volta risolto, sarà disponibile in ArResolveAnchorOnTerrainFuture.

Controlla lo stato dell'ancora del terreno utilizzando ArResolveAnchorOnTerrainFuture_getResultTerrainAnchorState(). Recupera l'ancora risolta utilizzando ArResolveAnchorOnTerrainFuture_acquireResultAnchor().

float eus_quaternion_4[4] = {qx, qy, qz, qw};
void* context = NULL;
ArResolveAnchorOnTerrainCallback callback = NULL;
ArResolveAnchorOnTerrainFuture* future = NULL;
if (ar_earth != NULL) {
  ArTrackingState earth_tracking_state = AR_TRACKING_STATE_STOPPED;
  ArTrackable_getTrackingState(ar_session, (ArTrackable*)ar_earth,
                               &earth_tracking_state);
  if (earth_tracking_state == AR_TRACKING_STATE_TRACKING) {
    ArStatus status = ArEarth_resolveAnchorOnTerrainAsync(
        ar_session, ar_earth,
        /* location values */
        latitude, longitude, altitude_above_terrain, eus_quaternion_4,
        context, callback, &future);
  }
}

Nota: la creazione di ancore a meno di 0,1 gradi dai poli Nord o Sud (90 gradi o -90 gradi) non è supportata. Se viene specificata un'ancora di questo tipo, ArEarth_resolveAnchorOnTerrainAsync() restituirà un AR_ERROR_INVALID_ARGUMENT e l'ancora non verrà creata.

Consulta lo stato del futuro

Al futuro sarà associato un ArFutureState.

Stato	Descrizione
AR_FUTURE_STATE_PENDING	L'operazione è ancora in attesa.
AR_FUTURE_STATE_DONE	L'operazione è completata e il risultato è disponibile.
AR_FUTURE_STATE_CANCELLED	L'operazione è stata annullata.

Controlla lo stato dell'ancora del terreno del risultato futuro

ArTerrainAnchorState appartiene all'operazione asincrona e fa parte del risultato finale Future.

switch (terrain_anchor_state) {
  case AR_TERRAIN_ANCHOR_STATE_SUCCESS:
    // A resolving task for this anchor has been successfully resolved.
    break;
  case AR_TERRAIN_ANCHOR_STATE_ERROR_UNSUPPORTED_LOCATION:
    // The requested anchor is in a location that isn't supported by the
    // Geospatial API.
    break;
  case AR_TERRAIN_ANCHOR_STATE_ERROR_NOT_AUTHORIZED:
    // An error occurred while authorizing your app with the ARCore API. See
    // https://developers.google.com/ar/reference/c/group/ar-anchor#:~:text=from%20this%20error.-,AR_TERRAIN_ANCHOR_STATE_ERROR_NOT_AUTHORIZED,-The%20authorization%20provided
    // for troubleshooting steps.
    break;
  case AR_TERRAIN_ANCHOR_STATE_ERROR_INTERNAL:
    // The Terrain anchor could not be resolved due to an internal error.
    break;
  default:
    break;
}

Ancoraggi sul tetto

Gli ancoraggi sul tetto sono un tipo di ancoraggio e sono molto simili agli ancoraggi sul terreno sopra descritti. La differenza è che dovrai fornire l'altitudine sopra il tetto anziché l'altitudine sopra il suolo.

Nota: alcune località hanno informazioni sui tetti più precise di altre. Per ulteriori informazioni, consulta la sezione Qualità in Geometria della scena urbana.

Creare un'ancora sul tetto utilizzando la nuova API asincrona

L'ancora non sarà pronta immediatamente e dovrà essere risolta.

Per creare e posizionare un'ancora sul tetto, chiama ArEarth_resolveAnchorOnRooftopAsync(). Analogamente agli ancoraggi del terreno, avrai accesso anche al ArFutureState del futuro. Poi puoi controllare il risultato futuro per accedere a ArRooftopAnchorState.

Utilizza ArEarth_resolveAnchorOnRooftopAsync() per creare un ArResolveAnchorOnRooftopFuture.

Controlla lo stato dell'ancoraggio sul tetto utilizzando ArResolveAnchorOnRooftopFuture_getResultRooftopAnchorState().

Recupera l'ancora risolta utilizzando ArResolveAnchorOnRooftopFuture_acquireResultAnchor().

float eus_quaternion_4[4] = {qx, qy, qz, qw};
void* context = NULL;
ArResolveAnchorOnRooftopCallback callback = NULL;
ArResolveAnchorOnRooftopFuture* future = NULL;
if (ar_earth != NULL) {
  ArTrackingState earth_tracking_state = AR_TRACKING_STATE_STOPPED;
  ArTrackable_getTrackingState(ar_session, (ArTrackable*)ar_earth,
                               &earth_tracking_state);
  if (earth_tracking_state == AR_TRACKING_STATE_TRACKING) {
    ArStatus status = ArEarth_resolveAnchorOnRooftopAsync(
        ar_session, ar_earth,
        /* location values */
        latitude, longitude, altitude_above_rooftop, eus_quaternion_4,
        context, callback, &future);
  }
}

Consulta lo stato del futuro

Al futuro sarà associato un ArFutureState, consulta la tabella sopra.

Controlla lo stato dell'ancora sul tetto del risultato futuro

ArRooftopAnchorState appartiene all'operazione asincrona e fa parte del risultato finale Future.

switch (rooftop_anchor_state) {
  case AR_ROOFTOP_ANCHOR_STATE_SUCCESS:
    // A resolving task for this anchor has been successfully resolved.
    break;
  case AR_ROOFTOP_ANCHOR_STATE_ERROR_UNSUPPORTED_LOCATION:
    // The requested anchor is in a location that isn't supported by the
    // Geospatial API.
    break;
  case AR_ROOFTOP_ANCHOR_STATE_ERROR_NOT_AUTHORIZED:
    // An error occurred while authorizing your app with the ARCore API. See
    // https://developers.google.com/ar/reference/c/group/ar-anchor#:~:text=from%20this%20error.-,AR_ROOFTOP_ANCHOR_STATE_ERROR_NOT_AUTHORIZED,-The%20authorization%20provided
    // for troubleshooting steps.
    break;
  case AR_ROOFTOP_ANCHOR_STATE_ERROR_INTERNAL:
    // The Rooftop anchor could not be resolved due to an internal error.
    break;
  default:
    break;
}

Passaggi successivi

• Assicurati di comprendere la quota di utilizzo dell'API geospaziale.