Stay organized with collections
Save and categorize content based on your preferences.
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
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.
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:
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.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2023-11-03 UTC."],[[["\u003cp\u003eThis tutorial explains how to create a super-overlay, a set of ground overlays using region-based NetworkLinks, with the open source Geospatial Data Abstraction Library (GDAL) utilities.\u003c/p\u003e\n"],["\u003cp\u003eHigh-resolution raster data can be displayed efficiently using tiling, which breaks the image into smaller images that load as needed, similar to Google Earth and Maps.\u003c/p\u003e\n"],["\u003cp\u003eGDAL provides command-line tools to georeference, warp, and tile images, automating the process of creating super-overlays for use in geobrowsers.\u003c/p\u003e\n"],["\u003cp\u003eThe tutorial outlines six steps: installing GDAL, downloading an image, getting image information, georeferencing, warping, and creating tiles using specific GDAL commands.\u003c/p\u003e\n"],["\u003cp\u003eGDAL offers extensive functionality beyond this tutorial, including language bindings and the ability to generate Google Maps API and OpenLayers pages.\u003c/p\u003e\n"]]],[],null,["*Mano Marks, Google Geo APIs Team\nSeptember 2009*\n\nObjective\n\n\nThis tutorial walks you through the basics of creating a [super-overlay](/kml/documentation/regions#superoverlays), a set of ground overlays that use region-based NetworkLinks, using the open source [Geospatial Data Abstraction Library](http://gdal.org) utilities.\n\nIntroduction\n\n\nGeobrowsers 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](http://en.wikipedia.org/wiki/Raster_graphics) comes in many forms and has many uses.\n\n- Placing your own satellite or aerial imagery into a geobrowser\n- Placing historical maps on top of existing imagery, such as the [Rumsey Maps](http://www.davidrumsey.com/) layer in Google Earth\n- Importing [GIS](http://en.wikipedia.org/wiki/Geographic_information_system) data in raster form\n- Placing [LIDAR](http://en.wikipedia.org/wiki/LIDAR) or infrared imagery in the geobrowser\n\nOne 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.\n\nTiling 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](http://en.wikipedia.org/wiki/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](/kml/documentation/regions#superoverlays).\n\nIt 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](http://superoverlay.geoblogspot.com/), [Arc2Earth](http://www.arc2earth.com/), and [MapCruncher](http://research.microsoft.com/en-us/um/redmond/projects/mapcruncher/) combined with [CrunchUp2KML](http://rootcamp.net/crunchup2kml/).\n\n\nIf you want to automate the process, or add functionality to your own application, [GDAL](http://gdal.org), provides you with a rich set of tools for working with raster and [vector data](http://en.wikipedia.org/wiki/Vector_graphics). 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.\n\nCommand Line Steps\n\nThere are six steps to using GDAL at the command line.\n\n1. [Download and install GDAL](#install)\n2. [Download an image](#image)\n3. [Use `gdalinfo` to determine information about the image](#info)\n4. [Use `gdal_translate` to georeference the image](#translate)\n5. [Use `gdalwarp` to change the projection of the image](#warp)\n6. [Use `gdal2tiles` to break the image into tiles and create the associated KML code](#tile)\n\nStep 1: Download and install GDAL\n\n\nBegin by downloading and installing the GDAL as detailed [here](http://trac.osgeo.org/gdal/wiki/DownloadingGdalBinaries).\n\nStep 2: Download an image\n\nYou 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](http://www.gsfc.nasa.gov/blue_marble2/world_200401.jpg), available for download from [NASA's website](http://www.nasa.gov/vision/earth/features/blue_marble.html). 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.\n\nIf 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.\n\nStep 3: Get information about the image\n\nOnce 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.\n\nGDAL 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: \n\n```\nDriver: JPEG/JPEG JFIF\nFiles: world_200401.jpg\nSize is 21600, 10800\nCoordinate System is `'\nImage Structure Metadata:\n SOURCE_COLOR_SPACE=YCbCr\n INTERLEAVE=PIXEL\n COMPRESSION=JPEG\nCorner Coordinates:\nUpper Left ( 0.0, 0.0)\nLower Left ( 0.0,10800.0)\nUpper Right (21600.0, 0.0)\nLower Right (21600.0,10800.0)\nCenter (10800.0, 5400.0)\nBand 1 Block=21600x1 Type=Byte, ColorInterp=Red\n Image Structure Metadata:\n COMPRESSION=JPEG\nBand 2 Block=21600x1 Type=Byte, ColorInterp=Green\n Image Structure Metadata:\n COMPRESSION=JPEG\nBand 3 Block=21600x1 Type=Byte, ColorInterp=Blue\n Image Structure Metadata:\n COMPRESSION=JPEG\n```\n\nThe 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.\n\nStep 4: Georeference the Image\n\nGeoreferencing 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](http://www.gdal.org/gdal_vrttut.html) 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: \n\n 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\n\nThere's a lot of information on that line, so here it is broken out:\n\n- `-of` is output format, in this case VRT.\n- `-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.\n- `-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.\n- The last two parameters are the origin file and the target file.\n\nStep 5: Warp the Image\n\nThe original image wasn't created for a round globe, it was created to appear to lie flat. In GIS terms, it is [projected](http://en.wikipedia.org/wiki/Map_projection), 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.\n\nIn 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.\n\nStep 6: Create the Tiles\n\nYou'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!\n\nConclusion\n\nThis 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](/maps) and [OpenLayers](http://openlayers.org) pages."]]