Click here to see your recently viewed pages and most viewed pages.
Hide
Google Maps Android API

Ground Overlays

Ground overlays are image overlays that are tied to latitude/longitude coordinates, so they move when you drag or zoom the map.

Introduction

A ground overlay is an image that is fixed to a map. Unlike markers, ground overlays are oriented against the Earth's surface rather than the screen, so rotating, tilting or zooming the map will change the orientation of the image. Ground overlays are useful when you wish to fix a single image at one area on the map. If you want to add extensive imagery that covers a large portion of the map, you should consider a Tile overlay.

To add a GroundOverlay, create a GroundOverlayOptions object that defines both an image and a position. You can optionally specify additional settings that will affect the positioning of the image on the map. Once you've defined the necessary options, pass the object to the GoogleMap.addGroundOverlay() method to add the image to the map. The addGroundOverlay() method returns a GroundOverlay object; you should retain a reference to this object if you want to modify it later.

Add an overlay

  1. Instantiate a new GroundOverlayOptions object
  2. Specify the image as a BitmapDescriptor.
  3. Set the position of the image using one of the available methods:
    • position(LatLng location, float width, float height)
    • position(LatLng location, float width)
    • positionFromBounds(LatLngBounds bounds)
  4. Set any optional properties, such as transparency, as desired.
  5. Call GoogleMap.addGroundOverlay() to add the image to the map.

The below example demonstrates how to add a ground overlay to an existing GoogleMap object.

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

If you wish to change or remove a ground overlay after you've added it to the map, ensure that you keep hold of the GroundOverlay object. You can modify the overlay later by making changes to this object.

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

Remove an overlay

You can remove a ground overlay with the GroundOverlay.remove() method.

imageOverlay.remove();

Change an overlay

You can change the ground overlay image after it's been added to the map with the GroundOverlay.setImage(BitmapDescriptor) method.

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

The setImage() method will replace the existing image with another image of the same dimensions.

Position a Ground Overlay

There are two ways to specify the position of the ground overlay:

  • Using a LatLng to center the overlay, and dimensions in meters to specify the size of the image.
  • Using a LatLngBounds to specify the north east and south west corners of the image.

You must specify the position of the ground overlay before it is added to the map.

Use location to position an image

When you add the image you specify a LatLng to which the anchor will be fixed and the width of the overlay (in meters). The anchor defaults to the center of the image. You can optionally provide the height of the overlay (in meters). If you do not provide the height of the overlay, it will be automatically calculated to preserve the proportions of the image.

The below code places an image at position 40.714086, -74.228697 that is 8.6km wide by 6.5km high. The image is anchored at the bottom left.

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

Use LatLngBounds to position an image

You provide a LatLngBounds which contains the image. The LatLngBounds sets the north east, and south west corners of the image. When the image is drawn on the map it will be rotated to fit the bounds. If the bounds do not match the original aspect ratio, the image will be skewed.

The below code places an image on the map with its South West corner bound to 40.712216,-74.22655 and its North East corner bound to 40.773941, -74.12544.

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