<!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 API Tutorial</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_tutorial"><h2>GDAL API Tutorial</h2></a>
<p>
<center>
<p>
</center>
<p>
<h2>Opening the File</h2>
<p>
Before opening a GDAL supported raster datastore it is necessary to register drivers. There is a driver for each supported format. Normally this is accomplished with the <a class="el" href="gdal_h.html#a57">GDALAllRegister</a>() function which attempts to register all known drivers, including those auto-loaded from .so files using <a class="el" href="class_GDALDriverManager.html#a8">GDALDriverManager::AutoLoadDrivers</a>(). If for some applications it is necessary to limit the set of drivers it may be helpful to review the code from <a href="gdalallregister.cpp.html">gdalallregister.cpp</a>.
<p>
Once the drivers are registered, the application should call the free standing <a class="el" href="gdal_h.html#a60">GDALOpen</a>() function to open a dataset, passing the name of the dataset and the access desired (GA_ReadOnly or GA_Update).
<p>
In C++: <div class="fragment"><pre><font class="preprocessor">#include "gdal_priv.h"</font>
<font class="keywordtype">int</font> main()<font class="keyword"></font>
<font class="keyword"></font>{
<a class="code" href="class_GDALDataset.html">GDALDataset</a> *poDataset;
<a class="code" href="gdal_h.html#a57">GDALAllRegister</a>();
poDataset = (<a class="code" href="class_GDALDataset.html">GDALDataset</a> *) <a class="code" href="gdal_h.html#a60">GDALOpen</a>( pszFilename, GA_ReadOnly );
<font class="keywordflow">if</font>( poDataset == NULL )
{
...;
}</div></pre>
<p>
In C: <div class="fragment"><pre><font class="preprocessor">#include "<a class="code" href="gdal_h.html">gdal.h</a>"</font>
<font class="keywordtype">int</font> main()<font class="keyword"></font>
<font class="keyword"></font>{
GDALDatasetH hDataset;
<a class="code" href="gdal_h.html#a57">GDALAllRegister</a>();
hDataset = <a class="code" href="gdal_h.html#a60">GDALOpen</a>( pszFilename, GA_ReadOnly );
<font class="keywordflow">if</font>( hDataset == NULL )
{
...;
}</div></pre>
<p>
In Python: <div class="fragment"><pre> import gdal
from gdalconst import *
dataset = gdal.Open( filename, GA_ReadOnly )
<font class="keywordflow">if</font> dataset is None:
...</div></pre>
<p>
Note that if <a class="el" href="gdal_h.html#a60">GDALOpen</a>() returns NULL it means the open failed, and that an error messages will already have been emitted via <a class="el" href="cpl_error_h.html#a17">CPLError</a>(). If you want to control how errors are reported to the user review the <a class="el" href="cpl_error_h.html#a17">CPLError</a>() documentation. Generally speaking all of GDAL uses <a class="el" href="cpl_error_h.html#a17">CPLError</a>() for error reporting. Also, note that pszFilename need not actually be the name of a physical file (though it usually is). It's interpretation is driver dependent, and it might be an URL, a filename with additional parameters added at the end controlling the open or almost anything. Please try not to limit GDAL file selection dialogs to only selecting physical files.
<p>
<h2>Getting Dataset Information</h2>
<p>
As described in the <a href="gdal_datamodel.html">GDAL Data Model</a>, a <a class="el" href="class_GDALDataset.html">GDALDataset</a> contains a list of raster bands, all pertaining to the same area, and having the same resolution. It also has metadata, a coordinate system, a georeferencing transform, size of raster and various other information. If we wanted to print some general information about the dataset we might do the following:
<p>
In C++: <div class="fragment"><pre> <font class="keywordtype">double</font> adfGeoTransform[6];
printf( <font class="stringliteral">"Driver: %s/%s\n"</font>,
poDataset-><a class="code" href="class_GDALDataset.html#a12">GetDriver</a>()->pszShortName,
poDataset-><a class="code" href="class_GDALDataset.html#a12">GetDriver</a>()->pszLongName );
printf( <font class="stringliteral">"Size is %dx%dx%d\n"</font>,
poDataset-><a class="code" href="class_GDALDataset.html#a1">GetRasterXSize</a>(), poDataset-><a class="code" href="class_GDALDataset.html#a2">GetRasterYSize</a>(),
poDataset-><a class="code" href="class_GDALDataset.html#a3">GetRasterCount</a>() );
<font class="keywordflow">if</font>( poDataset-><a class="code" href="class_GDALDataset.html#a6">GetProjectionRef</a>() != NULL )
printf( <font class="stringliteral">"Projection is `%s'\n"</font>, poDataset-><a class="code" href="class_GDALDataset.html#a6">GetProjectionRef</a>() );
<font class="keywordflow">if</font>( poDataset-><a class="code" href="class_GDALDataset.html#a8">GetGeoTransform</a>( adfGeoTransform ) == CE_None )
{
printf( <font class="stringliteral">"Origin = (%.6f,%.6f)\n"</font>,
adfGeoTransform[0], adfGeoTransform[3] );
printf( <font class="stringliteral">"Pixel Size = (%.6f,%.6f)\n"</font>,
adfGeoTransform[1], adfGeoTransform[5] );
}</div></pre>
<p>
In C: <div class="fragment"><pre> GDALDriverH hDriver;
<font class="keywordtype">double</font> adfGeoTransform[6];
hDriver = GDALGetDatasetDriver( hDataset );
printf( <font class="stringliteral">"Driver: %s/%s\n"</font>,
GDALGetDriverShortName( hDriver ),
GDALGetDriverLongName( hDriver ) );
printf( <font class="stringliteral">"Size is %dx%dx%d\n"</font>,
GDALGetRasterXSize( hDataset ),
GDALGetRasterYSize( hDataset ),
GDALGetRasterCount( hDataset ) );
<font class="keywordflow">if</font>( GDALGetProjectionRef( hDataset ) != NULL )
printf( <font class="stringliteral">"Projection is `%s'\n"</font>, GDALGetProjectionRef( hDataset ) );
<font class="keywordflow">if</font>( GDALGetGeoTransform( hDataset, adfGeoTransform ) == CE_None )
{
printf( <font class="stringliteral">"Origin = (%.6f,%.6f)\n"</font>,
adfGeoTransform[0], adfGeoTransform[3] );
printf( <font class="stringliteral">"Pixel Size = (%.6f,%.6f)\n"</font>,
adfGeoTransform[1], adfGeoTransform[5] );
}</div></pre>
<p>
In Python (note, driver bindings are not currently available): <div class="fragment"><pre> print 'Size is ',dataset.RasterXSize,<font class="charliteral">'x'</font>,dataset.RasterYSize, \
<font class="charliteral">'x'</font>,dataset.RasterCount
print 'Projection is ',dataset.GetProjection()
geotransform = dataset.GetGeoTransform()
<font class="keywordflow">if</font> not geotransform is None:
print 'Origin = (',geotransform[0], <font class="charliteral">','</font>,geotransform[3],<font class="charliteral">')'</font>
print 'Pixel Size = (',geotransform[1], <font class="charliteral">','</font>,geotransform[5],<font class="charliteral">')'</font></div></pre>
<p>
<h2>Fetching a Raster Band</h2>
<p>
At this time access to raster data via GDAL is done one band at a time. Also, there is metadata, blocksizes, color tables, and various other information available on a band by band basis. The following codes fetches a <a class="el" href="class_GDALRasterBand.html">GDALRasterBand</a> object from the dataset (numbered 1 through GetRasterCount()) and displays a little information about it.
<p>
In C++: <div class="fragment"><pre> <a class="code" href="class_GDALRasterBand.html">GDALRasterBand</a> *poBand;
<font class="keywordtype">int</font> nBlockXSize, nBlockYSize;
<font class="keywordtype">int</font> bGotMin, bGotMax;
<font class="keywordtype">double</font> adfMinMax[2];
poBand = poDataset-><a class="code" href="class_GDALDataset.html#a4">GetRasterBand</a>( 1 );
poBand-><a class="code" href="class_GDALRasterBand.html#a6">GetBlockSize</a>( &nBlockXSize, &nBlockYSize );
printf( <font class="stringliteral">"Block=%dx%d Type=%s, ColorInterp=%s\n"</font>,
nBlockXSize, nBlockYSize,
GDALGetDataTypeName(poBand-><a class="code" href="class_GDALRasterBand.html#a5">GetRasterDataType</a>()),
<a class="code" href="gdal_h.html#a50">GDALGetColorInterpretationName</a>(
poBand-><a class="code" href="class_GDALRasterBand.html#a22">GetColorInterpretation</a>()) );
adfMinMax[0] = poBand-><a class="code" href="class_GDALRasterBand.html#a17">GetMinimum</a>( &bGotMin );
adfMinMax[1] = poBand-><a class="code" href="class_GDALRasterBand.html#a18">GetMaximum</a>( &bGotMax );
<font class="keywordflow">if</font>( ! (bGotMin && bGotMax) )
<a class="code" href="gdal_h.html#a118">GDALComputeRasterMinMax</a>((GDALRasterBandH)poBand, TRUE, adfMinMax);
printf( <font class="stringliteral">"Min=%.3fd, Max=%.3f\n"</font>, adfMinMax[0], adfMinMax[1] );
<font class="keywordflow">if</font>( poBand-><a class="code" href="class_GDALRasterBand.html#a28">GetOverviewCount</a>() > 0 )
printf( <font class="stringliteral">"Band has %d overviews.\n"</font>, poBand-><a class="code" href="class_GDALRasterBand.html#a28">GetOverviewCount</a>() );
<font class="keywordflow">if</font>( poBand-><a class="code" href="class_GDALRasterBand.html#a23">GetColorTable</a>() != NULL )
printf( <font class="stringliteral">"Band has a color table with %d entries.\n"</font>,
poBand-><a class="code" href="class_GDALRasterBand.html#a23">GetColorTable</a>()->GetColorEntryCount() );</div></pre>
<p>
In C: <div class="fragment"><pre> <a class="code" href="class_GDALRasterBand.html">GDALRasterBand</a> hBand;
<font class="keywordtype">int</font> nBlockXSize, nBlockYSize;
<font class="keywordtype">int</font> bGotMin, bGotMax;
<font class="keywordtype">double</font> adfMinMax[2];
hBand = GDALGetRasterBand( hDataset, 1 );
GDALGetBlockSize( hBand, &nBlockXSize, &nBlockYSize );
printf( <font class="stringliteral">"Block=%dx%d Type=%s, ColorInterp=%s\n"</font>,
nBlockXSize, nBlockYSize,
GDALGetDataTypeName(GDALGetRasterDataType(hBand)),
<a class="code" href="gdal_h.html#a50">GDALGetColorInterpretationName</a>(
GDALGetRasterColorInterpretation(hBand)) );
adfMinMax[0] = GDALGetRasterMinimum( hBand, &bGotMin );
adfMinMax[1] = GDALGetRasterMaximum( hBand, &bGotMax );
<font class="keywordflow">if</font>( ! (bGotMin && bGotMax) )
<a class="code" href="gdal_h.html#a118">GDALComputeRasterMinMax</a>( hBand, TRUE, adfMinMax );
printf( <font class="stringliteral">"Min=%.3fd, Max=%.3f\n"</font>, adfMinMax[0], adfMinMax[1] );
<font class="keywordflow">if</font>( GDALGetOverviewCount(hBand) > 0 )
printf( <font class="stringliteral">"Band has %d overviews.\n"</font>, GDALGetOverviewCount(hBand));
<font class="keywordflow">if</font>( GDALGetRasterColorTable( hBand ) != NULL )
printf( <font class="stringliteral">"Band has a color table with %d entries.\n"</font>,
GDALGetColorEntryCount(
GDALGetRasterColorTable( hBand ) ) );</div></pre>
<p>
In Python (note several bindings are missing): <div class="fragment"><pre> band = dataset.GetRasterBand(1)
print 'Band Type=',gdal.GetDataTypeName(band.DataType)
<font class="keywordflow">if</font> not band.GetRasterColorTable() is None:
print 'Band has a color table.'</div></pre>
<p>
<h2>Reading Raster Data</h2>
<p>
There are a few ways to read raster data, but the most common is via the <a class="el" href="class_GDALRasterBand.html#a8">GDALRasterBand::RasterIO</a>() method. This method will automatically take care of data type conversion, up/down sampling and windowing. The following code will read the first scanline of data into a similarly sized buffer, converting it to floating point as part of the operation.
<p>
In C++: <div class="fragment"><pre> <font class="keywordtype">float</font> *pafScanline;
<font class="keywordtype">int</font> nXSize = poBand-><a class="code" href="class_GDALRasterBand.html#a2">GetXSize</a>();
pafScanline = (<font class="keywordtype">float</font> *) <a class="code" href="cpl_conv_h.html#a3">CPLMalloc</a>(<font class="keyword">sizeof</font>(<font class="keywordtype">float</font>)*nXSize);
poBand-><a class="code" href="class_GDALRasterBand.html#a8">RasterIO</a>( GF_Read, 0, 0, nXSize, 1,
pafScanline, nXSize, 1, GDT_Float32,
0, 0 );</div></pre>
<p>
In C: <div class="fragment"><pre> <font class="keywordtype">float</font> *pafScanline;
<font class="keywordtype">int</font> nXSize = GDALGetRasterBandXSize( hBand );
pafScanline = (<font class="keywordtype">float</font> *) <a class="code" href="cpl_conv_h.html#a3">CPLMalloc</a>(<font class="keyword">sizeof</font>(<font class="keywordtype">float</font>)*nXSize);
GDALRasterIO( hBand, GF_Read, 0, 0, nXSize, 1,
pafScanline, nXSize, 1, GDT_Float32,
0, 0 );</div></pre>
<p>
In Python (note that the returned scanline is of type string, and contains xsize*4 bytes of raw binary floating point data):
<p>
<div class="fragment"><pre> scanline = band.ReadRaster( 0, 0, band.XSize, 1, \
band.XSize, 1, GDT_Float32 )</div></pre>
<p>
The RasterIO call takes the following arguments. <div class="fragment"><pre>CPLErr <a class="code" href="class_GDALRasterBand.html#a8">GDALRasterBand::RasterIO</a>( GDALRWFlag eRWFlag,
<font class="keywordtype">int</font> nXOff, <font class="keywordtype">int</font> nYOff, <font class="keywordtype">int</font> nXSize, <font class="keywordtype">int</font> nYSize,
<font class="keywordtype">void</font> * pData, <font class="keywordtype">int</font> nBufXSize, <font class="keywordtype">int</font> nBufYSize,
GDALDataType eBufType,
<font class="keywordtype">int</font> nPixelSpace,
<font class="keywordtype">int</font> nLineSpace )</div></pre>
<p>
Note that the same RasterIO() call is used to read, or write based on the setting of eRWFlag (either GF_Read or GF_Write). The nXOff, nYOff, nXSize, nYSize argument describe the window of raster data on disk to read (or write). It doesn't have to fall on tile boundaries though access may be more efficient if it does.
<p>
The pData is the memory buffer the data is read into, or written from. It's real type must be whatever is passed as eBufType, such as GDT_Float32, or GDT_Byte. The RasterIO() call will take care of converting between the buffer's data type and the data type of the band. Note that when converting floating point data to integer RasterIO() rounds down, and when converting source values outside the legal range of the output the nearest legal value is used. This implies, for instance, that 16bit data read into a GDT_Byte buffer will map all values greater than 255 to 255, <b>the data is not scaled!</b>
<p>
The nBufXSize and nBufYSize values describe the size of the buffer. When loading data at full resolution this would be the same as the window size. However, to load a reduced resolution overview this could be set to smaller than the window on disk. In this case the RasterIO() will utilize overviews to do the IO more efficiently if the overviews are suitable.
<p>
The nPixelSpace, and nLineSpace are normally zero indicating that default values should be used. However, they can be used to control access to the memory data buffer, allowing reading into a buffer containing other pixel interleaved data for instance.
<p>
<h2>Closing the Dataset</h2>
<p>
Please keep in mind that <a class="el" href="class_GDALRasterBand.html">GDALRasterBand</a> objects are <em>owned</em> by their dataset, and they should never be destroyed with the C++ delete operator. <a class="el" href="class_GDALDataset.html">GDALDataset</a>'s can be closed either by calling <a class="el" href="gdal_h.html">GDALClose</a>() or using the delete operator on the <a class="el" href="class_GDALDataset.html">GDALDataset</a>. Either will result in proper cleanup, and flushing of any pending writes.
<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>
