Overlay al suolo

Seleziona la piattaforma: Android iOS JavaScript

Gli overlay del suolo sono overlay di immagini legati alle coordinate di latitudine/longitudine, quindi si spostano quando trascini la mappa o ne aumenti lo zoom.

Esempi di codice

Il repository ApiDemos su GitHub include un esempio che mostra gli overlay del suolo:

• GroundOverlayDemoActivity - Java: elementi e ascoltatori di overlay sul suolo in Java
• GroundOverlayDemoActivity - Kotlin: elementi e ascoltatori di overlay sul suolo in Kotlin

Introduzione

Un overlay del suolo è un'immagine fissa a una mappa. A differenza dei indicatori, gli overlay del terreno sono orientati in base alla superficie terrestre anziché allo schermo, pertanto ruotare, inclinare o aumentare lo zoom della mappa cambia l'orientamento dell'immagine. Gli overlay del suolo sono utili quando vuoi correggere una singola immagine in un'area della mappa. Se vuoi aggiungere immagini estese che coprono una vasta porzione della mappa, ti consigliamo di utilizzare un riquadro in overlay.

Aggiungere un overlay

Per aggiungere un GroundOverlay, crea un oggetto GroundOverlayOptions che definisce sia un'immagine sia una posizione. Se vuoi, puoi specificare impostazioni aggiuntive che influiscono sul posizionamento dell'immagine sulla mappa. Dopo aver definito le opzioni necessarie, passa l'oggetto al metodo GoogleMap.addGroundOverlay() per aggiungere l'immagine alla mappa. Il metodo addGroundOverlay() restituisce un oggetto GroundOverlay. Devi conservare un riferimento a questo oggetto se vuoi modificarlo in un secondo momento.

Nota: quando l'immagine viene aggiunta alla mappa, viene convertita in un'immagine con lati che sono potenze di 2. Puoi evitare questa conversione utilizzando un'immagine originale con dimensioni che sono potenze di due, ad esempio 128 x 512 o 1024 x 1024.

Procedura passo passo:

1. Creare un nuovo oggetto GroundOverlayOptions
2. Specifica l'immagine come BitmapDescriptor.
3. Imposta la posizione dell'immagine utilizzando uno dei metodi disponibili:
   • position(LatLng location, float width, float height)
   • position(LatLng location, float width)
   • positionFromBounds(LatLngBounds bounds)
4. Imposta eventuali proprietà facoltative, ad esempio transparency, come preferisci.
5. Chiama GoogleMap.addGroundOverlay() per aggiungere l'immagine alla mappa.

L'esempio seguente mostra come aggiungere un overlay del suolo a un oggetto GoogleMap esistente.

Kotlin

val newarkLatLng = LatLng(40.714086, -74.228697)
val newarkMap = GroundOverlayOptions()
    .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922))
    .position(newarkLatLng, 8600f, 6500f)
map.addGroundOverlay(newarkMap)

      

Java

LatLng newarkLatLng = new LatLng(40.714086, -74.228697);

GroundOverlayOptions newarkMap = new GroundOverlayOptions()
    .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922))
    .position(newarkLatLng, 8600f, 6500f);
map.addGroundOverlay(newarkMap);

      

Se vuoi modificare o rimuovere un overlay del terreno dopo averlo aggiunto alla mappa, assicurati di tenere premuto l'oggetto GroundOverlay. Puoi modificare l'overlay in un secondo momento apportando modifiche a questo oggetto.

Kotlin

// Add an overlay to the map, retaining a handle to the GroundOverlay object.
val imageOverlay = map.addGroundOverlay(newarkMap)

      

Java

// Add an overlay to the map, retaining a handle to the GroundOverlay object.
GroundOverlay imageOverlay = map.addGroundOverlay(newarkMap);

      

Rimuovere un overlay

Puoi rimuovere un overlay del suolo con il metodo GroundOverlay.remove().

Kotlin

imageOverlay?.remove()

      

Java

imageOverlay.remove();

      

Modificare un overlay

Puoi modificare l'immagine dell'overlay del suolo dopo che è stata aggiunta alla mappa con il metodo GroundOverlay.setImage(BitmapDescriptor).

Kotlin

// Update the GroundOverlay with a new image of the same dimension
imageOverlay?.setImage(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922))

      

Java

// Update the GroundOverlay with a new image of the same dimension
imageOverlay.setImage(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922));

      

Il metodo setImage() sostituirà l'immagine esistente con un'altra delle stesse dimensioni.

Posizionare un overlay del suolo

Esistono due modi per specificare la posizione dell'overlay del suolo:

• Utilizza un LatLng per centrare l'overlay e le dimensioni in metri per specificare le dimensioni dell'immagine.
• Utilizza un LatLngBounds per specificare gli angoli nord-est e sud-ovest dell'immagine.

Devi specificare la posizione dell'overlay del suolo prima che venga aggiunto alla mappa.

Utilizzare la posizione per posizionare un'immagine

Quando aggiungi l'immagine, specifica un valore LatLng a cui verrà fissata l'ancora e la larghezza dell'overlay (in metri). Per impostazione predefinita, il valore di anchor è il centro dell'immagine. Se vuoi, puoi fornire l'altezza dell'overlay (in metri). Se non fornisci l'altezza dell'overlay, verrà calcolata automaticamente in modo da preservare le proporzioni dell'immagine.

Il codice seguente posiziona un'immagine nella posizione 40.714086, -74.228697 che è larga 8,6 km e alta 6,5 km. L'immagine è ancorata in basso a sinistra.

Kotlin

val newarkMap = GroundOverlayOptions()
    .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922))
    .anchor(0f, 1f)
    .position(LatLng(40.714086, -74.228697), 8600f, 6500f)

      

Java

GroundOverlayOptions newarkMap = new GroundOverlayOptions()
    .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922))
    .anchor(0, 1)
    .position(new LatLng(40.714086, -74.228697), 8600f, 6500f);

      

Utilizzare LatLngBounds per posizionare un'immagine

Fornisci un LatLngBounds contenente l'immagine. LatLngBounds imposta i vertici nord-est e sud-ovest dell'immagine. Quando l'immagine viene disegnata sulla mappa, viene ruotata in modo da adattarsi ai limiti. Se i limiti non corrispondono alle proporzioni originali, l'immagine sarà inclinata.

Il codice riportato di seguito inserisce un'immagine sulla mappa con il suo angolo sud-ovest vincolato a 40.712216,-74.22655 e il suo angolo nord-est vincolato a 40.773941, -74.12544.

Kotlin

val newarkBounds = LatLngBounds(
    LatLng(40.712216, -74.22655),  // South west corner
    LatLng(40.773941, -74.12544)   // North east corner
)
val newarkMap = GroundOverlayOptions()
    .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922))
    .positionFromBounds(newarkBounds)

      

Java

LatLngBounds newarkBounds = new LatLngBounds(
    new LatLng(40.712216, -74.22655),       // South west corner
    new LatLng(40.773941, -74.12544));      // North east corner
GroundOverlayOptions newarkMap = new GroundOverlayOptions()
    .image(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1922))
    .positionFromBounds(newarkBounds);

      

Associare i dati a un overlay del suolo

Puoi chiamare GroundOverlay.setTag() per archiviare un oggetto dati arbitrario con un overlay al suolo e recuperare l'oggetto dati utilizzando GroundOverlay.getTag().

Il seguente esempio di codice memorizza una descrizione di stringa con un overlay del suolo:

Kotlin

val sydneyGroundOverlay = map.addGroundOverlay(
    GroundOverlayOptions()
        .image(BitmapDescriptorFactory.fromResource(R.drawable.harbour_bridge))
        .position(LatLng(-33.873, 151.206), 100f)
        .clickable(true)
)
sydneyGroundOverlay?.tag = "Sydney"

      

Java

GroundOverlay sydneyGroundOverlay = map.addGroundOverlay(new GroundOverlayOptions()
    .image(BitmapDescriptorFactory.fromResource(R.drawable.harbour_bridge))
    .position(new LatLng(-33.873, 151.206), 100)
    .clickable(true));

sydneyGroundOverlay.setTag("Sydney");

      

Di seguito sono riportati alcuni esempi di scenari in cui è utile archiviare e recuperare i dati con overlay del suolo:

• La tua app potrebbe supportare diversi overlay del suolo e vuoi gestirli in modo diverso quando l'utente li fa clic.
• Potresti interagire con un sistema che dispone di identificatori di record univoci, dove gli overlay rappresentano record specifici in quel sistema.
• I dati dell'overlay possono indicare una priorità per determinare l'indice z per l'overlay.

Gestire gli eventi di overlay del suolo

Per impostazione predefinita, gli overlay del suolo non sono cliccabili. Puoi attivare e disattivare la possibilità di fare clic chiamando GroundOverlay.setClickable(boolean).

Utilizza un OnGroundOverlayClickListener per ascoltare gli eventi di clic su un overlay del suolo cliccabile. Per impostare questo listener sulla mappa, chiama GoogleMap.setOnGroundOverlayClickListener(OnGroundOverlayClickListener). Quando un utente fa clic su un overlay del suolo, riceverai un callbackonGroundOverlayClick(GroundOverlay).

Nota: se più overlay o forme (indicatori, polilinee, poligoni, cerchi e/o overlay del suolo) sono sovrapposti, l'evento di clic viene visualizzato prima nel cluster di indicatori, quindi attivato per altri overlay o forme cliccabili in base ai relativi valori z-index. Per ogni clic viene attivato al massimo un evento. In altre parole, il clic non viene trasmesso agli overlay o alle forme con valori z-index inferiori. Scopri di più su indice z degli indicatori ed eventi di clic.