<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html><head><meta name="robots" content="noindex">
<meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
<title>GDAL Utilities</title>
<link href="doxygen.css" rel="stylesheet" type="text/css">
</head><body bgcolor="#ffffff">
<!-- Generated by Doxygen 1.2.3-20001105 on Thu Mar 28 09:47:33 2002 -->
<center>
<a class="qindex" href="index.html">Main Page</a> <a class="qindex" href="hierarchy.html">Class Hierarchy</a> <a class="qindex" href="annotated.html">Compound List</a> <a class="qindex" href="files.html">File List</a> <a class="qindex" href="functions.html">Compound Members</a> <a class="qindex" href="globals.html">File Members</a> <a class="qindex" href="pages.html">Related Pages</a> </center>
<hr><a name="gdal_utilities"><h2>GDAL Utilities</h2></a>
<p>
<center>
<p>
</center>
<p>
The following utility programs are distributed with GDAL.
<p>
<h2>gdalinfo</h2>
<p>
The gdalinfo program lists various information about a GDAL supported raster dataset.
<p>
<div class="fragment"><pre>
Usage: gdalinfo [-mm] datasetname
</div></pre>
<p>
The -mm switch will force computation of the actual min/max values for each band in the dataset.
<p>
The gdalinfo will report all of the following (if known):
<p>
<ul>
<li> The format driver used to access the file. <li> Raster size (in pixel and lines). <li> The coordinate system for the file (in OGC WKT). <li> The geotransform associated with the file (rotational coefficients are currently not reported). <li> Corner coordinates in georeferenced, and if possible lat/long based on the full geotransform (but not GCPs). <li> Ground control points. <li> File wide (including subdatasets) metadata. <li> Band data types. <li> Band color interpretations. <li> Band block size. <li> Band descriptions. <li> Band min/max values (internally known and possibly computed). <li> Band NODATA value. <li> Band overview resolutions available. <li> Band unit type (ie. "meters" or "feet" for elevation bands). <li> Band pseudo-color tables. </ul>
<p>
Example: <div class="fragment"><pre>
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
</div></pre>
<p>
<h2>gdal_translate</h2>
<p>
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.
<p>
<div class="fragment"><pre>
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
</div></pre>
<p>
<ul>
<li> <b>-ot</b>: For the output bands to be of the indicated data type. <li> <b>-not_strict</b>: Be forgiving of mismatches and lost data when translating to the output format. <li> <b>-of</b> <em>format</em>: Select the output format. The default is GeoTIFF (GTiff). Use the short format name. <li> <b>-b</b> <em>band</em>: Select only input band <em>band</em> for output. Bands are numbered from 1. <li> <b>-outsize</b> <em>xsize[%] ysize[%]</em>: 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. <li> <b>-scale</b> <em>[src_min src_max [dst_min dst_max]]</em>: Rescale the input pixels values from the range <em>src_min</em> to <em>src_max</em> to the range <em>dst_min</em> to <em>dst_max</em>. If omitted the output range is 0 to 255. If omitted the input range is automatically computed from the source data. <li> <b>-srcwin</b> <em>xoff yoff xsize ysize</em>: Selects a subwindow from the source image for copying. <li> <b>-co</b> <em>"NAME=VALUE"</em>: passes a creation option to the output format driver. Multiple <b>-co</b> options may be listed. See format specific documentation for legal creation options for each format. <li> <em>src_dataset</em>: The source file name. <li> <em>dst_dataset</em>: The destination file name. </ul>
<p>
Example: <div class="fragment"><pre>
% gdal_translate -of GTiff -co "TILED=YES" utm.tif utm_tiled.tif
</div></pre>
<p>
<h2>gdaladdo</h2>
<p>
The gdaladdo utility can be used to build or rebuild overview images for most supported file formats with one over several downsampling algorithms.
<p>
<div class="fragment"><pre>
Usage: gdaladdo [-r {nearest,average,average_mp,average_magphase,mode}]
filename levels
Example:
% gdaladdo -r average abc.tif 2 4 8 16
</div></pre>
<p>
<ul>
<li> <b>-r</b> <em>{nearest,average,average_mp,average_magphase,mode}</em>: Select a resampling algorithm. <li> <em>filename</em>: The file to build overviews for. <li> <em>levels</em>: A list of integral overview levels to build. </ul>
<p>
<em>Mode</em> is not actually implemented, and <em>average_mp</em> is unsuitable for use. <em>Average_magphase</em> averages complex data in mag/phase space. <em>Nearest</em> and <em>average</em> are applicable to normal image data. <em>Nearest</em> applies a nearest neighbour (simple sampling) resampler, while <em>average</em> computes the average of all non-NODATA contributing pixels.
<p>
Selecting a level value like <em>2</em> 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.
<p>
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.
<p>
<h2>gdaltindex</h2>
<p>
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.
<p>
<div class="fragment"><pre>
Usage: gdaltindex [-tileindex field_name] index_file [gdal_file]*
eg.
% gdaltindex doq_index.shp doq/*.tif
</div></pre>
<p>
<ul>
<li> The shapefile (index_file) will be created if it doesn't already exist. <li> The default tile index field is 'location'. <li> Raster filenames will be put in the file exactly as they are specified on the commandline. <li> Simple rectangular polygons are generated in the same coordinate system as the rasters. </ul>
<p>
<h2>rgb2pct.py</h2>
<p>
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.
<p>
<div class="fragment"><pre>
Usage: rgb2pct.py [-n colors] [-of format] source_file dest_file
</div></pre>
<p>
<ul>
<li> <b>-n</b> <em>colors</em>: Select the number of colors in the generated color table. Defaults to 256. Must be between 2 and 256. <li> <b>-of</b> <em>format</em>: Format to generated (defaults to GeoTIFF). Same semantics as the <b>-of</b> flag for gdal_translate. Only output formats supporting pseudocolor tables should be used. <li> <em>source_file</em>: The input RGB file. <li> <em>dest_file</em>: The output pseudo-colored file that will be created. </ul>
<p>
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.
<p>
<h2>gdal_merge.py</h2>
<p>
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.
<p>
<div class="fragment"><pre>
Usage: gdal_merge.py [-o out_filename] [-f out_format] [-v]
[-ps pixelsize_x pixelsize_y]
[-ul_lr ulx uly lrx lry] input_files
</div></pre>
<p>
<ul>
<li> <b>-o</b> <em>out_filename</em>: The name of the output file to be created. <li> <b>-f</b> <em>out_format</em>: Output format, defaults to GeoTIFF. <li> <b>-ps</b> <em>pixelsize_x pixelsize_y</em>: Pixel size to be used for the output file. If not specified the resolution of the first input file will be used. <li> <b>-ul_lr</b> <em>ulx uly lrx lry</em>: The extents of the output file. If not specified the aggregate extents of all input files will be used. <li> <b>-v</b>: Generate verbose output of mosaicing operations as they are done. </ul>
<p>
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.
<p>
<h2>gdal-config</h2>
<p>
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.
<p>
<div class="fragment"><pre>
Usage: gdal-config [OPTIONS]
Options:
[--prefix[=DIR]]
[--libs]
[--cflags]
[--version]
[--ogr-enabled]
[--formats]
</div></pre>
<p>
<ul>
<li> <b>--prefix</b>: the top level directory for the GDAL installation. <li> <b>--libs</b>: The libraries and link directives required to use GDAL. <li> <b>--cflags</b>: The include and macro definition required to compiled modules using GDAL. <li> <b>--version</b>: Reports the GDAL version. <li> <b>--ogr-enabled</b>: Reports "yes" or "no" to standard output depending on whether OGR is built into GDAL. <li> <b>--formats</b>: Reports which formats are configured into GDAL to stdout. </ul>
<p>
<hr><address><small>Generated at Thu Mar 28 09:47:33 2002 for GDAL by
<a href="http://www.stack.nl/~dimitri/doxygen/index.html">
<img src="doxygen.gif" alt="doxygen" align="middle" border=0
width=110 height=53></a>1.2.3-20001105 written by <a href="mailto:dimitri@stack.nl">Dimitri van Heesch</a>,
© 1997-2000</small></address>
</body>
</html>
