Introduction to GDAL

Overview

This tutorial covers basic usage of the command line utilities available through the GDAL software package. Since descriptions of the utilities themselves are available on the GDAL website, the focus here will be on providing examples.

What is GDAL?

GDAL stands for the Geospatial Data Abstraction Library. As a software library, it is widely used by developers seeking to incorporate various raster format compatibility in their software. If none of that makes any sense you're still ok, this tutorial covers the other use for GDAL: using its command line utilities to manipulate raster and vector files.

More on Rasters

Download and Installation

Windows

  • Download FWTools
  • Open the executable file
  • Follow the onscreen instructions to install

Linux

In Linux you have the choice between using FWTools or a standalone installation of GDAL. INSTALL_DIRECTORY refers to path to the location you would like to install to. Note that the standalone default installation of GDAL may not have the python utilities.

FWTools

  • Download FWTools
  • Open a terminal and navigate to the location of the file on your system
Execute the Following
gunzip FWTools-linux-2.0.6.tar.gz
tar xvf FWTools-linux-2.0.6.tar
./configure --prefix=INSTALL_DIRECTORY
make
make install

You may omit --prefix=INSTALL_DIRECTORY in which case it is installed at the default location (requires root access).
If you do not install to the default location you will need to add FWTools to you path before you can run the utilities:

Add FWTools to Your Path
export PATH=INSTALL_DIRECTORY/FWTools-2.0.6/bin_safe:$PATH

GDAL Standalone (Build from Source)

  • Download GDAL1.9.1
  • Open a terminal and navigate to the location of the file on your system
Execute the Following
gunzip gdal-1.9.1.tar.gz
tar xvf gdal-1.9.1.tar
./configure --prefix=INSTALL_DIRECTORY
make
make install

You may omit --prefix=INSTALL_DIRECTORY in which case it is installed at the default location (requires root access).
If you do not install to the default location you will need to add GDAL to you path before you can run programs:

Add GDAL to Your Path
export PATH=INSTALL_DIRECTORY/GDAL1.9.1/bin:$PATH

GDAL Standalone (Package Manager)

Certain versions of Linux, such as Ubuntu, come with a package manager that can be used to obtain gdal easily and quickly with little to no effort on your part. You will however need root access, or kindly ask your IT manager to install it for you.

First open a terminal, then:

Ubuntu
sudo apt-get install gdal-bin
sudo apt-get install python-gdal
Fedora
sudo yum install gdal
sudo yum install gdal-python

GDAL is a set of command line utilities, so you need a shell to run them. In windows, FWTools sets up a shell from which you can execute all of the utilities. Linux should come with a shell, generally referred to as the terminal.

Navigation in a Shell

When specifying input and output files, the utility needs to know where the file is located on the filesystem. For this you have two options: either manually type out the full absolute path to each and every file you work with, or navigate to the folder containing your working files so you only need to type filenames.

Viewing the Contents of the Current Directory

You can see what folders and files are available in your current directory using the 'dir' (or 'ls' in linux, though dir may still work).

Changing Directories

You can change to a different directory by specifying the full path to the directory you wish to navigate to.

Alternatively, if the directory you wish to navigate to is a subdirectory of your current directory, you can type in the difference between the two paths.

Finally, you can use ../ to move backwards through the directory structure. This may be combined with the partial path to another directory as well.

Note that if the path contains spaces, you must enter the path in double-quotes, or on Linux you can use a \ as seen in the picture above.

Example Files

Several image files will be used throughout these examples, you can get them here:

t1.09155.AV_MI.143.250m.tif
ne_small.tif
nw_small.tif
se_small.tif
sw_small.tif
mosaic.tif

Retrieving Information from an Image File

Raster Info

One of the easiest and most useful commands in GDAL is gdalinfo. When given an image as an argument, it retrieves and prints all relevant information that is known about the file. This is especially useful if the image contains additional tag data, as is the case with TIF files. When working with satellite imagery, this is an extremely useful way of keeping track of the images location in long./lat. coordinates as well as the image projection.

gdalinfo
gdalinfo RasterFile

Sample TIF information

Sample JPEG information

Vector Info

Sometimes similar information is needed from a vector image, for this there is ogrinfo. For example, if you are trying to group a lot of images together, you might use a shapefile (see Indexing Images).

gdalinfo
ogrinfo -al VectorFile

Sample Shapefile information

Change Image Properties

The gdal_translate command gives us several options to modify raster images:

Resize an Image

gdal_translate can be used simply to change the size of an image using the -outsize parameter, which takes two integer values as the xsize and ysize respectively, or two percentage values to scale the image.

Resize
gdal_translate -outsize newxsize newysize imageFile outputFile

Sample resized TIF

Change Image Format

gdal_translate's primary function is to change between image formats. Resizing and changing the image format can also be combined into one step by using both the -outsize and -of parameters.

Format Change
gdal_translate -of FORMAT imageFile outputFile

Sample Images After Conversion from TIF

JPEG PNG

Notice the blocky artifacts near the Eastern tip of the Upper Peninsula. See the section on Data Loss

Add Overviews

Overviews are essentially copies of an image at a lower resolution. The idea is that if the whole image is viewed, the overview of smallest resolution is shown to minimize performance overhead. As a smaller subsection of the image is zoomed in on, the higher resolution overviews are used until finally the actual image is displayed. Adding or removing images can be done with gdaladdo:

gdaladdo
gdaladdo -r METHOD INPUT OUTPUT RESOLUTIONS

The list of methods can be found here, common resolutions are 2 4 8 16, meaning an overview at 1/2, 1/4, 1/8, and 1/16 resolution are created.

Warping Coordinate Systems

GDAL has the capability to change an images coordinate system. This is most easily done with a TIF file since the source image likely contains all of the relevant geographic data. The -t_srs parameter specifies the target coordinate system, If the source coordinate system is unknown it must be specified with the -s_srs parameter.

Warping TIF files

gdalwarp
gdalwarp -t_srs ESPG:... INPUT OUTPUT

You should get something like this:

Indexing Images

If you have many small images and you want to use them together as a group, you might want to create an index that contains the boundries and locations of the images. For this you can use gdaltindex, which will automatically generate a shapefile from the images you supply it. Using TIF images is again the easiest. If a shapefile doesn't already exist, GDAL will give an error, you can safely ignore it since it's just warning you that it will instead have to make one.

To try this yourself, download the four _small.tif files and put them into a directory apart from other TIF images. Placing these in their own directory isn't a must, but it makes it convenient since you can use the *.tif parameter and GDAL will automatically grab all four files without risk of including anything that doesn't belong. You could also use *_small.tif, or list each file separately. (the * simply means match any string, so *.tif means grab all files that end with .tif, while *_small.tif would be any file ending in _small.tif)

gdaltindex
gdaltindex -tileindex location OUTPUT *.EXTENSION

Creating Mosaics

Similar to the Indexing function is gdal_merge.py which creates an image mosaic. The difference here is that the images are actually combined into one, instead of having a shapefile that describes how they fit together. This utility has no problem dealing with images that overlap, but the last image specified is what is shown on top.

The setup here is the same as the example on indexing.

gdal_merge.py
gdal_merge.py -o OUTPUT *.EXTENSION

You should get an image like this:

Which in case you're wondering, is an image of Houghton, MI.

Converting Between RGB and Palleted Rasters

Converting to Palleted

Converting between 8-bit palleted images and True Color RGB images is rather straightforward with rgb2pct.py:

rgb2pct.py
rgb2pct.py -of FORMAT INPUT OUTPUT

The default format for this function is TIF, so we don't need to supply the -of parameter.

At first the output image will appear to be identical to the original, it isn't until you zoom in that the differences become clear. The palleted image is on the left, the original on the right.

Converting to RGB

Conversion to RGB can be accomplished through the use of either pct2rgb.py, which has the same syntax as rgb2pct.py, or by using -expand parameter with gdal_translate:

Pallete to RGB
gdal_translate -expand 'rgb'/'rgba' -of FORMAT INPUT OUTPUT

Burning Vector images onto Raster Images

gdal_rasterize is good for using vector images to highlight areas on a raster image. The GDAL Stub on this utility gives the example of highlighting certain types of buildings using elevation data. You could also use it to draw roads or place symbols over important buildings or locations.

For this example, we will be using mosaic.tif and ne_small.tif to highlight the upper right region of the mosaic.

gdal_rasterize
gdal_rasterize -b BAND -burn INTENSITY -l VECTOR_LAYER INPUT OUTPUT

Using gdaltindex we create a shapefile using only the upper right image from the mosaic. gdal_rasterize then burns the shapefile onto the mosaic image. The -b parameter specifies which color bands will be burned to, multiple -b parameters can be used to specify multiple color bands. The -l parameter is the layer we are using as a source from the vector image. You can use ogrinfo (Vector Info) to see what layers are available in a vector image. Note that this Utility modifies the source image and does not produce a copy, if you want your original file intact, be sure to copy it beforehand.

External Links


All text on the MichiganView website is released under a Creative Commons Attribution 3.0 License.