Sovrapposizioni riquadri

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

Esempi di codice

Il repository ApiDemos su GitHub include un esempio che dimostra la funzionalità di overlay dei riquadri:

• TileOverlayDemoActivity - Java: funzionalità di overlay dei riquadri in Java
• TileCoordinateDemoActivity - Java: il sistema di coordinate utilizzato per gli overlay dei riquadri in Java
• TileOverlayDemoActivity - Kotlin: funzionalità di overlay dei riquadri in Kotlin
• TileCoordinateDemoActivity - Kotlin: il sistema di coordinate utilizzato per gli overlay dei riquadri 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 delle mappe di Google per l'intera mappa.

Gli overlay riquadro sono utili quando vuoi aggiungere immagini estese alla mappa, in genere coprendo grandi aree geografiche. Al contrario, gli overlay al suolo sono utili quando vuoi correggere una singola immagine in un'area della mappa.

Puoi inoltre utilizzare overlay di riquadri trasparenti per aggiungere ulteriori funzionalità alla mappa, impostando in modo programmatico un fattore di trasparenza sull'overlay dei riquadri o fornendo immagini dei riquadri trasparenti.

Coordinate dei riquadri e livelli di zoom

L'API di Google Maps suddivide le immagini a ogni livello di zoom in una serie 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 i valori x che aumentano da ovest a est e i valori y che aumentano da nord a sud. I riquadri vengono indicizzati utilizzando le coordinate x e y di tale origine.

A livello di zoom 0, il mondo intero viene visualizzato in un unico riquadro. Ogni livello di zoom aumenta l'ingrandimento di un fattore di due. Quindi, a livello di zoom 1, la mappa viene visualizzata come una griglia di riquadri 2x2. A livello di zoom 2, è una griglia 4 x 4. A livello di zoom 3, si tratta di una griglia 8x8 e così via.

Ad esempio, a livello di zoom 2 la Terra viene divisa in 16 riquadri. È possibile fare riferimento a ogni riquadro tramite una combinazione univoca di x, y e zoom:

Quando crei immagini per un livello di riquadro, devi creare un'immagine per ogni riquadro a ogni livello di zoom che vuoi supportare. Google Maps sceglie come target 256 dp (pixel indipendenti dal dispositivo) quando vengono visualizzati riquadri. Per i dispositivi ad alta risoluzione, è consigliabile restituire riquadri con risoluzione elevata (512 x 512 px). Consulta la documentazione per gli sviluppatori Android per informazioni sul supporto di dimensioni e densità dello schermo diverse.

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 massimo di zoom disponibile nella posizione corrente della fotocamera. Tiene conto del tipo di mappa attualmente in uso. Ad esempio, un satellite o una mappa del rilievo può 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 tutte le località (a differenza del livello massimo di zoom), ma può variare in base al dispositivo e alle dimensioni della mappa.

Aggiungi un overlay riquadro

Il modo più semplice e comune di creare un overlay riquadro è fornire un URL che rimandi all'immagine riquadro pertinente. UrlTileProvider è un'implementazione parziale di TileProvider che fornisce riquadri di immagini in base a 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 è presente alcun riquadro per le coppie x, y e zoom specificati. Un URL può puntare a una risorsa web, a un asset Android o a un file sul disco locale.

Configura lo stock di immagini dei riquadri su un server, definito 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 dei riquadri.
2. Esegui l'override di getTileUrl() per creare l'URL per ogni immagine riquadro.
3. Fornisci un oggetto TileOverlayOptions con le opzioni pertinenti:
• fadeIn: valore booleano. Specifica se i riquadri devono avere una dissolvenza in entrata. Il valore predefinito è true. Può essere utile disattivare la dissolvenza in entrata quando si passa rapidamente da un overlay dei riquadri all'altro. Per informazioni sul rapporto tra trasparenza e dissolvenza in entrata, consulta la sezione sulla trasparenza di seguito.
• tileProvider: il valore TileProvider da utilizzare per questo overlay.
• transparency: numero mobile. Imposta un fattore di trasparenza per le immagini dei riquadri. Il valore deve essere compreso nell'intervallo [0.0f, 1.0f], dove 0.0f significa completamente opaco (impostazione predefinita) e 1.0f significa completamente trasparente. Consulta la sezione sulla trasparenza di seguito per un esempio di codice e la relazione tra trasparenza e dissolvenza in entrata.
• visible: valore booleano. Specifica la visibilità dell'overlay dei riquadri. Un overlay riquadro invisibile (valore false) non viene tracciato sulla mappa, ma conserva tutte le altre proprietà. Il valore predefinito è true.
• zIndex: determina l'ordine in cui verrà disegnato l'overlay del riquadro rispetto ad altri overlay, inclusi overlay del suolo , cerchi, polilinee e poligoni. Le sovrapposizioni con uno z-index più elevato vengono disegnate sopra quelle con uno z-index più basso. L'ordine degli overlay con lo stesso z-index è arbitrario. Il valore predefinito z-index è 0. Tieni presente che gli indicatori vengono sempre visualizzati sopra gli altri overlay, indipendentemente dallo z-index degli altri overlay.
4. Chiama GoogleMap.addTileOverlay() per aggiungere l'overlay alla mappa.

private lateinit var map: GoogleMap

var 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)
)

      

private GoogleMap map;

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("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 integrato nell'SDK Google Play Services.

Impostare la trasparenza per gli overlay dei riquadri

Può essere utile sovrapporre riquadri trasparenti sulla mappa, in modo che gli utenti possano vedere la mappa base sotto i riquadri sovrapposti. Per farlo, fornisci i tuoi riquadri trasparenti o imposta un fattore di trasparenza sull'overlay del riquadro in modo programmatico.

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

private var tileOverlayTransparent: TileOverlay? = null

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

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

      

private TileOverlay tileOverlayTransparent;

@Override
public void onMapReady(GoogleMap map) {
    tileOverlayTransparent = map.addTileOverlay(new TileOverlayOptions()
        .tileProvider(new UrlTileProvider(256, 256) {
            // ...
        })
        .transparency(0.5f));
}

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

      

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

Puoi accedere alla trasparenza dell'overlay del riquadro chiamando TileOverlay.getTransparency() e modificandola chiamando TileOverlay.setTransparency().

Trasparenza, animazione e dissolvenza in entrata

Quando la trasparenza viene modificata, non viene visualizzata alcuna animazione. L'opzione Trasparenza opera insieme all'opzione fadeIn.

La dissolvenza in entrata fornisce un'animazione della trasparenza al caricamento del riquadro. Se imposti un valore di trasparenza, i riquadri presentano una 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 di riquadro con il metodo TileOverlay.remove().

tileOverlay?.remove()

      

tileOverlay.remove();

      

Cancella riquadri inattivi

Se i riquadri forniti dall'overlay dei riquadri diventano "inattivi", puoi chiamare clearTileCache() per forzare l'aggiornamento. 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();