Gdal source code analysis (12) gdal warp API usage instructions

I. Introduction

Address: http://www.gdal.org/warptut.html

The gdal warp API (defined in the file gdalwarper. h) is an efficient interface for image transformation. It mainly consists of gdaltransformerfunc, multiple image sampling methods, and mask operation options. This interface can process large images.

The following example shows how to use the transform API in a program. First, assume that you are familiar with the abstract data model of gdal and the APIs of gdal.

In the program, first initialize a gdalwarpoptions struct object, then use the gdalwarpoptions object to initialize the gdalwarpoperation object, and finally call the gdalwarpoperation: chunkandwarpimage () in the gdalwarpoptions class () function to complete the image transformation.

Ii. Simple Image Re-projection example

First, let's start with an image re-projection example. Note that the output result file already exists and the error information is not checked here, only the most normal process is demonstrated.

# Include "gdalwarper. H "int main () {gdaldataseth hsrcds, hdstds; // open the input/output image gdalallregister (); hsrcds = gdalopen (" in. TIF ", ga_readonly); hdstds = gdalopen (" out. TIF ", ga_update); // set the conversion options gdalwarpoptions * pswarpoptions = conditions (); pswarpoptions-> hsrcds = hsrcds; pswarpoptions-> hdstds = hdstds; pswarpoptions-> nbandcount = 1; pswarpoptions-> pansrcbands = (int *) cplmalloc (sizeof (INT) * pswarpoptions-> nbandcount); pswarpoptions-> pansrcbands [0] = 1; duration-> pandstbands = (int *) cplmalloc (sizeof (INT) * pswarpoptions-> nbandcount); pswarpoptions-> pandstbands [0] = 1; pswarpoptions-> pfnprogress = progress; // create the re-projection transform function pswarpoptions-> ptransformerarg = transform (hsrcds, gdalgetprojectionref (hsrcds), hdstds, gdalgetprojectionref (hdstds), false, 0.0, 1 ); pswarpoptions-> pfntransformer = gdalgenimgprojtransform; // initialize and execute the Transformation Operation gdalwarpoperationooperation; ooperation. initialize (pswarpoptions); ooperation. values (0, 0, values (hdstds), gdalgetrasterysize (hdstds); values (pswarpoptions-> ptransformerarg); values (pswarpoptions); gdalclose (hdstds); gdalclose (hsrcds ); return 0 ;}

In this example, the existing input and output files (in. tif and out. tif) are first opened ). Use the gdalcreatewarpoptions () function to create a gdalwarpoptions struct object (the parameters in the struct will specify a reasonable default value), and then set the handle of the input and output file (that is, the file pointer) for this struct object) and the band to be processed. Note that the pansrcbands and pandstbands arrays need to be dynamically applied outside, and will be automatically released when the gdaldestroywarpoptions () function is called, therefore, we do not need to release these two arrays. Gdaltermprogress is a simple console progress information function, used to display the processing progress.

The gdalcreategenimgprojtransformer () function is used to create a projection transformation parameter from the original image to the result image. We assume that both images have a suitable four-to-four range and coordinate system without using GCP points.

Once the gdalwarpoptions struct is created, you can use this gdalwarpoptions object to initialize a gdalwarpoperation object, and then call the gdalwarpoperation: chunkandwarpimage () function for conversion. After the conversion is complete, the conversion options and datasets must be released.

Generally, a series of checks should be performed after the image is opened. Then, when the projection transformation parameter is set up, the returned parameters should be checked (if the returned value is null, it indicates a failure ), finally, check the created transformation operation. The above example does not check the information for convenience. We need to check the information in our own program.

Iii. Other conversion options

The gdalwarpoptions struct contains many parameters to set the transform. The following describes some important examples:

1. gdalwarpoptions: dfwarpmemorylimit: sets the maximum memory used by gdalwarpoperation to process images. The Unit is bits. The default value is relatively conservative (relatively small). You can adjust this value based on your memory size. Adding this value can improve the program running efficiency, but pay attention to the memory size. This size, gdal cache size, and the memory required by your application and system must be smaller than the system memory. Otherwise, errors may occur. Generally, for example, for a system with a memory of MB, it is reasonable to set this value to at least 64 MB. Note that this value does not include the memory used by gdal to read data.

2. gdalwarpopations: eresamplealg: re-sampling method. Available values include gra_nearestneighbour (nearest sampling, default value, fastest processing speed), gra_bilinear (2x2 bilinear interpolation sampling) and gra_cubic (cubic convolution sampling ). Gra_nearestneighbour sampling method is generally used in thematic or color images. Other sampling methods have better results, especially in algorithms that change the image resolution during computing.

3. gdalwarpoptions: padfsrcnodatareal: This array (one value for each band) can be used to specify the nodata value of the input image band, which is the background value of the image. For such values, the algorithm will not participate in the operation, copy the value directly to the result image.

4. gdalwarpoptions: papszwarpoptions: This is a string list used to set some options in the image conversion process. The format is name = value. For more details, see the gdalwarpoptions: papszwarpoptions document, which contains all the options. Supported values include:

• Init_dest = [value] Or init_dest = no_data: This option is used to forcibly set the initial value of the result image (all bands). The initial value is the specified value or nodata value. The nodata value is obtained from the padfdstnodatareal parameter or the padfdstnodataimag parameter. If this value is not set, it will be overwritten by the nodata value of the original image.
• Write_flush = yes/no: This option is used to force data to be written to the disk after each partition is processed. In some cases, this option can write result data more securely, but it also adds more disk operations. The default value is no.

4. Create an output file

In the previous example, The result image already exists. Select the range and coordinate system of the prediction output file to create a new image. This operation is not a special API for image transformation, but an API for transformation.

# Include "gdalwarper. H "# include" ogr_spatialref.h "... gdaldriverh hdriver; gdaldatatype EDT; gdaldataseth hdstds; gdaldataseth hsrcds; // open the source file hsrcds = gdalopen ("in. TIF ", ga_readonly); cplassert (hsrcds! = NULL); // the Data Type of the output image is the same as that of the first input image band. EDT = gdalgetrasterdatatype (gdalgetrasterband (hsrcds, 1 )); // get the output image Driver (geotiff format) hdriver = gdalgetdriverbyname ("gtiff"); cplassert (hdriver! = NULL); // obtain the coordinate system const char * pszsrcwkt, * pszdstwkt = NULL; pszsrcwkt = gdalgetprojectionref (hsrcds); cplassert (pszsrcwkt! = NULL & strlen (pszsrcwkt)> 0); // set the coordinate system of the output image to UTM 11 WGS84 ogrspatialreference osrs; osrs. setutm (11, true); osrs. setwellknowngeogcs ("WGS84"); osrs. exporttowkt (& pszdstwkt); // create a transformation parameter to handle the coordinate from the row and column of the source image to the geographical coordinate (no // result row and column) of the result image. The initial value is set to null. Void * htransformarg; htransformarg = gdalcreategenimgprojtransformer (hsrcds, pszsrcwkt, null, pszdstwkt, false, 0, 1); cplassert (htransformarg! = NULL); // obtain the approximate geographic range and resolution of the output file. Double adfdstgeotransform [6]; int npixels = 0, nlines = 0; cplerr eerr; eerr = gdalsuggestedwarpoutput (hsrcds, outputs, htransformarg, adfdstgeotransform, & npixels, & nlines); cplassert (eerr = ce_none); loads (htransformarg); // create the output file hdstds = gdalcreate (hdriver, "out. TIF ", npixels, nlines, gdalgetrastercount (hsrcds), EDT, nu Ll); cplassert (hdstds! = NULL); // write projection gdalsetprojection (hdstds, pszdstwkt); gdalsetgeotransform (hdstds, adfdstgeotransform); // copy the color table, if any, gdalcolortableh HCT; HCT = gdalgetrastercolortable (gdalgetrasterband (hsrcds, 1); If (Hct! = NULL) gdalsetrastercolortable (gdalgetrasterband (hdstds, 1), HCT...

Note The following logical relationships:

• The output coordinates we need to create are represented by geographical coordinates, rather than the column and column numbers. At the same time, the output coordinates are the coordinates under the result coordinate system, not the original coordinate system.
• Gdalsuggestedwarpoutput () function return value: adfdstgeotransform, npixels
  And nlines are the size and four-to-range of the output image, which contains all the pixels of the source image. The resolution in the image is estimated based on the original image. The resolution of the output image is consistent between the horizontal and vertical, and is not restricted by the input image.
• Changes require that the output file format be "random. Generally, the CREATE () (createcopy () function cannot be used) function is used to create a non-compressed image format. If you want to create a compressed image format or use the createcopy () function to create a temporary file, the system will create a temporary file and then use the createcopy () function to write it to the result image.
• The transform API only processes the image metadata. All the color tables, geographic references, and other metadata information must be set to the result image by the program. This information is not set for conversion.

V. Performance Optimization

The following points can improve the processing efficiency when using the transform API.

1. Increase the memory used by the conversion API to make the program run faster. This parameter is called gdalwarpoptions: dfwarpmemorylimit. Theoretically, the larger the block, the higher the I/O efficiency of the data, and the higher the transformation efficiency. However, the memory and gdal cache required for the conversion should be smaller than the machine memory, which is about 2/3 of the memory at most.
2. Add gdal cache. This is especially useful for processing very large input images. If the data of all input and output images is frequently read, the operation efficiency is greatly reduced. Use the gdalsetcachemax () function to set the maximum cache used by gdal.
3. Use an approximate transformation instead of an exact Transformation (the exact transformation is calculated once every pixel ). The following code describes how to use the approximate transformation. The approximate transformation requires specifying a transformation error dferrorthreshold, which is measured in the number of pixels of the output image.

4. hTransformArg =    GDALCreateApproxTransformer(GDALGenImgProjTransform,hGenImgProjArg, dfErrorThreshold );pfnTransformer = GDALApproxTransform;

5. When an empty output file is written, the init_dest option is used in the gdalwarpoptions: papszwarpoptions object for setting. This greatly reduces the disk I/O operations.
6. The input and output files use the block storage file format. The block file format allows you to quickly access a piece of data. Compared with the block file format, it takes more time for an I/O operation to store the file format with a large amount of data.
7. Process all bands in one call. Processing all bands at a time is more secure than processing one band at a time.
8. Use the gdalwarpoperation: chunkandwarpmulti () method to replace the gdalwarpoperation: chunkandwarpimage () method. Multiple independent threads are used to perform Io operations and transform image processing, which improves the CPU and IO efficiency. To execute this operation, gdal requires multi-thread support (since gdal1.8.0, It is supported on Win32 and UNIX platforms by default. For previous versions, you must modify the configuration ).
9. The method of re-sampling, the fastest execution speed of the nearest pixel, the second in bilinear interpolation, and the slowest in three cubes. Do not use a function based on complex sampling.
10. Avoid using complex mask options. For example, the 8bit data with no mask is much more efficient than normal sampling.

6. About mask options

Gdalwarpoptions includes some capabilities for processing complex masks, such as the validity of masks and the masks for input and output data. These features have not been tested. Take caution when using the valid mask for each other band.