Keyhole Markup Language

Creating super-overlays with gdal2tiles

Mano Marks, Google Geo APIs Team
September 2009

Objective

This tutorial walks you through the basics of creating a super-overlay, a set of ground overlays that use region-based NetworkLinks, using the open source Geospatial Data Abstraction Library utilities.

Introduction

Geobrowsers like Google Earth and Google Maps provide you with satellite imagery and map tiles. However, sometimes you may want to use your own. Imagery, or raster data comes in many forms and has many uses.

  • Placing your own satellite or aerial imagery into a geobrowser
  • Placing historical maps on top of existing imagery, such as the Rumsey Maps layer in Google Earth
  • Importing GIS data in raster form
  • Placing LIDAR or infrared imagery in the geobrowser

One of the problems with high-resolution raster data, though, is that it takes a lot of memory to display it. And if you're pushing it out over the net, you have bandwidth concerns as well. To address that problem, you have to create tiles.

Tiling breaks your image file into many different images that load when they come into view. You create one low resolution image for display while the user is zoomed way out. Over the same area, you create four higher resolution images for closer in viewing. For each area overlayed by an image, you create four more higher resolution images for closer in zooming, etc. This is known as the quadtree method, and is how imagery is tiled for Google Earth and Google Maps. The process is explained in more detail in the KML Developer Guide article on Regions.

It is possible to do this manually with a graphics editing application like Adobe's PhotoShop or GIMP, but this can be complex, tedious, and is errors-prone. There are also a number of good applications available, primarily for Windows, such as SuperOverlay, Arc2Earth, and MapCruncher combined with CrunchUp2KML.

If you want to automate the process, or add functionality to your own application, GDAL, provides you with a rich set of tools for working with raster and vector data. This article covers the command line options. However, the libraries can also be easily incorporated into your own applications. For this tutorial, you're going to use the gdalinfo, gdal_translate, gdalwarp, and gdal2tiles utilities. The ultimate output is a super-overlay.

Command Line Steps

There are six steps to using GDAL at the command line.

  1. Download and install GDAL
  2. Download an image
  3. Use gdalinfo to determine information about the image
  4. Use gdal_translate to georeference the image
  5. Use gdalwarp to change the projection of the image
  6. Use gdal2tiles to break the image into tiles and create the associated KML code

Step 1: Download and install GDAL

Begin by downloading and installing the GDAL as detailed here.

Step 2: Download an image

You can use any image. There are a number of sources of geographic data on the web. You can use any of them, but you should know the boundaries of the image—the latitude and longitude of each of the corners of the image. This tutorial uses a NASA Blue Marble image, available for download from NASA's website. These images were taken in 2004 and present a beautiful image of the Earth from space. Choose one of the files in the lower right of the right navigation bar.

If you're using your own image and know that it is already georectified, then you can skip to Step 5. Otherwise, proceed with Step 3.

Step 3: Get information about the image

Once you've installed the GDAL libraries and selected the image, you need to get some information about the image so that you can georeference it. Specifically, you need the pixel and line positions of each corner of the image. If you imagine the image as a table, with columns and rows, the pixels are the columns, and the lines are rows.

GDAL provides a handy utility, gdalinfo, for capturing this information. At the command line, simply type gdalinfo filename, replacing filename with the path to the file. You should get output that looks like this:

Driver: JPEG/JPEG JFIF
Files: world_200401.jpg
Size is 21600, 10800
Coordinate System is `'
Image Structure Metadata:
  SOURCE_COLOR_SPACE=YCbCr
  INTERLEAVE=PIXEL
  COMPRESSION=JPEG
Corner Coordinates:
Upper Left  (    0.0,    0.0)
Lower Left  (    0.0,10800.0)
Upper Right (21600.0,    0.0)
Lower Right (21600.0,10800.0)
Center      (10800.0, 5400.0)
Band 1 Block=21600x1 Type=Byte, ColorInterp=Red
  Image Structure Metadata:
    COMPRESSION=JPEG
Band 2 Block=21600x1 Type=Byte, ColorInterp=Green
  Image Structure Metadata:
    COMPRESSION=JPEG
Band 3 Block=21600x1 Type=Byte, ColorInterp=Blue
  Image Structure Metadata:
    COMPRESSION=JPEG

The important information for this tutorial is the Upper Left, Lower Left, Upper Right, Lower Right lines. These tell you the pixel and line values of each corner. The Upper Left, in this case, is at 0,0, and the Lower Right is at 21600,10800.

Step 4: Georeference the Image

Georeferencing in this case means to create metadata describing the geographic position of each of the corners of the image. Using the information gained in Step 3 and gdal_translate, you can assign georeference information to the file. This creates a VRT file from world_200401.jpg image, bluemarble1.vrt. VRT files are XML files that contain the information about a particular transformation, in this case the gdal_translate step. You will use it again in the next step to create your final set of tiles. gdal_translate allows you to do multiple file output types including major image file formats. Using VRT outputs allows you to essentially put off making output files until the last step. This increases efficiency and decreases your wait time for individual steps if you're doing the command line. Here's the command you would run:

gdal_translate -of VRT -a_srs EPSG:4326 -gcp 0 0 -180 90 -gcp 21600 0 180 90 -gcp 21600 10800 180 -90 world_200401.jpg bluemarble1.vrt

There's a lot of information on that line, so here it is broken out:

  • -of is output format, in this case VRT.
  • -a_srs assigns a spatial reference system to the file. That tells any application consuming it what coordinate system is being used. In this case, it is using EPSG:4326, which is the same as WGS84, the coordinate system used by Google Earth.
  • -gcp, or ground control point, assigns coordinates to positions in the file. In this case, you actually only need three points, since the image is a rectangle and therefore the fourth point can be easily identified. For -gcp, define the gcp by setting the pixel and then line number, and then the longitude and latitude. Each of those is separated by a space.
  • The last two parameters are the origin file and the target file.

Step 5: Warp the Image

The original image wasn't created for a round globe, it was created to appear to lie flat. In GIS terms, it is projected, which means that it is a two-dimensional representation of a three-dimensional object. Projection requires distorting the image so that it appears how you would expect a flat image of the Earth to look.

In order to get it to look right, you have to warp the image it to fit the globe. Fortunately GDAL provides a great tool for that too. Simply type gdalwarp -of VRT -t_srs EPSG:4326 bluemarble1.vrt bluemarble2.vrt. This will create a new file, bluemarble2.vrt, which provides metadata about the warping procedure.

Step 6: Create the Tiles

You're almost done, but this part will take the longest. To create the tiles, type in gdal2tiles.py -p geodetic -k bluemarble2.vrt. The -k forces a KML output. This will create a directory structure with a super-overlay. As each of those image files has to be created separately, it takes awhile to run. For large images, you can now go, get a cup of coffee, take a nap, maybe get a light meal. When you're done, open up doc.kml and observe the results!

Conclusion

This tutorial just scratches the surface of what GDAL can do, but it does provide a convenient mechanism for generating tiles. The core GDAL libraries are written in C++, but they provide bindings for Perl, Python, VB6, R, Ruby, Java, and C#/.NET, meaning you can easily incorporate GDAL into your own applications. Also, many of the utilities, including gdal2tiles, are written in Python, making them easy to incorporate into Python applications. gdal2tiles also has the ability to generate Google Maps API and OpenLayers pages.

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.