Boden-Overlays

Boden-Overlays sind Bild-Overlays, die an Breiten- und Längengrad gebunden sind, sodass sie sich beim Ziehen und Zoomen der Karte mitbewegen.

Codebeispiele

Das ApiDemos-Repository auf GitHub enthält ein Beispiel für Boden-Overlays:

Einführung

Ein Boden-Overlay ist ein Bild, das auf einer Karte fixiert ist. Im Unterschied zu Markierungen sind Boden-Overlays auf die Erdoberfläche und nicht auf den Bildschirm ausgerichtet. Deshalb wirkt sich das Drehen, Neigen oder Zoomen der Karte auf die Ausrichtung des Bilds aus. Mit Boden-Overlays kann ein einzelnes Bild an einem Punkt der Karte fixiert werden. Wenn du umfangreiches Bildmaterial hinzufügen möchtest, das einen großen Teil der Karte abdeckt, solltest du es mit einem Kachel-Overlay versuchen.

Overlay hinzufügen

Um ein GroundOverlay hinzuzufügen, erstellst du ein GroundOverlayOptions-Objekt, das sowohl ein Bild als auch eine Position definiert. Du kannst außerdem zusätzliche Einstellungen angeben, die die Positionierung des Bilds auf der Karte beeinflussen. Nachdem du die erforderlichen Optionen definiert hast, übergibst du das Objekt an die GoogleMap.addGroundOverlay()-Methode, um das Bild der Karte hinzuzufügen. Über die addGroundOverlay()-Methode wird ein GroundOverlay-Objekt zurückgegeben. Ein Verweis auf dieses Objekt sollte beibehalten werden, falls du es später ändern möchtest.

Schritte:

  1. Instanziiere ein neues GroundOverlayOptions-Objekt.
  2. Gib das Bild als BitmapDescriptor an.
  3. Lege die Position des Bilds mithilfe einer der verfügbaren Methoden fest:
    • position(LatLng location, float width, float height)
    • position(LatLng location, float width)
    • positionFromBounds(LatLngBounds bounds)
  4. Lege bei Bedarf optionale Eigenschaften wie z. B. transparency fest.
  5. Rufe GoogleMap.addGroundOverlay() auf, um das Bild zur Karte hinzuzufügen.

Das folgenden Beispiel zeigt, wie ein Boden-Overlay einem vorhandenen GoogleMap-Objekt hinzugefügt wird:

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

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

Wenn du ein Boden-Overlay ändern oder entfernen möchtest, nachdem du es der Karte hinzugefügt hast, muss das Objekt GroundOverlay beibehalten werden. Du kannst das Overlay später über dieses Objekt ändern.

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

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

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

Overlay entfernen

Du kannst ein Boden-Overlay mit der Methode GroundOverlay.remove() entfernen.

imageOverlay.remove();

Overlay ändern

Du kannst das Boden-Overlay-Bild ändern, nachdem es der Karte mit der Methode GroundOverlay.setImage(BitmapDescriptor) hinzugefügt wurde.

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

// Update the GroundOverlay with a new image of the same dimensions.
imageOverlay = map.setImage(BitmapDescriptorFactory.fromResource(R.drawable.newark_nj_1975));

Bei der Methode setImage() wird das vorhandene Bild durch ein anderes Bild derselben Größe ersetzt.

Boden-Overlay positionieren

Es gibt zwei Möglichkeiten, um Boden-Overlays zu positionieren.

  • Du kannst LatLng verwenden, um das Overlay zu zentrieren, und Abmessungen in Metern anführen, um die Bildgröße anzugeben.
  • Verwende LatLngBounds, um die Nordost- und Südwestecke des Bilds anzugeben.

Du musst die Position des Boden-Overlays angeben, bevor du es der Karte hinzufügst.

Bild mithilfe eines Standorts positionieren

Beim Hinzufügen des Bilds gibst du einen LatLng-Wert zum Fixieren des Ankers sowie die Breite des Overlays in Metern an. Die Position anchor befindet sich standardmäßig in der Mitte des Bilds. Optional kannst du die Höhe des Overlays (in Metern) angeben. Wenn du die Höhe des Overlays nicht angibst, wird sie automatisch unter Beibehaltung des Seitenverhältnisses des Bilds berechnet.

Durch den unten stehenden Code wird an der Position 40.714086, -74.228697 ein Bild platziert, das 8,6 km breit und 6,5 km hoch ist. Das Bild wird unten links verankert.

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

Bild mit "LatLngBounds" positionieren

Du stellst ein LatLngBounds bereit, das das Bild enthält. Über LatLngBounds werden die Nordost- und die Südwestecke des Bilds festgelegt. Beim Zeichnen des Bilds auf der Karte wird es so gedreht, dass es in die Begrenzungen passt. Wenn die Begrenzungen nicht dem ursprünglichen Seitenverhältnis entsprechen, wird das Bild verzerrt dargestellt.

Durch den unten stehenden Code wird auf der Karte ein Bild platziert, dessen Südwest- und Nordostecke sich bei 40.712216,-74.22655 bzw. 40.773941, -74.12544 befinden.

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

Daten mit einem Boden-Overlay verknüpfen

Du kannst GroundOverlay.setTag() aufrufen, um ein beliebiges Datenobjekt mit einem Boden-Overlay zu speichern, und das Datenobjekt mit GroundOverlay.getTag() abrufen.

Im folgenden Codebeispiel wird eine Stringbeschreibung mit einem Boden-Overlay gespeichert:

private GoogleMap mMap;
private GroundOverlay mSydneyGroundOverlay;

mSydneyGroundOverlay = mMap.addGroundOverlay(new GroundOverlayOptions()
    .image(BitmapDescriptorFactory.fromResource(R.drawable.harbour_bridge))
    .position(new LatLng(-33.873, 151.206))
    .clickable(true));

mSydneyGroundOverlay.setTag("Sydney");

Nachfolgend sind einige Beispiele für Szenarien aufgeführt, in denen es nützlich ist, Daten mit Boden-Overlays zu speichern und abzurufen:

  • Deine App deckt möglicherweise verschiedene Boden-Overlays ab, die unterschiedlich behandelt werden sollen, wenn der Nutzer darauf klickt.
  • Du verfügst möglicherweise über eine Schnittstelle mit einem System, in dem es eindeutige Datensatzbezeichner gibt, wobei die Overlays spezifische Datensätze in diesem System darstellen.
  • Mithilfe von Overlay-Daten kann eine Priorität angegeben werden, um den Z-Index für das Overlay zu ermitteln.

Boden-Overlay-Ereignisse verarbeiten

Boden-Overlays sind standardmäßig nicht anklickbar. Das kann durch Aufrufen von GroundOverlay.setClickable(boolean) aktiviert oder deaktiviert werden.

Mithilfe von OnGroundOverlayClickListener kannst du Klickereignisse auf ein anklickbares Boden-Overlay erfassen. Rufe GoogleMap.setOnGroundOverlayClickListener(OnGroundOverlayClickListener) auf, um diesen Listener auf der Karte festzulegen. Wenn ein Nutzer auf ein Boden-Overlay klickt, erhältst du ein onGroundOverlayClick(GroundOverlay)-Callback.