Sovrapposizioni riquadri

Un overlay riquadri, a volte chiamato livello riquadro, è una raccolta di immagini che vengono visualizzate sopra i riquadri della mappa base.

Esempi di codice

Il repository ApiDemos su GitHub include un esempio che mostra la funzionalità di overlay riquadro:

• TileOverlayDemoActivity - Java: funzionalità di overlay riquadro in Java
• TileCoordinateDemoActivity - Java: il sistema di coordinate utilizzato per gli overlay riquadro in Java
• TileOverlayDemoActivity - Kotlin: funzionalità di overlay riquadro in Kotlin
• TileCoordinateDemoActivity - Kotlin: il sistema di coordinate utilizzato per gli overlay riquadro in Kotlin

Introduzione

Un TileOverlay definisce un insieme di immagini che vengono aggiunte sopra i riquadri della mappa base.

Devi fornire i riquadri per ogni livello di zoom che vuoi supportare. Se hai un numero sufficiente di riquadri a più livelli di zoom, puoi integrare i dati della mappa di Google per l'intera mappa.

Gli overlay riquadro sono utili quando vuoi aggiungere immagini estese alla mappa, in genere che coprono grandi aree geografiche. Al contrario, gli overlay di terra sono utili quando vuoi fissare una singola immagine in un'area della mappa.

Puoi anche utilizzare overlay riquadro trasparenti per aggiungere funzionalità extra alla mappa, impostando un fattore di trasparenza sull'overlay riquadro a livello di programmazione o fornendo immagini riquadro trasparenti.

Coordinate dei riquadri e livelli di zoom

L'API di Google Maps suddivide le immagini a ogni livello di zoom in un insieme di riquadri della mappa quadrati disposti in una griglia. Quando una mappa si sposta in una nuova posizione o a un nuovo livello di zoom, l'API di Google Maps determina quali riquadri sono necessari e traduce queste informazioni in un insieme di riquadri da recuperare.

Il riquadro con coordinate (0,0) si trova sempre nell'angolo nord-ovest della mappa, con valori x che aumentano da ovest a est e valori y che aumentano da nord a sud. I riquadri vengono indicizzati utilizzando le coordinate x,y dall'origine.

Al livello di zoom 0, il mondo intero viene visualizzato in un singolo riquadro. Ogni livello di zoom aumenta l'ingrandimento di un fattore due. Pertanto, al livello di zoom 1 la mappa verrà visualizzata come una griglia di riquadri 2x2. Al livello di zoom 2, è una griglia 4x4. Al livello di zoom 3, è una griglia 8x8 e così via.

Ad esempio, al livello di zoom 2 la terra è suddivisa in 16 riquadri. È possibile fare riferimento a ogni riquadro tramite una combinazione univoca di x, y e zoom:

Quando crei immagini per un livello riquadro, devi creare un'immagine per ogni riquadro a ogni livello di zoom che vuoi supportare. Google Maps ha come target 256 dp (pixel indipendenti dal dispositivo) quando visualizza i riquadri. Per i dispositivi ad alta risoluzione, ti consigliamo di restituire riquadri ad alta risoluzione (512x512 px). Per informazioni sul supporto di diverse dimensioni e densità dello schermo, consulta la documentazione per lo sviluppo Android.

Nota: i livelli di zoom supportati dalla fotocamera dipendono da vari fattori, e non sono correlati ai livelli di zoom supportati dai riquadri.

1. GoogleMap.getMaxZoomLevel() restituisce il livello di zoom massimo disponibile nella posizione attuale della fotocamera. Questo tiene conto del tipo di mappa attualmente in uso. Ad esempio, una mappa satellitare o del rilievo potrebbe avere un livello di zoom massimo inferiore rispetto ai riquadri della mappa base.
2. GoogleMap.getMinZoomLevel() restituisce il livello di zoom minimo, che è lo stesso per ogni località (a differenza del livello di zoom massimo), ma può variare a seconda dei dispositivi e delle dimensioni della mappa.

Aggiungere un overlay riquadro

Il modo più semplice e comune per creare un overlay riquadro è fornire un URL che rimanda all'immagine riquadro pertinente. UrlTileProvider è un'implementazione parziale di TileProvider che fornisce riquadri immagine basati su un URL. Questa classe richiede che tutte le immagini abbiano le stesse dimensioni.

Dovrai implementare UrlTileProvider.getTileUrl(), che accetta le coordinate del riquadro (x, y, zoom) e restituisce un URL che rimanda all' immagine da utilizzare per il riquadro. Il metodo deve restituire null se non esiste un riquadro per i valori x, y e zoom specificati. Un URL può rimandare a una risorsa web, a un asset Android o a un file sul disco locale.

Configura la scorta di immagini riquadro su un server, definita per tutte le coordinate x,y e i livelli di zoom che intendi supportare. Quindi aggiungi l'overlay riquadro:

1. Definisci un UrlTileProvider per fornire le immagini riquadro.
2. Esegui l'override di getTileUrl() per creare l'URL di ogni immagine riquadro.
3. Fornisci un TileOverlayOptions oggetto con le opzioni pertinenti:
• fadeIn: booleano. Specifica se i riquadri devono essere visualizzati con dissolvenza in entrata. Il valore predefinito è true. Potrebbe essere utile disattivare la dissolvenza in entrata quando passi rapidamente da un overlay riquadro all'altro. Per informazioni sulla relazione tra trasparenza e dissolvenza in entrata, consulta la sezione sulla trasparenza di seguito.
• tileProvider: il TileProvider da utilizzare per questo overlay.
• transparency: float. Imposta un fattore di trasparenza per le immagini riquadro. Il valore deve essere compreso nell'intervallo [0.0f, 1.0f] dove 0.0f significa completamente opaco (valore predefinito) e 1.0f significa completamente trasparente. Per un esempio di codice e per informazioni sulla relazione tra trasparenza e dissolvenza in entrata, consulta la sezione sulla trasparenza di seguito.
• visible: booleano. Specifica la visibilità dell'overlay riquadro. Un overlay riquadro invisibile (valore false) non viene disegnato sulla mappa, ma mantiene tutte le altre proprietà. Il valore predefinito è true.
• zIndex: determina l'ordine in cui l'overlay riquadro verrà disegnato rispetto ad altri overlay, inclusi overlay di terra , cerchi, polilinee e poligoni. Gli overlay con un indice z più alto vengono disegnati sopra quelli con indici z più bassi. L'ordine degli overlay con lo stesso indice z è arbitrario. L'indice z predefinito è 0. Tieni presente che i marker vengono sempre disegnati sopra gli altri overlay, indipendentemente dall'indice z degli altri overlay.
4. Chiama GoogleMap.addTileOverlay() per aggiungere l'overlay alla mappa.

val tileProvider: TileProvider = object : UrlTileProvider(256, 256) {
    override fun getTileUrl(x: Int, y: Int, zoom: Int): URL? {

        /* Define the URL pattern for the tile images */
        val url = "http://my.image.server/images/$zoom/$x/$y.png"
        return if (!checkTileExists(x, y, zoom)) {
            null
        } else try {
            URL(url)
        } catch (e: MalformedURLException) {
            throw AssertionError(e)
        }
    }

    /*
     * Check that the tile server supports the requested x, y and zoom.
     * Complete this stub according to the tile range you support.
     * If you support a limited range of tiles at different zoom levels, then you
     * need to define the supported x, y range at each zoom level.
     */
    private fun checkTileExists(x: Int, y: Int, zoom: Int): Boolean {
        val minZoom = 12
        val maxZoom = 16
        return zoom in minZoom..maxZoom
    }
}

val tileOverlay = map.addTileOverlay(
    TileOverlayOptions()
        .tileProvider(tileProvider)
)
tileOverlay?.let {
    val isVisible = it.isVisible
    val fadeIn = it.fadeIn
    val transparency = it.transparency
    val zIndex = it.zIndex
}

      

TileProvider tileProvider = new UrlTileProvider(256, 256) {

    @Override
    public URL getTileUrl(int x, int y, int zoom) {

        /* Define the URL pattern for the tile images */
        String s = String.format(java.util.Locale.US, "http://my.image.server/images/%d/%d/%d.png", zoom, x, y);

        if (!checkTileExists(x, y, zoom)) {
            return null;
        }

        try {
            return new URL(s);
        } catch (MalformedURLException e) {
            throw new AssertionError(e);
        }
    }

    /*
     * Check that the tile server supports the requested x, y and zoom.
     * Complete this stub according to the tile range you support.
     * If you support a limited range of tiles at different zoom levels, then you
     * need to define the supported x, y range at each zoom level.
     */
    private boolean checkTileExists(int x, int y, int zoom) {
        int minZoom = 12;
        int maxZoom = 16;

        return (zoom >= minZoom && zoom <= maxZoom);
    }
};

TileOverlay tileOverlay = map.addTileOverlay(new TileOverlayOptions()
    .tileProvider(tileProvider));

      

Per vedere un esempio di UrlTileProvider in azione, consulta TileOverlayDemoActivity nel codice campione incluso nell'SDK di Google Play Services.

Impostare la trasparenza per gli overlay riquadro

Può essere utile sovrapporre riquadri trasparenti alla mappa, in modo che gli utenti possano vedere la mappa base sotto i riquadri sovrapposti. Puoi farlo fornendo i tuoi riquadri trasparenti o impostando un fattore di trasparenza sull'overlay riquadro a livello di programmazione.

Il seguente esempio di codice attiva/disattiva la trasparenza dell'overlay riquadro tra 0.5f e 0.0f:

val tileOverlayTransparent = map.addTileOverlay(
    TileOverlayOptions()
        .tileProvider(object : UrlTileProvider(256, 256) {
            // ...
        })
        .transparency(0.5f)
)

// Switch between 0.0f and 0.5f transparency.
tileOverlayTransparent?.let {
    it.transparency = 0.5f - it.transparency
}

      

TileOverlay tileOverlayTransparent = map.addTileOverlay(new TileOverlayOptions()
    .tileProvider(new UrlTileProvider(256, 256) {
        // ...
    })
    .transparency(0.5f));

// Switch between 0.0f and 0.5f transparency.
if (tileOverlayTransparent != null) {
    tileOverlayTransparent.setTransparency(0.5f - tileOverlayTransparent.getTransparency());
}

      

La trasparenza viene implementata come moltiplicatore del canale alfa per le immagini riquadro. Per impostare la trasparenza di un overlay riquadro, fornisci un TileOverlayOptions oggetto con un transparency nell'intervallo [0.0f, 1.0f] come mostrato nell'esempio sopra. Un valore di 0.0f indica che l'overlay riquadro è completamente opaco, mentre 1.0f indica che è completamente trasparente. Il valore predefinito è 0.0f (opaco).

Puoi accedere alla trasparenza dell'overlay riquadro chiamando TileOverlay.getTransparency(), e puoi modificarla chiamando TileOverlay.setTransparency().

Trasparenza, animazione e dissolvenza in entrata

Non è presente alcuna animazione quando la trasparenza viene modificata. L'opzione di trasparenza funziona insieme all' fadeIn.

La dissolvenza in entrata fornisce l'animazione della trasparenza al caricamento del riquadro. Se imposti un valore di trasparenza, i riquadri vengono visualizzati con dissolvenza in entrata da completamente trasparenti al valore di trasparenza definito. Se modifichi la trasparenza durante la dissolvenza in entrata, l' animazione continua verso la nuova trasparenza di destinazione.

Rimuovere un overlay riquadro

Puoi rimuovere un overlay riquadro con il TileOverlay.remove() metodo.

tileOverlay?.remove()

      

tileOverlay.remove();

      

Cancellare i riquadri obsoleti

Se i riquadri forniti dall'overlay riquadro diventano 'obsoleti', puoi chiamare clearTileCache() per forzare un aggiornamento. In questo modo, tutti i riquadri di questo overlay verranno ricaricati. Ad esempio, se i riquadri forniti da TileProvider cambiano, devi chiamare clearTileCache() in seguito per assicurarti che i riquadri precedenti non vengano più visualizzati.

tileOverlay?.clearTileCache()

      

tileOverlay.clearTileCache();