Animation & Image Overlays in Google Earth

Download the data for these exercises <GEarth>.

Part I – Creating Animated KML placemarks from text files using python


In our first tutorial with Google Earth, we looked at how to construct Google Earth objects using kml. In this tutorial, we assemble these basic concepts together to construct a simple Google Maps application. Our application will display the track of an imaginary sea turtle across the north Atlantic – first as a set of placemarks and then as animated map of turtle movements.

1. Turtle locations: “Zissou”

The data we’ll use for this exercise originate from Catherine McClellan’s (a Duke PhD!) work tracking sea turtles in 2006-07. These data in their original format can be found on the “Field Trip Earth” web site: (read the “Please Note” paragraph and click on the Research Data link for the actual data.

The particular turtle whose track we’ll be mapping is “Zissou” and the coordinates and dates are found in the Zissou.txt file found in the TurtleTutorial folder in the file on Blackboard. (Or you can download the data for Zissou or for another turtle – yourself).

2. Building KML placemarks from a text file

No doubt you could eventually come up with a python script to convert the text file to KML formatted placemarks yourselves, but I figured I’d save you some time and write one myself. The script is called and is found in the Turtle Tutorial folder on blackboard.

At some point, take a careful look at this python script. There are some techniques used here that we haven’t discussed, primarily the use of the triple single quotes (”’) to create a multi-line string, and the use of variable placeholders (%s, %d, and %2.4f) within strings.

The general approach of this script is to create a new KML text file, then first write all the standard KML header lines to this file, and then loop through each of the data lines in the Zissou text file and create formatted KML placemark line blocks for each of these turtle observation lines. Finally, the standard ending lines are written to the KML document and the document is closed and ready to be open in Google Earth.

There are two functions in the script: the first (“MakePlacemark”) creates a simple placemark from the line text passed to the function, and the second (“MakeTimePlacemark”) uses the date information to add a TimeStamp element to each placemark. This enables animation when viewing in Google Earth. (See the KML documentation for TimeStamp…)

Clearly this script can be modified a great deal, and you are encouraged to do so. It also demonstrates that constructing a KML file programmatically is not all that difficult to do, once you know the ins and outs of KML and its elements.

Try running the file as is, and then run it again, but switch the
line to use the MakeTimePlacemark function. What else might you add to make this a more elegant application? How might you approach figuring out how to do it?

Part II – Using imagery in GoogleEarth

KML files cannot contain image data. Instead they contain pointers to images in their native format. To avoid separating the KML file and it’s referred image, both are kept in a single KMZ file, which is simply a zip file archive containing both. Here we look at an example:

1. Images and KMZ files

  • Open the MODIS_chlorophyll.KMZ file (found in the GEarth folder) in Google Earth. You’ll see that the one KMZ file contained 3 elements: 2 static overlays (a logo and a legend), and a map of oceanic chlorophyll concentration
  • Now, back in windows explorer, right click the KMZ file and open it using 7Zip. You’ll see that this file is a zipped archive containing 4 files – three are images representing the logo, the legend, and the chlorophyll map, and the fourth is a KML file.
  • Inspection of the KML file shows that it contains links to the three images and information on how to display each.

So here we see that a KMZ file is a tidy way to package self contained Google Earth data and the instructions on how to georeference and display them…

2. Creating your own image overlays within Google Earth

So how do you create your own image overlay if all you have is an image and information on where this image is located? The easiest option is to add your image into GoogleEarth and set its location manually. You can save these settings as your own KMZ file. Let’s demonstrate this using some images for mountains in Nevada.

  • In GoogleEarth, select Image Overlay from the Add menu
  • Name the overlay: Carvers, Nevada DRG
  • Browse to the Carvers.tif file (In the OverlayKMLExamples folder)
  • Set its location variables to:
    • North:             38.875
    • South:             38.750
    • East:              117.125
    • West:             117.250
  • Set the transparency to somewhere in the middle of the slider bar and close the properties.
  • Right click and save the image as its own KMZ file.


3. Creating an image overlay programmatically

Say, however, that you wanted to create the image overlay outside of Google Earth, perhaps writing a Python script to do it programmatically using user input variables. To do that we have to create/edit our KML document so that it reflects the correct image linkage and coordinates. Here we’ll simply edit an existing image KML so that it points to a different image for a different location.

  • In the same directory as the CarversNW.tif file, create and open a new text file. Name it kml.
  • In Google Earth, right click the Carvers, Nevada DRG layer (created above) and select copy. This copies the layer’s KML text to the clipboard.
  • Paste the KML into the newly created text document.
  • Now update the contents of the KML file to reflect the Carvers NW tiff coordinates:
    • North:       39.000
    • South:       38.875
    • East:        -117.125
    • West:      -117.250
  • Also update the image file it references to the Carvers NW tiff file (line 7) and the name attribute (line 4).
  • Save the edited KML file and open it in Google Earth. Voila!

 4. Using a hosted image

There may be reasons that you’d rather point to an image file that already resides on a web site rather than download it and distribute it with your KML/KMZ file. If that’s the case, we simply have to edit the hyper link reference in our KML file from a local directory to the URL where the image is hosted. We’ll look at an example of this by modifying the CarverNW.kml file to point to another image that’s on-line.

  • Copy the CarverNW.kml as a new file named ArcDome.kml
  • Change the hyperlink reference (href) to:
  • Change the image corners to
    • North:       38.875
    • South:       38.750
    • East:     -117.250
    • West:    -117.375

The result is a KML file that points to an image stored on-line, with the KML having the information needed to display the image in a georeferenced fashion.

5. Using a hosted image – a marine example

  • A quick Google image search on “sea surface temperature” yields a bunch of images of several different extents, shapes, and coordinate systems.
  • Find one that appears to be Unprojected and that extends no further than pole to pole and has no extra space on the east or west border. This one will work:
    (It’s replicated at in case the link breaks)
  • In Google Earth, select “AddàImage Overlay”
  • Name the file something relevant: e.g. “Sea Surface Temperature”
  • Set the link to the URL of the image (above)
  • In the location tab, you have to essentially guess where the image lines up.
    • North and south are easy: enter 90° and -90°, respectively.
    • For east, the image edges appear right around the prime meridian, so you could try putting in 0° for the east coordinate and 360° for the west, but you’ll see these values only allow you to put in values <= 180°.
    • So you’ll have to align the image manually, which is done by clicking and dragging the image “handles” which appear when the image properties are open.
    • Once you have the image aligned, you may see that the coordinates listed in the image properties are still limited to values <= 180°. However, if you close the properties and save the image to a kml/kmz file, and look at the kml, you’ll see that the coordinates of the ground overlay are correct. And when the kml is opened again, the image appears georeferenced correctly.

An easier example is the image hosted at: since this image is centered at 0°, 0° and its corners are at 90°, 180° and -90°, -180°. For this you don’t have to manually adjust the images, you just have to enter in the coordinate locations and your data should appear on Google Maps without issue. (The image is mirrored at ).

The lesson here is that you can project nearly any map onto the Google Earth surface without too much trouble. Furthermore, since maps can be hyper links, the images themselves can be updated – much like a typical web service. To see some examples, check some “real time links: