GDAL_API_Tutorial

GDAL API Tutorial Before 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.h" int 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 不需要确实是物理文件名称（尽管通常都是如此）。 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. 这个解释了驱动的依赖性，它可能是一个URL， 带有加在最后的额外的参数的文件名，控制了打开或是其他行为。 Please try not to limit GDAL file selection dialogs to only selecting physical files. 请不要去限制GDAL文件选择对话框去仅仅选择物理文件。 Getting Dataset Information As 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. 也同样含有元数据，坐标系统，地理参考坐标系转换，栅格大小和多种多样的其他数据。 adfGeoTransform[0] /* top left x */ adfGeoTransform[1] /* w-e pixel resolution */ adfGeoTransform[2] /* rotation, 0 if image is "north up" */ adfGeoTransform[3] /* top left y */ adfGeoTransform[4] /* rotation, 0 if image is "north up" */ adfGeoTransform[5] /* n-s pixel resolution */ If we wanted to print some general information about the dataset we might do the following: 如果我们想要输出一些关于dataset的主要信息，我们可以按以下所说的做： In C++: double adfGeoTransform[6]; printf( "Driver: %s/%s\n", poDataset->GetDriver()->GetDescription(), poDataset->GetDriver()->GetMetadataItem( GDAL_DMD_LONGNAME ) ); printf( "Size is %dx%dx%d\n", poDataset->GetRasterXSize(), poDataset->GetRasterYSize(), poDataset->GetRasterCount() ); if( poDataset->GetProjectionRef() != NULL ) printf( "Projection is `%s'\n", poDataset->GetProjectionRef() ); if( poDataset->GetGeoTransform( adfGeoTransform ) == CE_None ) { printf( "Origin = (%.6f,%.6f)\n", adfGeoTransform[0], adfGeoTransform[3] ); printf( "Pixel Size = (%.6f,%.6f)\n", adfGeoTransform[1], adfGeoTransform[5] ); } Fetching a Raster Band At 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 adfMinMax[2]; poBand = poDataset->GetRasterBand( 1 ); poBand->GetBlockSize( &nBlockXSize, &nBlockYSize ); printf( "Block=%dx%d Type=%s, ColorInterp=%s\n", nBlockXSize, nBlockYSize, GDALGetDataTypeName(poBand->GetRasterDataType()), GDALGetColorInterpretationName( poBand->GetColorInterpretation()) ); adfMinMax[0] = poBand->GetMinimum( &bGotMin ); adfMinMax[1] = poBand->GetMaximum( &bGotMax ); if( ! (bGotMin && bGotMax) ) GDALComputeRasterMinMax((GDALRasterBandH)poBand, TRUE, adfMinMax); printf( "Min=%.3fd, Max=%.3f\n", adfMinMax[0], adfMinMax[1] ); 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 Data There 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 doesn't 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是存储缓冲器，数据被读入或从其中被写。 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. 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 Dataset Please 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++删除操作所销毁。 GDALDataset's 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 Files New 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(). 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 won't 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: In C++: GDALDataset *poSrcDS = (GDALDataset *) GDALOpen( pszSrcFilename, GA_ReadOnly ); GDALDataset *poDstDS; poDstDS = poDriver->CreateCopy( pszDstFilename, poSrcDS, FALSE, NULL, NULL, NULL ); /* Once we're 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. 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 we're 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. 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 adfGeoTransform[6] = { 444720, 30, 0, 3751320, 0, -30 }; OGRSpatialReference oSRS; char *pszSRS_WKT = NULL; GDALRasterBand *poBand; GByte abyRaster[512*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 we're done, close properly the dataset */ GDALClose( (GDALDatasetH) poDstDS );