In this post I will continue my discussion of overlays in the MapQuest JavaScript API 5.2. My last two posts covered a couple of methods for adding rollover functionality to overlays. Over the next couple of posts I will discuss some of the options that are available when working with image overlays.

There are a few things that set image overlays apart from the other overlay types. The one that poses the biggest obstacle is image resolution. Since an image overlay is "pinned" to a map with Lat and Lng coordinates, there is a significant difference in resolution required to display an image properly at different zoom levels. If this becomes an issue for your application, one of the options that is available is the setImageOverlayLevels method provided by the API.

The setImageOverlayLevels() method takes an array of MQImageOverlayLevel objects as an argument. You create an MQImageOverlayLevel object by passing a string representing the URL of the image and an integer between 1 and 16 representing the zoom level the image should be tied to. Although you can specify 16 different images, you don't need to, as the nearest image to the current zoom level will always be displayed. I have included a function here that I created as an example. The function can be used in your code to implement the use of MQImageOverlayLevel's in your application.

Listing 1: The addImageUrls() function

  function addImageUrls(MAX_ZOOM, MIN_ZOOM, imageOverlay){   // Lowest resolution to highest.
    if(arguments.length > (SPAN+3)){
      arguments.length = SPAN+3;  // Ensure a maximum of 1 image per zoom level.
    var incrementor = MIN_ZOOM;
    var incrementSize = Math.round(SPAN / (arguments.length - 3));
    var levels = new Array();
    var addImageLevel = function(url,lvl){
      var newLevel = new MQImageOverlayLevel(url,lvl);
      newLevel ? levels.push(newLevel) : alert('Error: Level ' +
        lvl + ' image initialization has failed.'); // No real error checking implemented here.
    // In a production environment, something more
    // thorough would become necessary.
    for(var i=3;i<arguments.length;i++){
      if(incrementor > MAX_ZOOM){
        incrementor = MAX_ZOOM;
      addImageLevel(arguments[i], incrementor);
      incrementor = incrementor+incrementSize;

The function is called with the following arguments:

Listing 2: Calling the addImageUrls() function

	addImageUrls(MAX_ZOOM, MIN_ZOOM, imageOverlay,
	/* and up to 16 string URLís */)

The values for max and min zoom are used to determine which zoom level to place each image at, as well as to determine when the image won't be displayed at all (because of the incredible difference between zoom level 16 and zoom level 1, there is a good chance that the image overlay will only be applicable for a certain range of values). Next you pass your MQImageOverlay object, followed by a series of strings containing the URL's of the images. You can pass in anywhere from 2 to 16 values, ordered from lowest resolution to highest.

To close, I've included two screenshots that show MQImageOverlayLevels in a sample application. Other than setting up the map and collecting the shape points, all of the code is contained within the sample function in Listing 1. For simplicity sake, I created two square images of separate colors. When the map is zoomed in beyond the half-way point, the brown image is displayed. When it is zoomed out, a blue image is displayed.

Image 1: The Image, Zoomed In

Image 2: The Image, Zoomed Out