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. More...

Typedefs
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	GWKAverageOrModeAlg {   GWKAOM_Average = 1 , GWKAOM_Fmode = 2 , GWKAOM_Imode = 3 , GWKAOM_Max = 4 ,   GWKAOM_Min = 5 , GWKAOM_Quant = 6 , GWKAOM_Sum = 7 , GWKAOM_RMS = 8 }

Functions
GDALWarpOptions *	GDALCreateWarpOptions (void)
	Create a warp options structure. More...
void	GDALDestroyWarpOptions (GDALWarpOptions *)
	Destroy a warp options structure.
GDALWarpOptions *	GDALCloneWarpOptions (const GDALWarpOptions *)
	Clone a warp options structure. More...
void	GDALWarpInitDstNoDataReal (GDALWarpOptions *, double dNoDataReal)
	Initialize padfDstNoDataReal with specified value. More...
void	GDALWarpInitSrcNoDataReal (GDALWarpOptions *, double dNoDataReal)
	Initialize padfSrcNoDataReal with specified value. More...
void	GDALWarpInitNoDataReal (GDALWarpOptions *, double dNoDataReal)
	Initialize padfSrcNoDataReal and padfDstNoDataReal with specified value. More...
void	GDALWarpInitDstNoDataImag (GDALWarpOptions *, double dNoDataImag)
	Initialize padfDstNoDataImag with specified value. More...
void	GDALWarpInitSrcNoDataImag (GDALWarpOptions *, double dNoDataImag)
	Initialize padfSrcNoDataImag with specified value. More...
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. More...
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. More...
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. More...
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. More...
GDALDatasetH	GDALAutoCreateWarpedVRTEx (GDALDatasetH hSrcDS, const char *pszSrcWKT, const char *pszDstWKT, GDALResampleAlg eResampleAlg, double dfMaxError, const GDALWarpOptions *psOptions, CSLConstList papszTransformerOptions)
	Create virtual warped dataset automatically. More...
GDALDatasetH	GDALCreateWarpedVRT (GDALDatasetH hSrcDS, int nPixels, int nLines, double *padfGeoTransform, GDALWarpOptions *psOptions)
	Create virtual warped dataset. More...
CPLErr	GDALInitializeWarpedVRT (GDALDatasetH hDS, GDALWarpOptions *psWO)
	Set warp info on virtual warped dataset. More...
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)

GWKAverageOrModeAlg

enum GWKAverageOrModeAlg

GWKAverageOrMode Algorithm

Enumerator
GWKAOM_Average	Average
GWKAOM_Fmode	Mode
GWKAOM_Imode	Mode of GDT_Byte, GDT_UInt16, or GDT_Int16
GWKAOM_Max	Maximum
GWKAOM_Min	Minimum
GWKAOM_Quant	Quantile
GWKAOM_Sum	Sum
GWKAOM_RMS	RMS

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);

Traditonal 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,
		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);

Traditonal 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.

No metadata, projection info, or color tables are transferred to the output file.

Starting with GDAL 2.0, nodata values set on destination dataset are taken into account.

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.

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.