Custom Raster Tiles

Dividing a Map and Tile Lookup

Once a tile source has been implemented you can toggle its display by adding or removing it to the map using Map.addRasterTileSource(MapRasterTileSource) or Map.removeRasterTileSource(MapRasterTileSource).

The MapRasterTileSource Abstract Class

MapRasterTileSource is the common way for you to define your raster tile source. If your application uses local tile images or remote images that require custom server authentication, then you should implement this class by defining hasTile() and getTileWithError() methods. For example:

public class MyTileSource extends MapRasterTileSource {

  @Override
  public boolean hasTile(int x, int y, int zoomLevel) {
    return true;
  }

  @Override
  public TileResult getTileWithError(int x, int y, int zoomLevel) {
    byte[] myImageData = null;
    // perform tile retrieval logic such as server authentication
    // also translate the x, y, and zoomlevel to address an image

    TileResult result = new TileResult(Error.NONE, myImageData);
    return result;
  }
}

The UrlMapRasterTileSourceBase Abstract Class

UrlMapRasterTileSourceBase is a child abstract class of MapRasterTileSource that you can use if you plan to fetch tile images from a remote server using image URLs. The following is a sample implementation of UrlMapRasterTileSourceBase. In this example, we use the MapRasterTileSource.MapTileSystemHelper.tileXYToQuadKey() method to address our map tiles. This helper method assumes that we are using a quadtree/quadkey scheme where the map is divided into a quadtree (a tree data structure where each node has exactly four children) with 20 levels. Each level of this map quadtree has (2 ^x )² tiles where x represents the floor function value of the current zoom level. So for level 0 there is 1 x 1 = 1 tile, level 1 has 2 x 2 = 4 tiles, level 2 has 4 x 4 = 16 tiles, and level 3.7 has 8 x 8 = 64 tiles—since the floor value of 3.7 is 3.

For more information about the quadkey/quadtree division scheme see the tileXYToQuadKey() API reference.

public class LiveMapRasterTileSource extends UrlMapRasterTileSourceBase {

  private final static String URL_FORMAT =
      "http://1.communitymaptiles.example.org/tilehub/live/map/png/%s";

  public LiveMapRasterTileSource() {
    // We want the tiles placed over everything else
    setOverlayType(MapOverlayType.FOREGROUND_OVERLAY);
    // We don't want the map visible beneath the tiles
    setTransparency(Transparency.OFF);
    // We don't want the tiles visible between these zoom levels
    hideAtZoomRange(12, 20);
    // Do not cache tiles
    setCachingEnabled(false);
  }

  // Implementation of UrlMapRasterTileSourceBase
  public String getUrl(int x, int y, int zoomLevel) {
    String url = null;

    // Utility to map the x, y coordinates easily into an equivalent
    // quadkey at a specified zoomLevel
    String quadKey =
        MapTileSystemHelper.tileXYToQuadKey(x, y, zoomLevel);

    try {
      // Append the quadkey to the URL template to get a real URL
      url = String.format(URL_FORMAT, quadKey);
    } catch (Exception ex) {
      ex.printStackTrace();
    }

    return url;
  }
}

The example above generates a quadkey from the x, y coordinates and the zoom level and appends it to the URL. However, this is server-specific and the method of converting x, y and zoom level to a URL can be done in many ways. Also, it is worth noting that tiles can be cached with setCachingEnabled(true).

Changing the Overlay Rendering Order

You can choose to customize the order raster tiles are rendered in by calling MapRasterTileSource.setOverlayType(MapOverlayType). For example, MapOverlayType.BACKGROUND_OVERLAY and MapOverlayType.BACKGROUND_REPLACEMENT are similar to rendering raster tiles with streets rendered on top. MapOverlayType.FOREGROUND_OVERLAY renders tiles on top of everything on the map.

Caching Tiles

Tiles can be cached to the disk by calling the following:

// Give the tile source a custom prefix so it can be cached on the disk
MapRasterTileSource.setCachePrefix(String cache)

// Give each raster tile file an expiration time in seconds
MapRasterTileSource.setCacheExpiration( int seconds )

If no expiration time is set, then the raster tiles remain on the device. We recommend that both a cache prefix and an expiration time be set.