GDAL_API教程.docVIP

GDAL API TutorialBefore opening a GDAL supported raster datastore it is necessary to register drivers. 在打开一个GDAL支持的栅格资料之前，必需要注册驱动。There is a driver for each supported format. 每个驱动对应各自支持的格式。Normally this is accomplished with the GDALAllRegister() function which attempts to register all known drivers, including those auto-loaded from .so files using GDALDriverManager:AutoLoadDrivers(). 通常这个会被GDALAllRegister（）函数完成，试图去注册所有已知的驱动包括使用GDALDriverManager:AutoLoadDrivers()从.so文件来加载。If for some applications it is necessary to limit the set of drivers it may be helpful to review the code from gdalallregister.cpp. 如果一些程序有必要去限制驱动集合，检查gdalallregister.cpp的代码将会有所帮助，Python automatically calls GDALAllRegister() when the gdal module is imported.当gdal模块被导入时，Python会自动调用GDALAllRegister()。Once the drivers are registered, the application should call the free standing GDALOpen() function to open a dataset, passing the name of the dataset and the access desired (GA_ReadOnly or GA_Update).一但驱动被注册，程序将会调用独立的GDALOpen（）函数通过dataset的名称和需要的存取方式（GA_ReadOnly或GA_Update）来打开dataset.#include gdal_priv.hint main() GDALDataset *poDataset; GDALAllRegister(); poDataset = (GDALDataset *) GDALOpen( pszFilename, GA_ReadOnly ); if( poDataset = NULL ) .; Note that if GDALOpen() returns NULL it means the open failed, and that an error messages will already have been emitted via CPLError(). 注意 如果GDALOpen（）返回NULL，意味着打开失败了，这个错误信息将会通过CPLError（）释放出。If you want to control how errors are reported to the user review the CPLError() documentation. 如果你想控制错误怎样被报告给用户，参考CPLError文档。Generally speaking all of GDAL uses CPLError() for error reporting. 一般而言，所有的GDAL都是用CPLError（）来报告错误。Also, note that pszFilename need not actually be the name of a physical file (though it usually is).同样，注意pszFilename 不需要确实是物理文件名称（尽管通常都是如此）。 Its 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. 这个解释了驱动的依赖性，它可能是一个URL， 带有加在最后的额外的参数的文件名，控制了打开或是其他行为。Please try not to limit GDAL file selection dialogs to only selecting physical files.请不要去限制GDAL文件选择对话框去仅仅选择物理文件。Getting Dataset InformationAs described in the GDAL Data Model, a GDALDataset contains a list of raster bands, all pertaining to the same area, and having the same resolution.作为在GDAL Data model的描述，一个GDALDataset包含了一个栅格波段列表，都属于相同区域，并且有相同分辨率。 It also has metadata, a coordinate system, a georeferencing transform, size of raster and various other information.也同样含有元数据，坐标系统，地理参考坐标系转换，栅格大小和多种多样的其他数据。adfGeoTransform0 /* top left x */ adfGeoTransform1 /* w-e pixel resolution */ adfGeoTransform2 /* rotation, 0 if image is north up */ adfGeoTransform3 /* top left y */ adfGeoTransform4 /* rotation, 0 if image is north up */ adfGeoTransform5 /* n-s pixel resolution */If we wanted to print some general information about the dataset we might do the following:如果我们想要输出一些关于dataset的主要信息，我们可以按以下所说的做：In C+: double adfGeoTransform6; printf( Driver: %s/%sn, poDataset-GetDriver()-GetDescription(), poDataset-GetDriver()-GetMetadataItem( GDAL_DMD_LONGNAME ) ); printf( Size is %dx%dx%dn, poDataset-GetRasterXSize(), poDataset-GetRasterYSize(), poDataset-GetRasterCount() ); if( poDataset-GetProjectionRef() != NULL ) printf( Projection is %sn, poDataset-GetProjectionRef() ); if( poDataset-GetGeoTransform( adfGeoTransform ) = CE_None ) printf( Origin = (%.6f,%.6f)n, adfGeoTransform0, adfGeoTransform3 ); printf( Pixel Size = (%.6f,%.6f)n, adfGeoTransform1, adfGeoTransform5 ); Fetching a Raster BandAt this time access to raster data via GDAL is done one band at a time.这时通过GDAL存取栅格数据，每次只完成一个波段。 Also, there is metadata, blocksizes, color tables, and various other information available on a band by band basis.同样以波段为基础的元数据，区块，颜色表和其他可见的信息 The following codes fetches a GDALRasterBand object from the dataset (numbered 1 through GetRasterCount() and displays a little information about it.下面的代码从dataset(通过GetRasterCount（）被记为1)中获取GDALRasterBand对象，并显示一些有关的信息。In C+: GDALRasterBand *poBand; int nBlockXSize, nBlockYSize; int bGotMin, bGotMax; double adfMinMax2; poBand = poDataset-GetRasterBand( 1 ); poBand-GetBlockSize( &nBlockXSize, &nBlockYSize ); printf( Block=%dx%d Type=%s, ColorInterp=%sn, nBlockXSize, nBlockYSize, GDALGetDataTypeName(poBand-GetRasterDataType(), GDALGetColorInterpretationName( poBand-GetColorInterpretation() ); adfMinMax0 = poBand-GetMinimum( &bGotMin ); adfMinMax1 = poBand-GetMaximum( &bGotMax ); if( ! (bGotMin & bGotMax) ) GDALComputeRasterMinMax(GDALRasterBandH)poBand, TRUE, adfMinMax); printf( Min=%.3fd, Max=%.3fn, adfMinMax0, adfMinMax1 ); if( poBand-GetOverviewCount() 0 ) printf( Band has %d overviews.n, poBand-GetOverviewCount() ); if( poBand-GetColorTable() != NULL ) printf( Band has a color table with %d entries.n, poBand-GetColorTable()-GetColorEntryCount() );Reading Raster DataThere are a few ways to read raster data, but the most common is via the GDALRasterBand:RasterIO() method. 有很多方法去读取栅格数据，但是最常见的是通过GDALRasterBand:RasterIO()方法。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.以下代码将会读取第一行数据到相同大小的缓冲区中，作为操作的一部分将其转换为浮点型。In C+: float *pafScanline; int nXSize = poBand-GetXSize(); pafScanline = (float *) CPLMalloc(sizeof(float)*nXSize); poBand-RasterIO( GF_Read, 0, 0, nXSize, 1, pafScanline, nXSize, 1, GDT_Float32, 0, 0 );The RasterIO call takes the following arguments.RasterIO调用需要以下这些参数。CPLErr GDALRasterBand:RasterIO( GDALRWFlag eRWFlag, int nXOff, int nYOff, int nXSize, int nYSize, void * pData, int nBufXSize, int nBufYSize, GDALDataType eBufType, int nPixelSpace, int nLineSpace )Note that the same RasterIO() call is used to read, or write based on the setting of eRWFlag (either GF_Read or GF_Write). 注意同样RasterIO调用习惯用来读取，或在eRWFlag基础上写入（GF _Read 或 GF_Write）。The nXOff, nYOff, nXSize, nYSize argument describe the window of raster data on disk to read (or write). nXOff, nYOff, nXSize, nYSize参数描述了磁盘上被读取（或写入）的栅格数据的区域大小。It doesnt have to fall on tile boundaries though access may be more efficient if it does.尽管存取可能会更有能力去做，但是没有必要去覆盖边界。The pData is the memory buffer the data is read into, or written from. pData是存储缓冲器，数据被读入或从其中被写。Its 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 buffers data type and the data type of the band. RasterIO()调用将会处理缓冲区数据类型和波段数据类型的转换。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.注意当把浮点格式转换到整型时RasterIO()会四舍五入，当转换超出合法的范围的源数据时，最接近的合法数据将会被使用。This implies, for instance, that 16bit data read into a GDT_Byte buffer will map all values greater than 255 to 255, the data is not scaled!这意味着，例如16位的数据读入到GDT_Byte 缓冲将会把所有大于255的数值变成255，这个数据不是按比例变换的。The nBufXSize and nBufYSize values describe the size of the buffer.nBufXSize 和nBufYSize描述了缓冲区的大小。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.在这个案例中，RasterIO()将会利用预览图会更高效的去做IO，如果预览图更适合。The nPixelSpace, and nLineSpace are normally zero indicating that default values should be used.nPixelSpace和nLineSpace通常是零，表示缺省值将会被使用 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.不管怎样，它们可以控制存取存储数据缓冲区，允许读入到缓冲区例如包含其他像素隔行扫描数据。Closing the DatasetPlease keep in mind that GDALRasterBand objects are owned by their dataset, and they should never be destroyed with the C+ delete operator. 请记住GDALRasterBand对象是被他们的dataset所拥有，而且他们不会被C+删除操作所销毁。GDALDatasets can be closed by calling GDALClose() (it is NOT recommended to use the delete operator on a GDALDataset for Windows users because of known issues when allocating and freeing memory across module boundaries. See the relevant topic on the FAQ). GDALDataset可以被关闭通过调用GDALClose()。（）Calling GDALClose will result in proper cleanup, and flushing of any pending writes.调用GDALClose将会引起恰当的清理，清除任何延迟的写入。Forgetting to call GDALClose on a dataset opened in update mode in a popular format like GTiff will likely result in being unable to open it afterwards.忘记调用GDALClose当一个一些流行格式的dataset（例如GTiff）被用update方式打开时，将可能导致不会再次被打开。Techniques for Creating FilesNew files in GDAL supported formats may be created if the format driver supports creation.如果格式驱动支持创建操作的话，GDAL支持的格式的新文件可以被创建。There are two general techniques for creating files, using CreateCopy() and Create().创建文件有两种方式，分别是CreateCopy() 和Create()。The CreateCopy method involves calling the CreateCopy() method on the format driver, and passing in a source dataset that should be copied. CreateCopy 方法需要调用格式驱动上的CreateCopy（）方法，并且通过源dataset来复制。The Create method involves calling the Create() method on the driver, and then explicitly writing all the metadata, and raster data with separate calls.创建的方法需要调用驱动的Create（）方法，然后清除的写入所有的元数据和栅格波段通过不同的调用。All drivers that support creating new files support the CreateCopy() method, but only a few support the Create() method.所有支持创建新文件的驱动都支持CreateCopy()方法，但是仅仅一部分支持Create()方法。To determine if a particular format supports Create or CreateCopy it is possible to check the DCAP_CREATE and DCAP_CREATECOPY metadata on the format driver object. Ensure that GDALAllRegister() has been called before calling GetDriverByName(). In this example we fetch a driver, and determine whether it supports Create() and/or CreateCopy().若要确定一个格式驱动对象是否支持Create()或者CreateCopy()，我们可以考察元数据DCAP_CREATE 和 DCAP_CREATECOPY。确保在调用GetDriverByName()方法之前已经调用了GDALAllRegister()方法。在下面的例子中，循环一个驱动，来确定它是否支持Create()或者CreateCopy()。In C+:#include cpl_string.h. const char *pszFormat = GTiff; GDALDriver *poDriver; char *papszMetadata; poDriver = GetGDALDriverManager()-GetDriverByName(pszFormat); if( poDriver = NULL ) exit( 1 ); papszMetadata = poDriver-GetMetadata(); if( CSLFetchBoolean( papszMetadata, GDAL_DCAP_CREATE, FALSE ) ) printf( Driver %s supports Create() method.n, pszFormat ); if( CSLFetchBoolean( papszMetadata, GDAL_DCAP_CREATECOPY, FALSE ) ) printf( Driver %s supports CreateCopy() method.n, pszFormat );Note that a number of drivers are read-only and wont support Create() or CreateCopy().注意一定数量的驱动是只读的，不支持Create()或CreateCopy()。Using CreateCopy()The GDALDriver:CreateCopy() method can be used fairly simply as most information is collected from the source dataset. However, it includes options for passing format specific creation options, and for reporting progress to the user as a long dataset copy takes place. A simple copy from the a file named pszSrcFilename, to a new file named pszDstFilename using default options on a format whose driver was previously fetched might look like this:GDALDriver:CreateCopy()方法可以被用来获取数据源的大部分信息。然而，它包含一些选项，能够通过特殊选项来创建选项，同时，像用户报告数据列表拷贝进程。一个简单的拷贝，从一个名为pszSrcFilename的文件到一个新文件pszDstFilename，使用驱动是事先初始化好的默认选项格式拷贝方式如下：In C+: GDALDataset *poSrcDS = (GDALDataset *) GDALOpen( pszSrcFilename, GA_ReadOnly ); GDALDataset *poDstDS; poDstDS = poDriver-CreateCopy( pszDstFilename, poSrcDS, FALSE, NULL, NULL, NULL ); /* Once were done, close properly the dataset */ if( poDstDS != NULL ) GDALClose( (GDALDatasetH) poDstDS ); GDALClose( (GDALDatasetH) poSrcDS );Note that the CreateCopy() method returns a writeable dataset, and that it must be closed properly to complete writing and flushing the dataset to disk. In the Python case this occurs automatically when dst_ds goes out of scope. The FALSE (or 0) value used for the bStrict option just after the destination filename in the CreateCopy() call indicates that the CreateCopy() call should proceed without a fatal error even if the destination dataset cannot be created to exactly match the input dataset. This might be because the output format does not support the pixel datatype of the input dataset, or because the destination cannot support writing georeferencing for instance. 注意，方法CreateCopy()返回一个可写入的数据集，在完成写入和刷新数据集到磁盘上后应该关闭。A more complex case might involve passing creation options, and using a predefined progress monitor like this:下面的例子中讲包含自定义选项，使用预先定义的方式来传递选项值：In C+: #include cpl_string.h. char *papszOptions = NULL; papszOptions = CSLSetNameValue( papszOptions, TILED, YES ); papszOptions = CSLSetNameValue( papszOptions, COMPRESS, PACKBITS ); poDstDS = poDriver-CreateCopy( pszDstFilename, poSrcDS, FALSE, papszOptions, GDALTermProgress, NULL ); /* Once were done, close properly the dataset */ if( poDstDS != NULL ) GDALClose( (GDALDatasetH) poDstDS ); CSLDestroy( papszOptions );Using Create()For situations in which you are not just exporting an existing file to a new file, it is generally necessary to use the GDALDriver:Create() method (though some interesting options are possible through use of virtual files or in-memory files). The Create() method takes an options list much like CreateCopy(), but the image size, number of bands and band type must be provided explicitly.有时候，你不仅输出一个现有文件到另一个新文件，一般来讲需要使用GDALDriver:Create()方法。该方法有跟CreateCopy()方法类似的属性选择列表，但是图像大小，波段数和波段类型必须准确给出。In C+: GDALDataset *poDstDS; char *papszOptions = NULL; poDstDS = poDriver-Create( pszDstFilename, 512, 512, 1, GDT_Byte, papszOptions );Once the dataset is successfully created, all appropriate metadata and raster data must be written to the file. What this is will vary according to usage, but a simple case with a projection, geotransform and raster data is covered here.一旦数据集创建成功，所有的元数据和光栅数据必须被写入文件。这些数据的多样化依赖于个人设置习惯。这里是一个简单的例子。In C+: double adfGeoTransform6 = 444720, 30, 0, 3751320, 0, -30 ; OGRSpatialReference oSRS; char *pszSRS_WKT = NULL; GDALRasterBand *poBand; GByte abyRaster512*512; poDstDS-SetGeoTransform( adfGeoTransform ); oSRS.SetUTM( 11, TRUE ); oSRS.SetWellKnownGeogCS( NAD27 ); oSRS.exportToWkt( &pszSRS_WKT ); poDstDS-SetProjection( pszSRS_WKT ); CPLFree( pszSRS_WKT ); poBand = poDstDS-GetRasterBand(1); poBand-RasterIO( GF_Write, 0, 0, 512, 512, abyRaster, 512, 512, GDT_Byte, 0, 0 ); /* Once were done, close properly the dataset */ GDALClose( (GDALDatasetH) poDstDS );GDAL附带工具GDAL创建了下面的工具程序 gdalinfo- 统计文件的信息。 gdal_translate- 拷贝一个可以控制控制输出格式的栅格文件。 gdaladdo- 为文件添加略缩图。 gdalwarp- 把一个图像转换到一个新的坐标系统。 |gdalindex - 为MapServer建立一个栅格索引。 |gdal_contour - 给DEM创建等高线。 |rgb2pct.py - 把一个24位的图像转化成8位调色板图像。 |pct2rgb.py - 把一个8位调色板图像转化成24位位图。 |gdal_merge.py - 把一系列的图像创建一个快速的地图集。 |gdal_rasterize - 把一个矢量图层栅格化。 |nearblack - 转换临近的黑/白边框为精准数值。 |gdal-config - 获取建立使用gdal的软件需要的参数。创建新的文件存取一个已存在的文件来读取是一件很容易的事情，只要在命令行中指定文件或者数据集的名字。但是，创建一个文件是一件非常复杂的事情。你可能需要指定创建格式，各种创建参数，以及指定一个坐标系统。在不同的GDAL工具中有许多参数都是差不多的，这里列举出来。-offormat 选择要创建新的文件的格式。这个格式被指定为类似GTiff（GeoTIFF格式）或者HFA（ERDAS格式）。所有的格式列表可以用-formats参数列出来。只有格式列表“(rw)”可以被写入。 许多工具如果没有指定，默认是创建GeoTIFF文件。文件扩展名不能用来猜测输出格式，如果没有指定文件名，gdal一般不会添加任何扩展名。-coNAME=VALUE 许多格式会有一个或者更多的创建参数来控制文件创建的细节。比如GeoTIFF可以用创建参数控制压缩，或者控制是否用分片还是分带来进行存储。可以使用的创建参数根据格式驱动不同而不同。而一些简单的格式根本就没有创建参数。虽然某个格式可以用-format 参数列出所有可用的参数列表，但是更详细的信息可以在格式介绍网页中查到。-a_srsSRS 有几个工具(gdal_translate,gdalwarp)可以在命令行中通过类似-a_srs(分配输出SRS)、-s_srs(源SRS)、-t_srs(目标SRS)来指定坐标系统 这些工具允许以一系列格式定义坐标系统（SRS就是空间参考系统）。 NAD27/NAD83/WGS84/WGS72:这些常见的地理坐标系统可以通过名字来直接使用。 EPSG:n坐标系统（投影或者地理坐标）可以通过EPSG码来选择。例如EPSG 27700是英国国家网格。一系列的EPSG坐标系统可以在GDAL数据文件gcs.csv和pcs.csv中找到。 PROJ.4定义：一个PROJ4定义字符串可以用作坐标系统定义。例如“+proj=utm +zone=11 +datum=WGS84”。注意在命令行中要保持Proj4字符串在一起作为一个单独的参数（一般用双引号引起来）。 OpenGIS 知名文本:OpenGIS标准定义了一个文本格式来描述坐标系统作为简单要素规范的一个部分。这个格式是gdal中使用的坐标系统的内部工作格式。包含wkt坐标系统描述的文件的文件名可以被用来作为坐标系统参数，或者坐标系统元素本身也可以被用来作为命令行参数（虽然wkt中释放所有引号是很有争议的）。 ESRI知名文本：ESRI在他们的ArcGIS产品（ArcGIS .prj文件）中使用了一种经过精简OGC WKT的格式，而且这个格式被用在一个和wkt相似的风格的文件中。但是文件名要被加以ESRI:前缀。比如ESRI:NAD 1927 StatePlane Wyoming West FIPS 4904.prj。总的命令行参数所有的GDAL命令行工具程序都支持下面的“总的”命令行参数。-version 登记gdal版本并退出。-formats 列出所有gdal支持的栅格格式（只读和读写的）并退出。