GDAL

Classes | Macros | Typedefs | Enumerations | Functions
gdalwarper.h File Reference

GDAL warper related entry points and definitions. More...

`#include "gdal_alg.h"`
`#include "cpl_minixml.h"`
`#include "cpl_multiproc.h"`
`#include <vector>`
`#include <utility>`

Go to the source code of this file.

## Classes
struct | GDALWarpOptions
| Warp control options for use with GDALWarpOperation::Initialize() More...
class | GDALWarpKernel
| This class represents the lowest level of abstraction of warping. More...
class | GDALWarpOperation
| High level image warping class. More...

## Macros
#define | WARP_EXTRA_ELTS 1
| This is the number of dummy pixels that must be reserved in source arrays in order to satisfy assumptions made in GWKResample(), and more specifically by GWKGetPixelRow() that always read a even number of pixels.

## Typedefs
using | GDALTransformerArgUniquePtr = std::unique_ptr< void, GDALTransformerUniquePtrReleaser >
| Unique pointer for the argument of a GDALTransformerFunc.
typedef void * | GDALWarpOperationH
| Opaque type representing a GDALWarpOperation object.

## Enumerations
enum | GDALResampleAlg { GRA_NearestNeighbour , GRA_Bilinear = 1 , GRA_Cubic = 2 , GRA_CubicSpline = 3 , GRA_Lanczos = 4 , GRA_Average = 5 , GRA_Mode = 6 , GRA_Max , GRA_Min , GRA_Med , GRA_Q1 = 11 , GRA_Q3 = 12 , GRA_Sum = 13 , GRA_RMS = 14 }
enum | GWKTieStrategy { GWKTS_First = 1 , GWKTS_Min = 2 , GWKTS_Max = 3 }

## Functions
const char * | GDALWarpGetOptionList (void)
| Return a XML string describing options accepted by GDALWarpOptions::papszWarpOptions.
GDALWarpOptions * | GDALCreateWarpOptions (void)
| Create a warp options structure.
void | GDALDestroyWarpOptions (GDALWarpOptions *)
| Destroy a warp options structure.
GDALWarpOptions * | GDALCloneWarpOptions (const GDALWarpOptions *)
| Clone a warp options structure.
void | GDALWarpInitDstNoDataReal (GDALWarpOptions *, double dNoDataReal)
| Initialize padfDstNoDataReal with specified value.
void | GDALWarpInitSrcNoDataReal (GDALWarpOptions *, double dNoDataReal)
| Initialize padfSrcNoDataReal with specified value.
void | GDALWarpInitNoDataReal (GDALWarpOptions *, double dNoDataReal)
| Initialize padfSrcNoDataReal and padfDstNoDataReal with specified value.
void | GDALWarpInitDstNoDataImag (GDALWarpOptions *, double dNoDataImag)
| Initialize padfDstNoDataImag with specified value.
void | GDALWarpInitSrcNoDataImag (GDALWarpOptions *, double dNoDataImag)
| Initialize padfSrcNoDataImag with specified value.
void | GDALWarpResolveWorkingDataType (GDALWarpOptions *)
| If the working data type is unknown, this method will determine a valid working data type to support the data in the src and dest data sets and any noData values.
void | GDALWarpInitDefaultBandMapping (GDALWarpOptions *, int nBandCount)
| Init src and dst band mappings such that Bands[i] = i+1 for nBandCount Does nothing if psOptionsIn->nBandCount is non-zero.
CPLErr | GDALReprojectImage (GDALDatasetH hSrcDS, const char *pszSrcWKT, GDALDatasetH hDstDS, const char *pszDstWKT, GDALResampleAlg eResampleAlg, double dfWarpMemoryLimit, double dfMaxError, GDALProgressFunc pfnProgress, void *pProgressArg, GDALWarpOptions *psOptions)
| Reproject image.
CPLErr | GDALCreateAndReprojectImage (GDALDatasetH hSrcDS, const char *pszSrcWKT, const char *pszDstFilename, const char *pszDstWKT, GDALDriverH hDstDriver, char **papszCreateOptions, GDALResampleAlg eResampleAlg, double dfWarpMemoryLimit, double dfMaxError, GDALProgressFunc pfnProgress, void *pProgressArg, GDALWarpOptions *psOptions)
| Reproject an image and create the target reprojected image.
GDALDatasetH | GDALAutoCreateWarpedVRT (GDALDatasetH hSrcDS, const char *pszSrcWKT, const char *pszDstWKT, GDALResampleAlg eResampleAlg, double dfMaxError, const GDALWarpOptions *psOptions)
| Create virtual warped dataset automatically.
GDALDatasetH | GDALAutoCreateWarpedVRTEx (GDALDatasetH hSrcDS, const char *pszSrcWKT, const char *pszDstWKT, GDALResampleAlg eResampleAlg, double dfMaxError, const GDALWarpOptions *psOptions, CSLConstList papszTransformerOptions)
| Create virtual warped dataset automatically.
GDALDatasetH | GDALCreateWarpedVRT (GDALDatasetH hSrcDS, int nPixels, int nLines, const double *padfGeoTransform, GDALWarpOptions *psOptions)
| Create virtual warped dataset.
CPLErr | GDALInitializeWarpedVRT (GDALDatasetH hDS, GDALWarpOptions *psWO)
| Set warp info on virtual warped dataset.
bool | GDALGetWarpResampleAlg (const char *pszResampling, GDALResampleAlg &eResampleAlg, bool bThrow=false)
| Return a GDALResampleAlg from a string.
GDALWarpOperationH | GDALCreateWarpOperation (const GDALWarpOptions *)
void | GDALDestroyWarpOperation (GDALWarpOperationH)
CPLErr | GDALChunkAndWarpImage (GDALWarpOperationH, int, int, int, int)
CPLErr | GDALChunkAndWarpMulti (GDALWarpOperationH, int, int, int, int)
CPLErr | GDALWarpRegion (GDALWarpOperationH, int, int, int, int, int, int, int, int)
CPLErr | GDALWarpRegionToBuffer (GDALWarpOperationH, int, int, int, int, void *, GDALDataType, int, int, int, int)

## Detailed Description

GDAL warper related entry points and definitions.

Eventually it is expected that this file will be mostly private to the implementation, and the public C entry points will be available in gdal_alg.h.

## Macro Definition Documentation

## ◆ WARP_EXTRA_ELTS

#define WARP_EXTRA_ELTS 1

This is the number of dummy pixels that must be reserved in source arrays in order to satisfy assumptions made in GWKResample(), and more specifically by GWKGetPixelRow() that always read a even number of pixels.

So if we are in the situation to read the last pixel of the source array, we need 1 extra dummy pixel to avoid reading out of bounds.

## Enumeration Type Documentation

## ◆ GDALResampleAlg

enum GDALResampleAlg

Warp Resampling Algorithm

Enumerator
GRA_NearestNeighbour | Nearest neighbour (select on one input pixel)
GRA_Bilinear | Bilinear (2x2 kernel)
GRA_Cubic | Cubic Convolution Approximation (4x4 kernel)
GRA_CubicSpline | Cubic B-Spline Approximation (4x4 kernel)
GRA_Lanczos | Lanczos windowed sinc interpolation (6x6 kernel)
GRA_Average | Average (computes the weighted average of all non-NODATA contributing pixels)
GRA_Mode | Mode (selects the value which appears most often of all the sampled points)
GRA_Max | Max (selects maximum of all non-NODATA contributing pixels)
GRA_Min | Min (selects minimum of all non-NODATA contributing pixels)
GRA_Med | Med (selects median of all non-NODATA contributing pixels)
GRA_Q1 | Q1 (selects first quartile of all non-NODATA contributing pixels)
GRA_Q3 | Q3 (selects third quartile of all non-NODATA contributing pixels)
GRA_Sum | Sum (weighed sum of all non-NODATA contributing pixels). Added in GDAL 3.1
GRA_RMS | RMS (weighted root mean square (quadratic mean) of all non-NODATA contributing pixels)

## ◆ GWKTieStrategy

enum GWKTieStrategy

GWKMode tie-breaking strategy

## Function Documentation

## ◆ GDALAutoCreateWarpedVRT()

GDALDatasetH GDALAutoCreateWarpedVRT | ( | GDALDatasetH | hSrcDS,
|  | const char * | pszSrcWKT,
|  | const char * | pszDstWKT,
|  | GDALResampleAlg | eResampleAlg,
|  | double | dfMaxError,
|  | const GDALWarpOptions * | psOptionsIn
| ) |  |

Create virtual warped dataset automatically.

This function will create a warped virtual file representing the input image warped into the target coordinate system. A GenImgProj transformation is created to accomplish any required GCP/Geotransform warp and reprojection to the target coordinate system. The output virtual dataset will be "northup" in the target coordinate system. The GDALSuggestedWarpOutput() function is used to determine the bounds and resolution of the output virtual file which should be large enough to include all the input image

If you want to create an alpha band if the source dataset has none, set psOptionsIn->nDstAlphaBand = GDALGetRasterCount(hSrcDS) + 1.

Note that the constructed GDALDatasetH will acquire one or more references to the passed in hSrcDS. Reference counting semantics on the source dataset should be honoured. That is, don't just GDALClose() it unless it was opened with GDALOpenShared().

It is possible to "transfer" the ownership of the source dataset to the warped dataset in the following way:

GDALDatasetH src_ds = GDALOpen("source.tif");
GDALDatasetH warped_ds = GDALAutoCreateWarpedVRT( src_ds, ... );
GDALReleaseDataset(src_ds); // src_ds is not "owned" fully by warped_ds.
Do NOT use GDALClose(src_ds) here
...
...
GDALReleaseDataset(warped_ds); // or GDALClose(warped_ds);
GDALClose
CPLErr GDALClose(GDALDatasetH)
Close GDAL dataset.
Definition gdaldataset.cpp:4478
GDALReleaseDataset
int GDALReleaseDataset(GDALDatasetH)
Drop a reference to this object, and destroy if no longer referenced.
Definition gdaldataset.cpp:1836
GDALOpen
GDALDatasetH GDALOpen(const char *pszFilename, GDALAccess eAccess)
Open a raster file as a GDALDataset.
Definition gdaldataset.cpp:3763
GDALDatasetH
void * GDALDatasetH
Opaque type used for the C bindings of the C++ GDALDataset class.
Definition gdal_fwd.h:42
GDALAutoCreateWarpedVRT
GDALDatasetH GDALAutoCreateWarpedVRT(GDALDatasetH hSrcDS, const char *pszSrcWKT, const char *pszDstWKT, GDALResampleAlg eResampleAlg, double dfMaxError, const GDALWarpOptions *psOptions)
Create virtual warped dataset automatically.
Definition vrtwarped.cpp:118

Traditional nested calls are also possible of course:

GDALDatasetH src_ds = GDALOpen("source.tif");
GDALDatasetH warped_ds = GDALAutoCreateWarpedVRT( src_ds, ... );
...
...
GDALReleaseDataset(warped_ds); // or GDALClose(warped_ds);
GDALReleaseDataset(src_ds); // or GDALClose(src_ds);

The returned dataset will have no associated filename for itself. If you want to write the virtual dataset description to a file, use the GDALSetDescription() function (or SetDescription() method) on the dataset to assign a filename before it is closed.

Parameters

  hSrcDS | The source dataset.
  pszSrcWKT | The coordinate system of the source image. If NULL, it will be read from the source image.
  pszDstWKT | The coordinate system to convert to. If NULL no change of coordinate system will take place.
  eResampleAlg | One of GRA_NearestNeighbour, GRA_Bilinear, GRA_Cubic, GRA_CubicSpline, GRA_Lanczos, GRA_Average, GRA_RMS or GRA_Mode. Controls the sampling method used.
  dfMaxError | Maximum error measured in input pixels that is allowed in approximating the transformation (0.0 for exact calculations).
  psOptionsIn | Additional warp options, normally NULL.

Returns
  NULL on failure, or a new virtual dataset handle on success.

## ◆ GDALAutoCreateWarpedVRTEx()

GDALDatasetH GDALAutoCreateWarpedVRTEx | ( | GDALDatasetH | hSrcDS,
|  | const char * | pszSrcWKT,
|  | const char * | pszDstWKT,
|  | GDALResampleAlg | eResampleAlg,
|  | double | dfMaxError,
|  | const GDALWarpOptions * | psOptionsIn,
|  | CSLConstList | papszTransformerOptions
| ) |  |

Create virtual warped dataset automatically.

Compared to GDALAutoCreateWarpedVRT() this function adds one extra argument: options to be passed to GDALCreateGenImgProjTransformer2().

Since
  3.2

## ◆ GDALChunkAndWarpImage()

CPLErr GDALChunkAndWarpImage | ( | GDALWarpOperationH | hOperation,
|  | int | nDstXOff,
|  | int | nDstYOff,
|  | int | nDstXSize,
|  | int | nDstYSize
| ) |  |

See also
  GDALWarpOperation::ChunkAndWarpImage()

## ◆ GDALChunkAndWarpMulti()

CPLErr GDALChunkAndWarpMulti | ( | GDALWarpOperationH | hOperation,
|  | int | nDstXOff,
|  | int | nDstYOff,
|  | int | nDstXSize,
|  | int | nDstYSize
| ) |  |

See also
  GDALWarpOperation::ChunkAndWarpMulti()

## ◆ GDALCloneWarpOptions()

GDALWarpOptions * GDALCloneWarpOptions | ( | const GDALWarpOptions * | psSrcOptions | ) |

Clone a warp options structure.

Must be deallocated with GDALDestroyWarpOptions()

## ◆ GDALCreateWarpedVRT()

GDALDatasetH GDALCreateWarpedVRT | ( | GDALDatasetH | hSrcDS,
|  | int | nPixels,
|  | int | nLines,
|  | const double * | padfGeoTransform,
|  | GDALWarpOptions * | psOptions
| ) |  |

Create virtual warped dataset.

This function will create a warped virtual file representing the input image warped based on a provided transformation. Output bounds and resolution are provided explicitly.

If you want to create an alpha band if the source dataset has none, set psOptions->nDstAlphaBand = GDALGetRasterCount(hSrcDS) + 1.

Note that the constructed GDALDatasetH will acquire one or more references to the passed in hSrcDS. Reference counting semantics on the source dataset should be honoured. That is, don't just GDALClose() it unless it was opened with GDALOpenShared().

It is possible to "transfer" the ownership of the source dataset to the warped dataset in the following way:

GDALDatasetH src_ds = GDALOpen("source.tif");
GDALDatasetH warped_ds = GDALAutoCreateWarpedVRT( src_ds, ... );
GDALReleaseDataset(src_ds); // src_ds is not "owned" fully by warped_ds.
Do NOT use GDALClose(src_ds) here
...
...
GDALReleaseDataset(warped_ds); // or GDALClose(warped_ds);

Traditional nested calls are also possible of course:

GDALDatasetH src_ds = GDALOpen("source.tif");
GDALDatasetH warped_ds = GDALAutoCreateWarpedVRT( src_ds, ... );
...
...
GDALReleaseDataset(warped_ds); // or GDALClose(warped_ds);
GDALReleaseDataset(src_ds); // or GDALClose(src_ds);

The returned dataset will have no associated filename for itself. If you want to write the virtual dataset description to a file, use the GDALSetDescription() function (or SetDescription() method) on the dataset to assign a filename before it is closed.

Parameters

  hSrcDS | The source dataset.
  nPixels | Width of the virtual warped dataset to create
  nLines | Height of the virtual warped dataset to create
  padfGeoTransform | Geotransform matrix of the virtual warped dataset to create
  psOptions | Warp options. Must be different from NULL.

Returns
  NULL on failure, or a new virtual dataset handle on success.

## ◆ GDALCreateWarpOperation()

GDALWarpOperationH GDALCreateWarpOperation | ( | const GDALWarpOptions * | psNewOptions | ) |

See also
  GDALWarpOperation::Initialize()

## ◆ GDALCreateWarpOptions()

GDALWarpOptions * GDALCreateWarpOptions | ( | void |  | ) |

Create a warp options structure.

Must be deallocated with GDALDestroyWarpOptions()

## ◆ GDALDestroyWarpOperation()

void GDALDestroyWarpOperation | ( | GDALWarpOperationH | hOperation | ) |

See also
  GDALWarpOperation::~GDALWarpOperation()

## ◆ GDALInitializeWarpedVRT()

CPLErr GDALInitializeWarpedVRT | ( | GDALDatasetH | hDS,
|  | GDALWarpOptions * | psWO
| ) |  |

Set warp info on virtual warped dataset.

Initializes all the warping information for a virtual warped dataset.

This method is the same as the C++ method VRTWarpedDataset::Initialize().

Parameters

  hDS | dataset previously created with the VRT driver, and a SUBCLASS of "VRTWarpedDataset".
  psWO | the warp options to apply. Note that ownership of the transformation information is taken over by the function though everything else remains the property of the caller.

Returns
  CE_None on success or CE_Failure if an error occurs.

## ◆ GDALReprojectImage()

CPLErr GDALReprojectImage | ( | GDALDatasetH | hSrcDS,
|  | const char * | pszSrcWKT,
|  | GDALDatasetH | hDstDS,
|  | const char * | pszDstWKT,
|  | GDALResampleAlg | eResampleAlg,
|  | double | dfWarpMemoryLimit,
|  | double | dfMaxError,
|  | GDALProgressFunc | pfnProgress,
|  | void * | pProgressArg,
|  | GDALWarpOptions * | psOptions
| ) |  |

Reproject image.

This is a convenience function utilizing the GDALWarpOperation class to reproject an image from a source to a destination. In particular, this function takes care of establishing the transformation function to implement the reprojection, and will default a variety of other warp options.

Nodata values set on destination dataset are taken into account.

No metadata, projection info, or color tables are transferred to the output file. Source overviews are not considered.

For more advanced warping capabilities, consider using GDALWarp().

Parameters

  hSrcDS | the source image file.
  pszSrcWKT | the source projection. If NULL the source projection is read from from hSrcDS.
  hDstDS | the destination image file.
  pszDstWKT | the destination projection. If NULL the destination projection will be read from hDstDS.
  eResampleAlg | the type of resampling to use.
  dfWarpMemoryLimit | the amount of memory (in bytes) that the warp API is allowed to use for caching. This is in addition to the memory already allocated to the GDAL caching (as per GDALSetCacheMax()). May be 0.0 to use default memory settings.
  dfMaxError | maximum error measured in input pixels that is allowed in approximating the transformation (0.0 for exact calculations).
  pfnProgress | a GDALProgressFunc() compatible callback function for reporting progress or NULL.
  pProgressArg | argument to be passed to pfnProgress. May be NULL.
  psOptions | warp options, normally NULL.

Returns
  CE_None on success or CE_Failure if something goes wrong.

See also
  GDALWarp()

## ◆ GDALWarpGetOptionList()

const char * GDALWarpGetOptionList | ( | void |  | ) |

Return a XML string describing options accepted by GDALWarpOptions::papszWarpOptions.

Since
  3.11

## ◆ GDALWarpInitDefaultBandMapping()

void GDALWarpInitDefaultBandMapping | ( | GDALWarpOptions * | psOptionsIn,
|  | int | nBandCount
| ) |  |

Init src and dst band mappings such that Bands[i] = i+1 for nBandCount Does nothing if psOptionsIn->nBandCount is non-zero.

Parameters

  psOptionsIn | options to initialize.
  nBandCount | bands to initialize for.

## ◆ GDALWarpInitDstNoDataImag()

void GDALWarpInitDstNoDataImag | ( | GDALWarpOptions * | psOptionsIn,
|  | double | dNoDataImag
| ) |  |

Initialize padfDstNoDataImag with specified value.

Parameters

  psOptionsIn | options to initialize.
  dNoDataImag | value to initialize to.

## ◆ GDALWarpInitDstNoDataReal()

void GDALWarpInitDstNoDataReal | ( | GDALWarpOptions * | psOptionsIn,
|  | double | dNoDataReal
| ) |  |

Initialize padfDstNoDataReal with specified value.

Parameters

  psOptionsIn | options to initialize.
  dNoDataReal | value to initialize to.

## ◆ GDALWarpInitNoDataReal()

void GDALWarpInitNoDataReal | ( | GDALWarpOptions * | psOptionsIn,
|  | double | dNoDataReal
| ) |  |

Initialize padfSrcNoDataReal and padfDstNoDataReal with specified value.

Parameters

  psOptionsIn | options to initialize.
  dNoDataReal | value to initialize to.

## ◆ GDALWarpInitSrcNoDataImag()

void GDALWarpInitSrcNoDataImag | ( | GDALWarpOptions * | psOptionsIn,
|  | double | dNoDataImag
| ) |  |

Initialize padfSrcNoDataImag with specified value.

Parameters

  psOptionsIn | options to initialize.
  dNoDataImag | value to initialize to.

## ◆ GDALWarpInitSrcNoDataReal()

void GDALWarpInitSrcNoDataReal | ( | GDALWarpOptions * | psOptionsIn,
|  | double | dNoDataReal
| ) |  |

Initialize padfSrcNoDataReal with specified value.

Parameters

  psOptionsIn | options to initialize.
  dNoDataReal | value to initialize to.

## ◆ GDALWarpRegion()

CPLErr GDALWarpRegion | ( | GDALWarpOperationH | hOperation,
|  | int | nDstXOff,
|  | int | nDstYOff,
|  | int | nDstXSize,
|  | int | nDstYSize,
|  | int | nSrcXOff,
|  | int | nSrcYOff,
|  | int | nSrcXSize,
|  | int | nSrcYSize
| ) |  |

See also
  GDALWarpOperation::WarpRegion()

## ◆ GDALWarpRegionToBuffer()

CPLErr GDALWarpRegionToBuffer | ( | GDALWarpOperationH | hOperation,
|  | int | nDstXOff,
|  | int | nDstYOff,
|  | int | nDstXSize,
|  | int | nDstYSize,
|  | void * | pDataBuf,
|  | GDALDataType | eBufDataType,
|  | int | nSrcXOff,
|  | int | nSrcYOff,
|  | int | nSrcXSize,
|  | int | nSrcYSize
| ) |  |

See also
  GDALWarpOperation::WarpRegionToBuffer()

## ◆ GDALWarpResolveWorkingDataType()

void GDALWarpResolveWorkingDataType | ( | GDALWarpOptions * | psOptions | ) |

If the working data type is unknown, this method will determine a valid working data type to support the data in the src and dest data sets and any noData values.

Parameters

  psOptions | options to initialize.