Add an image layer to a map

This article shows you how you can overlay an image to a fixed set of coordinates on the map. Here are few examples of the type of images often overlaid on maps:

  • Images captured from drones
  • Building floorplans
  • Historical or other specialized map images
  • Blueprints of job sites
  • Weather radar images


An ImageLayer is an easy way to overlay an image on a map. Note that browsers might have difficulty loading a large image. In this case, consider breaking your image up into tiles, and loading them into the map as a TileLayer.

The image layer supports the following image formats:

  • JPEG
  • PNG
  • BMP
  • GIF (no animations)

Add an image layer

The following code overlays an image of a map of Newark, New Jersey, from 1922 on the map. An ImageLayer is created by passing a URL to an image, and coordinates for the four corners in the format [Top Left Corner, Top Right Corner, Bottom Right Corner, Bottom Left Corner].

//Create an image layer and add it to the map.
map.layers.add(new atlas.layer.ImageLayer({
    url: 'newark_nj_1922.jpg',
    coordinates: [
        [-74.22655, 40.773941], //Top Left Corner
        [-74.12544, 40.773941], //Top Right Corner
        [-74.12544, 40.712216], //Bottom Right Corner
        [-74.22655, 40.712216]  //Bottom Left Corner

Here's the complete running code sample of the preceding code.

Import a KML ground overlay

This next sample shows how to overlay KML ground overlay information as an image layer on the map. KML ground overlays provide north, south, east, and west coordinates, and a counter-clockwise rotation, whereas the image layer expects coordinates for each corner of the image. The KML ground overlay in this sample is of the Chartres cathedral, and is sourced from Wikimedia.

The following code uses the static getCoordinatesFromEdges function of the ImageLayer class. It calculates the four corners of the image from the north, south, east, and west, and rotation information from the KML ground overlay.

Customize an image layer

The image layer has many styling options. Here's a tool to try them out.

Next steps

Learn more about the classes and methods used in this article:

See the following articles for more code samples to add to your maps: