help

The Geospatial Data Abstraction Library (GDAL/OGR) is an open-source, cross-platform set of libraries and low-level tools for working with spatial data in many formats. Although GDAL itself is geared towards raster data, it provides vector support via the OGR Simple Features Library. The term GDAL is often used to refer jointly to the full suite of GDAL and OGR functionality. GDAL/OGR plays a particular important role in the open-source geospatial software world as a file import/export/translation engine, as it can read (and often write) many spatial file formats. The associated command-line utilities can also be used to accomplish a variety of common tasks such as reprojecting, merging, and subsetting spatial data.

Installation guides

As of ‘’’'’Jun 2010’’’’’, the latest release is ‘’’'’GDAL/OGR 1.7.2’’’’’.

General

Binary installers for recent releases can be downloaded [http://trac.osgeo.org/gdal/wiki/DownloadingGdalBinaries here]. These are available for various flavors of Linux, OS X, and Windows. Windows and Linux users may find it useful to install the [http://fwtools.maptools.org/ FWTools kit], which includes the GDAL/OGR tools plus several other useful utility programs. Note that for the ‘‘most’’ recent version, it is often necessary to build from source.

Ubuntu

Although the official Ubuntu repositories provide gdal packages, more up-to-date versions can be obtained from the [http://trac.osgeo.org/ubuntugis/wiki/UbuntuGISRepository UbuntuGIS] repository. The ‘‘stable’’ incarnation of this repository is updated every 6 months, and the ‘‘unstable’’ repository is updated even more frequently. To enable the stable repository, add the following lines to your /etc/apt/sources.list file (substituting your Ubuntu version for ‘‘karmic’’ if appropriate):

deb http://ppa.launchpad.net/ubuntugis/ppa/ubuntu karmic main deb-src http://ppa.launchpad.net/ubuntugis/ppa/ubuntu karmic main

Then authenticate the repository and update your package list before installing gdal and proj as described above: sudo apt-key adv –keyserver keyserver.ubuntu.com –recv-keys 314DF160 sudo apt-get update

Finally, install ‘‘gdal-bin’’ to get the main utilities, and (if desired) ‘‘python-gdal’’ to get some additional command line tools. sudo apt-get install gdal-bin python-gdal

How can I…
See what formats are supported by my version of GDAL/OGR

ogrinfo –formats gdalinfo –formats

Obtain vector projection and other information

Get projection info and list of attribute columns # Shapefile ogrinfo -al -so ‘‘myshapefile.shp’’

# PostGIS table ogrinfo -al -so PG:dbname=’‘mydatabase’’ ‘‘mytable’’

# …or simply list the spatial layers in a PostGIS database ogrinfo -so PG:dbname=’‘mydatabase’’

Obtain raster projection and other information

Get projection info, bounding box coordinates, and other info gdalinfo ‘‘myraster’’

Reproject a vector

When using ‘‘ogr2ogr’’, remember that the output filename should come ‘’’'’before’’’’’ the input filename!

'’Option 1’’: Use the EPSG code (if known) to specify the projection ogr2ogr -t_srs EPSG:2784 ‘‘output_vector’’ ‘‘input_vector’’

'’Option 2’’: Use an appopriate projection file (e.g. the *.prj file associated with a shapefile) to specify the new projection ogr2ogr -t_srs ‘‘some_shapefile.prj’’ ‘‘output_vector’’ ‘‘input_vector’’

'’Option 3’’: Manually specify full Proj.4 definition string ogr2ogr -t_srs ‘+proj=tmerc +lat_0=21.16666666666667 +lon_0=-158 \ +k=0.999990 +x_0=500000 +y_0=0 +ellps=GRS80 +units=m +no_defs \ ‘‘output_vector’’ ‘‘input_vector’’

Reproject a raster

Because a square grid in one projection is not necessarily a square grid in another, reprojecting a raster layer often requires “warping”. Fortunately, this can usually be done quite easily using gdalwarp. As with other GDAL/OGR tools, the output projection can be specified using the EPSG code, an appropriate file, or the full Proj.4 definition string. Using EPSG code 2784 as an example, the general syntax is as below. In contrast to ‘‘ogr2ogr’’, the output filename should come ‘’’'’after’’’’’ the input filename gdalwarp -t_srs EPSG:2784 ‘‘input_raster’’ ‘‘output_raster’’

Align two rasters

Imagine you have two rasters, raster_A and raster_B, where raster_A falls entirely within the extent of raster_B, and is of finer resolution (i.e., smaller pixel size). For now, we’ll assume that they are both in the same projection. Prior to doing subsequent analysis comparing the two rasters, it is often necessary to align these rasters such that the value associated with a particular row and column of one raster refers to the same geographic location as the value in that same row and column of the other raster. Fortunately, this can be done in a straightforward way using GDAL utilities. First, you need to determine the resolution and bounding coordinates of raster_A. This information can be obtained using the gdalinfo command:

gdalinfo ‘‘raster_A’’

This will produce output that includes the following (edited for clarity): <...> Pixel Size = (0.01,-0.01) <...> Corner Coordinates: Upper Left (-150, 80) Lower Left (-150, 40) Upper Right (-120, 80) Lower Right (-120, 40)

Then, use gdalwarp to extract the desired portion of raster_B and resample it to produce a new map (‘‘raster_B_resamp’’) with the same extent and resolution as raster_A: gdalwarp -te -150 40 -120 80 -tr 0.01 0.01 ‘‘raster_B’’ ‘‘raster_B_resamp’’

The four numbers appearing after ‘‘-te’’ are, in order, ‘‘xmin’’, ‘‘ymin’’, ‘‘xmax’’, and ‘‘ymax’’, which together specify the desired extent of the output raster. Notice how these values come directly from the ‘Corner Coordinates’ of raster_A, as displayed by gdalinfo. The two numbers after ‘‘-tr’’ specify the desired resolution, given as pixel size in the ‘‘x’’ and ‘‘y’’ dimension. Notice how these values come directly from the Pixel Size information displayed by gdalinfo.

The default resampling method is nearest-neighbor (which can be specified explicitly by adding ‘‘-r near’’). This method is appropriate when the raster values are discrete or categorical, in which case it would be undesirable for the values to be modified by a smoothing algorithm. If the raster values are continuous (e.g., a DEM), it may be more useful to use bilinear or cubic resampling.

If raster_B also needs to be reprojected to match raster_A, no problem! The ‘‘-t_srs’’ specification (as described in the previous section) can simply be added to the gdalwarp statement, allowing all of the operations to be done in one fell swoop. Note that the coordinates and pixel size should always be given in the ‘’’'’target’’’’’ units. As long as you want to reproject raster_B to match raster_A (and not the reverse), the steps above will work. Otherwise, first use gdalwarp to reproject raster_A to match raster_B, then follow these steps to subset and resample raster_B to align with the reprojected version of raster_A.

Assign a “nodata” value to a raster

You may occasionally have a raster dataset in which a particular value indicates lack of information. Prior to analysis and display, it is often useful to designate this ‘‘nodata’’ value explicitly. This can be done using gdal_translate:

gdal_translate -a_nodata 255 input_raster output_raster (Note that ‘‘nodata’’ values are not supported by all raster formats.)

“Burn” polygons into an raster

The gdal_rasterize function will (re)assign a specified value to all cells of the input raster that overlap any polygons of the input vector. The example below assumes you have a polygon shapefile ‘‘mypolygons.shp’’, and a single band raster layer ‘‘myraster’’ in the same projection. (Other supported vector and raster formats can be substituted.)

gdal_rasterize -b ‘‘1’’ -burn ‘‘255’’ -l ‘‘mypolygons’’ ‘‘mypolygons.shp’’ ‘‘myraster’’

Note that if the raster layer has a ‘‘nodata’’ value, specifying this value as the ‘‘-burn’’ value can be a convenient way to “clip out” portions of the raster.

GDAL/OGR resources on the web
Resource portals