Main Page Class Hierarchy Compound List File List Compound Members File Members Related Pages

## GDAL Utilities

The following utility programs are distributed with GDAL.

## gdalinfo

The gdalinfo program lists various information about a GDAL supported raster dataset.

    Usage: gdalinfo [-mm] datasetname

The -mm switch will force computation of the actual min/max values for each band in the dataset.

The gdalinfo will report all of the following (if known):

- The format driver used to access the file.
- Raster size (in pixel and lines).
- The coordinate system for the file (in OGC WKT).
- The geotransform associated with the file (rotational coefficients are currently not reported).
- Corner coordinates in georeferenced, and if possible lat/long based on the full geotransform (but not GCPs).
- Ground control points.
- File wide (including subdatasets) metadata.
- Band data types.
- Band color interpretations.
- Band block size.
- Band descriptions.
- Band min/max values (internally known and possibly computed).
- Band NODATA value.
- Band overview resolutions available.
- Band unit type (ie. "meters" or "feet" for elevation bands).
- Band pseudo-color tables.

Example:

    warmerda@gdal[138]% gdalinfo ~/openev/utm.tif
    Driver: GTiff/GeoTIFF
    Size is 512, 512
    Coordinate System is:
    PROJCS["NAD27 / UTM zone 11N",
        GEOGCS["NAD27",
            DATUM["North_American_Datum_1927",
                SPHEROID["Clarke 1866",6378206.4,294.978698213901]],
            PRIMEM["Greenwich",0],
            UNIT["degree",0.0174532925199433]],
        PROJECTION["Transverse_Mercator"],
        PARAMETER["latitude_of_origin",0],
        PARAMETER["central_meridian",-117],
        PARAMETER["scale_factor",0.9996],
        PARAMETER["false_easting",500000],
        PARAMETER["false_northing",0],
        UNIT["metre",1]]
    Origin = (440720.000000,3751320.000000)
    Pixel Size = (60.000000,-60.000000)
    Corner Coordinates:
    Upper Left  (  440720.000, 3751320.000) (117d38'28.21"W, 33d54'8.47"N)
    Lower Left  (  440720.000, 3720600.000) (117d38'20.79"W, 33d37'31.04"N)
    Upper Right (  471440.000, 3751320.000) (117d18'32.07"W, 33d54'13.08"N)
    Lower Right (  471440.000, 3720600.000) (117d18'28.50"W, 33d37'35.61"N)
    Center      (  456080.000, 3735960.000) (117d28'27.39"W, 33d45'52.46"N)
    Band 1 Block=512x16 Type=Byte, ColorInterp=Gray

## gdal_translate

The gdal_translate utility can be used to convert raster data between different formats, potentially peforming some operations like subsettings, resampling, and rescaling pixels in the process.

    Usage: gdal_translate
           [-ot {Byte/UInt16/UInt32/Int32/Float32/Float64/CInt16/
                 CInt32/CFloat32/CFloat64}] [-not_strict]
           [-of format] [-b band] [-outsize xsize[%] ysize[%]]
           [-scale [src_min src_max [dst_min dst_max]]]
           [-srcwin xoff yoff xsize ysize] [-co "NAME=VALUE"]*
           src_dataset dst_dataset

- -ot: For the output bands to be of the indicated data type.
- -not_strict: Be forgiving of mismatches and lost data when translating to the output format.
- -of format: Select the output format. The default is GeoTIFF (GTiff). Use the short format name.
- -b band: Select only input band band for output. Bands are numbered from 1.
- -outsize xsize[%] ysize[%]: Set the size of the output file. Outsize is in pixels and lines unless '%' is attached in which case it is as a fraction of the input image size.
- -scale [src_min src_max [dst_min dst_max]]: Rescale the input pixels values from the range src_min to src_max to the range dst_min to dst_max. If omitted the output range is 0 to 255. If omitted the input range is automatically computed from the source data.
- -srcwin xoff yoff xsize ysize: Selects a subwindow from the source image for copying.
- -co "NAME=VALUE": passes a creation option to the output format driver. Multiple -co options may be listed. See format specific documentation for legal creation options for each format.
- src_dataset: The source file name.
- dst_dataset: The destination file name.

Example:

    % gdal_translate -of GTiff -co "TILED=YES" utm.tif utm_tiled.tif

## gdaladdo

The gdaladdo utility can be used to build or rebuild overview images for most supported file formats with one over several downsampling algorithms.

    Usage: gdaladdo [-r {nearest,average,average_mp,average_magphase,mode}]
                    filename levels

    Example:
     % gdaladdo -r average abc.tif 2 4 8 16

- -r {nearest,average,average_mp,average_magphase,mode}: Select a resampling algorithm.
- filename: The file to build overviews for.
- levels: A list of integral overview levels to build.

Mode is not actually implemented, and average_mp is unsuitable for use. Average_magphase averages complex data in mag/phase space. Nearest and average are applicable to normal image data. Nearest applies a nearest neighbour (simple sampling) resampler, while average computes the average of all non-NODATA contributing pixels.

Selecting a level value like 2 causes an overview level that is 1/2 the resolution (in each dimension) of the base layer to be computed. If the file has existing overview levels at a level selected, those levels will be recomputed and rewritten in place.

Some format drivers do not support overviews at all. Many format drivers store overviews in a secondary file with the extension .ovr. The GeoTIFF driver stores overviews internally to the file operated on.

## gdaltindex

This program builds a shapefile with a record for each input raster file, an attribute containing the filename, and a polygon geometry outlining the raster. This output is suitable for use with UMN MapServer as a raster tileindex.

    Usage: gdaltindex [-tileindex field_name] index_file [gdal_file]*

    eg.
      % gdaltindex doq_index.shp doq/*.tif

- The shapefile (index_file) will be created if it doesn't already exist.
- The default tile index field is 'location'.
- Raster filenames will be put in the file exactly as they are specified on the commandline.
- Simple rectangular polygons are generated in the same coordinate system as the rasters.

## rgb2pct.py

This utility will compute an optimal pseudo-color table for a given RGB image using a median cut algorithm on a downsampled RGB histogram. Then it converts the image into the a pseudo-colored image using the color table. This conversion utilizes Floyd-Steinberg dithering (error diffusion) to maximize output image visual quality.

    Usage: rgb2pct.py [-n colors] [-of format] source_file dest_file

- -n colors: Select the number of colors in the generated color table. Defaults to 256. Must be between 2 and 256.
- -of format: Format to generated (defaults to GeoTIFF). Same semantics as the -of flag for gdal_translate. Only output formats supporting pseudocolor tables should be used.
- source_file: The input RGB file.
- dest_file: The output pseudo-colored file that will be created.

NOTE: rgb2pct.py is a Python script, and will only work if GDAL was built with Python support. It is also not installed by default. It is found at $GDAL_HOME/pymod.

## gdal_merge.py

This utility will automatically mosaic a set of images. All the images must be in the same coordinate system and have a matching number of bands, but they may be overlapping, and at different resolutions.

    Usage: gdal_merge.py [-o out_filename] [-f out_format] [-v]
                         [-ps pixelsize_x pixelsize_y]
                         [-ul_lr ulx uly lrx lry] input_files

- -o out_filename: The name of the output file to be created.
- -f out_format: Output format, defaults to GeoTIFF.
- -ps pixelsize_x pixelsize_y: Pixel size to be used for the output file. If not specified the resolution of the first input file will be used.
- -ul_lr ulx uly lrx lry: The extents of the output file. If not specified the aggregate extents of all input files will be used.
- -v: Generate verbose output of mosaicing operations as they are done.

NOTE: gdal_merge.py is a Python script, and will only work if GDAL was built with Python support. It is also not installed by default. It is found at $GDAL_HOME/pymod.

## gdal-config

This utility script (available on Unix systems) can be used to determine various information about a GDAL installation. It is normally just used by configure scripts for applications using GDAL but can be queried by an end user.

    Usage: gdal-config [OPTIONS]
    Options:
            [--prefix[=DIR]]
            [--libs]
            [--cflags]
            [--version]
            [--ogr-enabled]
            [--formats]

- --prefix: the top level directory for the GDAL installation.
- --libs: The libraries and link directives required to use GDAL.
- --cflags: The include and macro definition required to compiled modules using GDAL.
- --version: Reports the GDAL version.
- --ogr-enabled: Reports "yes" or "no" to standard output depending on whether OGR is built into GDAL.
- --formats: Reports which formats are configured into GDAL to stdout.