Kachel-Overlays

Ein Kachel-Overlay, auch als Kachelebene bezeichnet, ist eine Sammlung von Bildern, die über den Kacheln der Basiskarte dargestellt werden.

Codebeispiele

Das ApiDemos-Repository auf GitHub enthält ein Beispiel, das die Kachel-Overlay-Funktion veranschaulicht:

Einführung

Mit TileOverlay wird eine Reihe von Bildern definiert, die über den Kacheln der Basiskarte hinzugefügt werden.

Du musst die Kacheln für jede Zoomstufe bereitstellen, die unterstützt werden soll. Wenn du ausreichend Kacheln für verschiedene Zoomstufen hast, kannst du die Kartendaten von Google für die gesamte Karte ergänzen.

Kachel-Overlays sind hilfreich, um der Karte umfassendes Bildmaterial hinzuzufügen, zumeist um große geografische Bereiche abzudecken. Mit Boden-Overlays kann dagegen ein einzelnes Bild an einem Punkt der Karte fixiert werden.

Der Karte können mithilfe von transparenten Kachel-Overlays auch zusätzliche Merkmale hinzugefügt werden. Hierfür kannst du programmgesteuert einen Transparenzfaktor für das Kachel-Overlay festlegen oder transparente Kachelbilder bereitstellen.

Kachelkoordinaten und Zoomstufen

Google Maps API unterteilt die Bilder in jeder Zoomstufe in einen Satz quadratischer Kartenkacheln, die in einem Raster angeordnet sind. Wird eine Karte an eine neue Position verschoben oder eine neue Zoomstufe aufgerufen, ermittelt die Maps API, welche Kacheln erforderlich sind. Diese Daten werden dann in einen abzurufenden Kachelsatz übersetzt.

Die Kachel mit den Koordinaten (0,0) befindet sich immer in der nordwestlichen Ecke der Karte, wobei der x-Wert von West nach Ost und der y-Wert von Nord nach Süd ansteigt. Kacheln werden mithilfe der Koordinaten x und y dieses Ursprungs indiziert.

Bei Zoomstufe 0 wird die ganze Welt in einer einzigen Kachel gerendert. Jede Zoomstufe erhöht die Vergrößerung um den Faktor zwei. Entsprechend wird die Karte bei Zoomstufe 1 mit einem Raster von 2 x 2 Kacheln gerendert. Bei Zoomstufe 2 besteht das Raster aus 4 x 4 Kacheln. Bei Zoomstufe 3 besteht das Raster aus 8 x 8 Kacheln usw.

Bei Zoomstufe 2 wird die Erde beispielsweise in 16 Kacheln unterteilt. Auf jede Kachel kann durch eine eindeutige Kombination aus x, y und Zoom verwiesen werden.

Beim Erstellen von Bildern für eine Kachelebene musst du jeweils ein Bild für jede Kachel für jede Zoomstufe, die unterstützt werden soll, erstellen. Google Maps gibt 256 dp (Device-independent Pixel) für die Anzeige von Kacheln vor. Für Geräte mit hoher Auflösung empfiehlt sich die Verwendung von Kacheln mit hoher Auflösung (512 x 512 px). Informationen zur Unterstützung verschiedener Bildschirmgrößen und -dichten findest du in der Android-Entwicklerdokumentation.

Hinweis: Die von der Kamera unterstützten Zoomstufen sind von verschiedenen Faktoren abhängig und stehen in keinem Zusammenhang mit den Zoomstufen, die von deinen Kacheln unterstützt werden.

  1. GoogleMap.getMaxZoomLevel() gibt den maximalen Zoomfaktor zurück, der bei der aktuellen Kameraposition verfügbar ist. Dabei wird der aktuell verwendete Kartentyp berücksichtigt. So kann eine Satelliten- oder Geländekarte eine geringere maximale Zoomstufe haben als die Kacheln der Basiskarte.
  2. GoogleMap.getMinZoomLevel() gibt den minimalen Zoomfaktor zurück, der (im Gegensatz zum maximalen Zoomfaktor) für jeden Standort gleich ist, aber je nach Gerät und Kartengröße variieren kann.

Kachel-Overlays hinzufügen

Die einfachste und gängigste Methode zum Erstellen eines Kachel-Overlays ist die Bereitstellung einer URL, die auf das entsprechende Kachelbild verweist. UrlTileProvider ist eine Teilimplementierung von TileProvider zum Bereitstellen von Bildkacheln basierend auf einer URL. Für diese Klasse müssen alle Bilder dieselben Maße haben.

Die Implementierung von UrlTileProvider.getTileUrl() ist erforderlich, damit die Kachelkoordinaten (x, y, Zoom) akzeptiert werden und eine URL zurückgegeben wird, die auf das für die Kachel zu verwendende Bild verweist. Das Ergebnis dieser Methode sollte null lauten, wenn für die angegebenen x-, y- und Zoom-Werte keine Kachel vorhanden ist. Eine URL kann auf eine Webressource, ein Android-Objekt oder eine Datei auf einer lokalen Festplatte verweisen.

Hinterlege deine gesamten Kachelbilder inklusive der Definition für alle x- und y-Koordinaten und Zoomstufen, die unterstützt werden sollen, auf einem Server. Füge anschließend das Kachel-Overlay hinzu:

  1. Definiere einen UrlTileProvider, um die Kachelbilder bereitzustellen.
  2. Überschreibe getTileUrl(), um die URL für jedes Kachelbild zu erstellen.
  3. Gib ein TileOverlayOptions-Objekt mit den relevanten Optionen an:
    • fadeIn: Boolesch. Gibt an, ob die Kacheln langsam eingeblendet werden sollen. Der Standardwert ist true. Es kann sinnvoll sein, das Einblenden zu deaktivieren, wenn schnell zwischen Kachel-Overlays gewechselt werden soll. Informationen zur Beziehung zwischen Transparenz und Einblenden findest du weiter unten im Abschnitt Transparenz.
    • tileProvider: Der für dieses Overlay zu verwendende TileProvider.
    • transparency: Gleitkommazahl. Legt einen Transparenzfaktor für Kachelbilder fest. Der Wert muss im Bereich [0.0f, 1.0f] liegen, wobei 0.0f vollständig deckend (Standard) und 1.0f vollständig transparent bedeutet. Im Abschnitt Transparenz weiter unten findest du ein Codebeispiel und Informationen zur Beziehung zwischen Transparenz und Einblenden.
    • visible: Boolesch. Gibt die Sichtbarkeit des Kachel-Overlays an. Ein unsichtbares Kachel-Overlay (Wert false) wird nicht auf der Karte dargestellt, behält aber alle anderen Eigenschaften bei. Der Standardwert ist true.
    • zIndex: Bestimmt die Reihenfolge, in der das Kachel-Overlay im Verhältnis zu anderen Overlays wie Boden-Overlays, Kreise, Polylinien und Polygone gezeichnet werden. Overlays mit einem höheren Z-Index werden über Overlays mit kleineren Z-Indizes gezogen. Die Reihenfolge von Overlays mit identischen Z-Indizes ist beliebig. Der Standard-Z-Index ist 0. Hinweis: Markierungen werden unabhängig von dem Z-Index der anderen Overlays immer über anderen Overlays gezeichnet.
  4. Rufe GoogleMap.addTileOverlay() auf, um das Overlay zur Karte hinzuzufügen.

Java

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

Kotlin

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

Ein Beispiel für UrlTileProvider in Aktion findest du in TileOverlayDemoActivity im Beispielcode, der im Google Play Services SDK enthalten ist.

Transparenz für Kachel-Overlays festlegen

Es kann nützlich sein, transparente Kacheln als Overlays auf der Karte zu platzieren, sodass die Nutzer die Basiskarte unter den überlagerten Kacheln sehen können. Hierfür kannst du deine eigenen transparenten Kacheln bereitstellen oder programmgesteuert einen Transparenzfaktor für das Kachel-Overlay festlegen.

Im folgenden Codebeispiel wird die Transparenz des Kachel-Overlays zwischen 0.5f und 0.0f umgeschaltet:

Java

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());
    }
}
      

Kotlin

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
    }
}
      

Die Transparenz wird als Alpha-Kanal-Multiplikator für die Kachelbilder implementiert. Zum Festlegen der Transparenz eines Kachel-Overlays stellst du ein TileOverlayOptions-Objekt mit einem transparency im Bereich [0.0f, 1.0f] bereit, wie in der Abbildung oben gezeigt. Der Wert 0.0f bedeutet, dass das Kachel-Overlay vollständig deckend ist, und 1.0f bedeutet, dass es vollständig transparent ist. Der Standardwert ist 0.0f (deckend).

Du kannst auf die Transparenz des Kachel-Overlays zugreifen, indem du TileOverlay.getTransparency() aufrufst. Durch Aufrufen von TileOverlay.setTransparency() lässt sie sich ändern.

Transparenz, Animation und Einblenden

Wenn sich die Transparenz ändert, erfolgt keine Animation. Die Tranzparenzoption wird zusammen mit der Option fadeIn verwendet.

Mithilfe der Einblendfunktion wird die Transparenz beim Laden der Kacheln animiert. Wenn du einen Transparenzwert festlegst, verläuft die Einblendung der Kacheln von vollständig transparent bis zum definierten Transparenzwert. Falls du den Transparenzwert während des Einblendvorgangs änderst, wird die Animation bis zur neuen Zieltransparenz fortgesetzt.

Kachel-Overlays entfernen

Kachel-Overlays können mit der Methode TileOverlay.remove() entfernt werden.

Java

tileOverlay.remove();
      

Kotlin

tileOverlay.remove()
      

Veraltete Kacheln löschen

Wenn die vom Kachel-Overlay bereitgestellten Kacheln veraltet sind, kannst du clearTileCache() aufrufen, um eine Aktualisierung zu erzwingen. Das führt dazu, dass alle Kacheln dieses Overlays neu geladen werden. Wenn sich die von TileProvider bereitgestellten Kacheln ändern, musst du anschließend clearTileCache() aufrufen, damit die vorherigen Kacheln nicht mehr gerendert werden.

Java

tileOverlay.clearTileCache();
      

Kotlin

tileOverlay.clearTileCache()