GDAL
Public Member Functions | Static Public Member Functions | Protected Member Functions | Friends | List of all members
GDALWarpOperation Class Reference

High level image warping class. More...

#include "gdalwarper.h"

Public Member Functions

CPLErr Initialize (const GDALWarpOptions *psNewOptions)
 This method initializes the GDALWarpOperation's concept of the warp options in effect. More...
 
void * CreateDestinationBuffer (int nDstXSize, int nDstYSize, int *pbWasInitialized=nullptr)
 This method creates a destination buffer for use with WarpRegionToBuffer. More...
 
const GDALWarpOptionsGetOptions ()
 Return warp options.
 
CPLErr ChunkAndWarpImage (int nDstXOff, int nDstYOff, int nDstXSize, int nDstYSize)
 This method does a complete warp of the source image to the destination image for the indicated region with the current warp options in effect. More...
 
CPLErr ChunkAndWarpMulti (int nDstXOff, int nDstYOff, int nDstXSize, int nDstYSize)
 This method does a complete warp of the source image to the destination image for the indicated region with the current warp options in effect. More...
 
CPLErr WarpRegion (int nDstXOff, int nDstYOff, int nDstXSize, int nDstYSize, int nSrcXOff=0, int nSrcYOff=0, int nSrcXSize=0, int nSrcYSize=0, double dfProgressBase=0.0, double dfProgressScale=1.0)
 This method requests the indicated region of the output file be generated. More...
 
CPLErr WarpRegion (int nDstXOff, int nDstYOff, int nDstXSize, int nDstYSize, int nSrcXOff, int nSrcYOff, int nSrcXSize, int nSrcYSize, double dfSrcXExtraSize, double dfSrcYExtraSize, double dfProgressBase, double dfProgressScale)
 This method requests the indicated region of the output file be generated. More...
 
CPLErr WarpRegionToBuffer (int nDstXOff, int nDstYOff, int nDstXSize, int nDstYSize, void *pDataBuf, GDALDataType eBufDataType, int nSrcXOff=0, int nSrcYOff=0, int nSrcXSize=0, int nSrcYSize=0, double dfProgressBase=0.0, double dfProgressScale=1.0)
 This method requests that a particular window of the output dataset be warped and the result put into the provided data buffer. More...
 
CPLErr WarpRegionToBuffer (int nDstXOff, int nDstYOff, int nDstXSize, int nDstYSize, void *pDataBuf, GDALDataType eBufDataType, int nSrcXOff, int nSrcYOff, int nSrcXSize, int nSrcYSize, double dfSrcXExtraSize, double dfSrcYExtraSize, double dfProgressBase, double dfProgressScale)
 This method requests that a particular window of the output dataset be warped and the result put into the provided data buffer. More...
 

Static Public Member Functions

static void DestroyDestinationBuffer (void *pDstBuffer)
 This method destroys a buffer previously retrieved from CreateDestinationBuffer. More...
 

Protected Member Functions

CPLErr ComputeSourceWindow (int nDstXOff, int nDstYOff, int nDstXSize, int nDstYSize, int *pnSrcXOff, int *pnSrcYOff, int *pnSrcXSize, int *pnSrcYSize, double *pdfSrcXExtraSize, double *pdfSrcYExtraSize, double *pdfSrcFillRatio)
 Given a target window starting at pixel (nDstOff, nDstYOff) and of dimension (nDstXSize, nDstYSize), compute the corresponding window in the source raster, and return the source position in (*pnSrcXOff, *pnSrcYOff), the source dimension in (*pnSrcXSize, *pnSrcYSize). More...
 
double GetWorkingMemoryForWindow (int nSrcXSize, int nSrcYSize, int nDstXSize, int nDstYSize) const
 Retrurns the amount of working memory, in bytes, required to process a warped window of source dimensions nSrcXSize x nSrcYSize and target dimensions nDstXSize x nDstYSize.
 

Friends

class VRTWarpedDataset
 

Detailed Description

High level image warping class.

Warper Design

The overall GDAL high performance image warper is split into a few components.

Chunk Size Selection

The GDALWarpOptions ChunkAndWarpImage() method is responsible for invoking the WarpRegion() method on appropriate sized output chunks such that the memory required for the output image buffer, input image buffer and any required density and validity buffers is less than or equal to the application defined maximum memory available for use.

It checks the memory required by walking the edges of the output region, transforming the locations back into source pixel/line coordinates and establishing a bounding rectangle of source imagery that would be required for the output area. This is actually accomplished by the private GDALWarpOperation::ComputeSourceWindow() method.

Then memory requirements are used by totaling the memory required for all output bands, input bands, validity masks and density masks. If this is greater than the GDALWarpOptions::dfWarpMemoryLimit then the destination region is divided in two (splitting the longest dimension), and ChunkAndWarpImage() recursively invoked on each destination subregion.

Validity and Density Masks Generation

Fill in ways in which the validity and density masks may be generated here. Note that detailed semantics of the masks should be found in GDALWarpKernel.

Member Function Documentation

◆ ChunkAndWarpImage()

CPLErr GDALWarpOperation::ChunkAndWarpImage ( int  nDstXOff,
int  nDstYOff,
int  nDstXSize,
int  nDstYSize 
)

This method does a complete warp of the source image to the destination image for the indicated region with the current warp options in effect.

Progress is reported to the installed progress monitor, if any.

This function will subdivide the region and recursively call itself until the total memory required to process a region chunk will all fit in the memory pool defined by GDALWarpOptions::dfWarpMemoryLimit.

Once an appropriate region is selected GDALWarpOperation::WarpRegion() is invoked to do the actual work.

Parameters
nDstXOffX offset to window of destination data to be produced.
nDstYOffY offset to window of destination data to be produced.
nDstXSizeWidth of output window on destination file to be produced.
nDstYSizeHeight of output window on destination file to be produced.
Returns
CE_None on success or CE_Failure if an error occurs.

◆ ChunkAndWarpMulti()

CPLErr GDALWarpOperation::ChunkAndWarpMulti ( int  nDstXOff,
int  nDstYOff,
int  nDstXSize,
int  nDstYSize 
)

This method does a complete warp of the source image to the destination image for the indicated region with the current warp options in effect.

Progress is reported to the installed progress monitor, if any.

Externally this method operates the same as ChunkAndWarpImage(), but internally this method uses multiple threads to interleave input/output for one region while the processing is being done for another.

Parameters
nDstXOffX offset to window of destination data to be produced.
nDstYOffY offset to window of destination data to be produced.
nDstXSizeWidth of output window on destination file to be produced.
nDstYSizeHeight of output window on destination file to be produced.
Returns
CE_None on success or CE_Failure if an error occurs.

◆ ComputeSourceWindow()

CPLErr GDALWarpOperation::ComputeSourceWindow ( int  nDstXOff,
int  nDstYOff,
int  nDstXSize,
int  nDstYSize,
int *  pnSrcXOff,
int *  pnSrcYOff,
int *  pnSrcXSize,
int *  pnSrcYSize,
double *  pdfSrcXExtraSize,
double *  pdfSrcYExtraSize,
double *  pdfSrcFillRatio 
)
protected

Given a target window starting at pixel (nDstOff, nDstYOff) and of dimension (nDstXSize, nDstYSize), compute the corresponding window in the source raster, and return the source position in (*pnSrcXOff, *pnSrcYOff), the source dimension in (*pnSrcXSize, *pnSrcYSize).

If pdfSrcXExtraSize is not null, its pointed value will be filled with the number of extra source pixels in X dimension to acquire to take into account the size of the resampling kernel. Similarly for pdfSrcYExtraSize for the Y dimension. If pdfSrcFillRatio is not null, its pointed value will be filled with the the ratio of the clamped source raster window size over the unclamped source raster window size. When this ratio is too low, this might be an indication that it might be beneficial to split the target window to avoid requesting too many source pixels.

◆ CreateDestinationBuffer()

void * GDALWarpOperation::CreateDestinationBuffer ( int  nDstXSize,
int  nDstYSize,
int *  pbInitialized = nullptr 
)

This method creates a destination buffer for use with WarpRegionToBuffer.

The output is initialized based on the INIT_DEST settings.

Parameters
nDstXSizeWidth of output window on destination buffer to be produced.
nDstYSizeHeight of output window on destination buffer to be produced.
pbInitializedFilled with boolean indicating if the buffer was initialized.
Returns
Buffer capable for use as a warp operation output destination

◆ DestroyDestinationBuffer()

void GDALWarpOperation::DestroyDestinationBuffer ( void *  pDstBuffer)
static

This method destroys a buffer previously retrieved from CreateDestinationBuffer.

Parameters
pDstBufferdestination buffer to be destroyed

◆ Initialize()

CPLErr GDALWarpOperation::Initialize ( const GDALWarpOptions psNewOptions)

This method initializes the GDALWarpOperation's concept of the warp options in effect.

It creates an internal copy of the GDALWarpOptions structure and defaults a variety of additional fields in the internal copy if not set in the provides warp options.

Defaulting operations include:

  • If the nBandCount is 0, it will be set to the number of bands in the source image (which must match the output image) and the panSrcBands and panDstBands will be populated.
Parameters
psNewOptionsinput set of warp options. These are copied and may be destroyed after this call by the application.
Returns
CE_None on success or CE_Failure if an error occurs.

◆ WarpRegion() [1/2]

CPLErr GDALWarpOperation::WarpRegion ( int  nDstXOff,
int  nDstYOff,
int  nDstXSize,
int  nDstYSize,
int  nSrcXOff,
int  nSrcYOff,
int  nSrcXSize,
int  nSrcYSize,
double  dfSrcXExtraSize,
double  dfSrcYExtraSize,
double  dfProgressBase,
double  dfProgressScale 
)

This method requests the indicated region of the output file be generated.

Note that WarpRegion() will produce the requested area in one low level warp operation without verifying that this does not exceed the stated memory limits for the warp operation. Applications should take care not to call WarpRegion() on too large a region! This function is normally called by ChunkAndWarpImage(), the normal entry point for applications. Use it instead if staying within memory constraints is desired.

Progress is reported from dfProgressBase to dfProgressBase + dfProgressScale for the indicated region.

Parameters
nDstXOffX offset to window of destination data to be produced.
nDstYOffY offset to window of destination data to be produced.
nDstXSizeWidth of output window on destination file to be produced.
nDstYSizeHeight of output window on destination file to be produced.
nSrcXOffsource window X offset (computed if window all zero)
nSrcYOffsource window Y offset (computed if window all zero)
nSrcXSizesource window X size (computed if window all zero)
nSrcYSizesource window Y size (computed if window all zero)
dfSrcXExtraSizeExtra pixels (included in nSrcXSize) reserved for filter window. Should be ignored in scale computation
dfSrcYExtraSizeExtra pixels (included in nSrcYSize) reserved for filter window. Should be ignored in scale computation
dfProgressBaseminimum progress value reported
dfProgressScalevalue such as dfProgressBase + dfProgressScale is the maximum progress value reported
Returns
CE_None on success or CE_Failure if an error occurs.

◆ WarpRegion() [2/2]

CPLErr GDALWarpOperation::WarpRegion ( int  nDstXOff,
int  nDstYOff,
int  nDstXSize,
int  nDstYSize,
int  nSrcXOff = 0,
int  nSrcYOff = 0,
int  nSrcXSize = 0,
int  nSrcYSize = 0,
double  dfProgressBase = 0.0,
double  dfProgressScale = 1.0 
)

This method requests the indicated region of the output file be generated.

Note that WarpRegion() will produce the requested area in one low level warp operation without verifying that this does not exceed the stated memory limits for the warp operation. Applications should take care not to call WarpRegion() on too large a region! This function is normally called by ChunkAndWarpImage(), the normal entry point for applications. Use it instead if staying within memory constraints is desired.

Progress is reported from dfProgressBase to dfProgressBase + dfProgressScale for the indicated region.

Parameters
nDstXOffX offset to window of destination data to be produced.
nDstYOffY offset to window of destination data to be produced.
nDstXSizeWidth of output window on destination file to be produced.
nDstYSizeHeight of output window on destination file to be produced.
nSrcXOffsource window X offset (computed if window all zero)
nSrcYOffsource window Y offset (computed if window all zero)
nSrcXSizesource window X size (computed if window all zero)
nSrcYSizesource window Y size (computed if window all zero)
dfProgressBaseminimum progress value reported
dfProgressScalevalue such as dfProgressBase + dfProgressScale is the maximum progress value reported
Returns
CE_None on success or CE_Failure if an error occurs.

◆ WarpRegionToBuffer() [1/2]

CPLErr GDALWarpOperation::WarpRegionToBuffer ( int  nDstXOff,
int  nDstYOff,
int  nDstXSize,
int  nDstYSize,
void *  pDataBuf,
GDALDataType  eBufDataType,
int  nSrcXOff,
int  nSrcYOff,
int  nSrcXSize,
int  nSrcYSize,
double  dfSrcXExtraSize,
double  dfSrcYExtraSize,
double  dfProgressBase,
double  dfProgressScale 
)

This method requests that a particular window of the output dataset be warped and the result put into the provided data buffer.

The output dataset doesn't even really have to exist to use this method as long as the transformation function in the GDALWarpOptions is setup to map to a virtual pixel/line space.

This method will do the whole region in one chunk, so be wary of the amount of memory that might be used.

Parameters
nDstXOffX offset to window of destination data to be produced.
nDstYOffY offset to window of destination data to be produced.
nDstXSizeWidth of output window on destination file to be produced.
nDstYSizeHeight of output window on destination file to be produced.
pDataBufthe data buffer to place result in, of type eBufDataType.
eBufDataTypethe type of the output data buffer. For now this must match GDALWarpOptions::eWorkingDataType.
nSrcXOffsource window X offset (computed if window all zero)
nSrcYOffsource window Y offset (computed if window all zero)
nSrcXSizesource window X size (computed if window all zero)
nSrcYSizesource window Y size (computed if window all zero)
dfSrcXExtraSizeExtra pixels (included in nSrcXSize) reserved for filter window. Should be ignored in scale computation
dfSrcYExtraSizeExtra pixels (included in nSrcYSize) reserved for filter window. Should be ignored in scale computation
dfProgressBaseminimum progress value reported
dfProgressScalevalue such as dfProgressBase + dfProgressScale is the maximum progress value reported
Returns
CE_None on success or CE_Failure if an error occurs.

◆ WarpRegionToBuffer() [2/2]

CPLErr GDALWarpOperation::WarpRegionToBuffer ( int  nDstXOff,
int  nDstYOff,
int  nDstXSize,
int  nDstYSize,
void *  pDataBuf,
GDALDataType  eBufDataType,
int  nSrcXOff = 0,
int  nSrcYOff = 0,
int  nSrcXSize = 0,
int  nSrcYSize = 0,
double  dfProgressBase = 0.0,
double  dfProgressScale = 1.0 
)

This method requests that a particular window of the output dataset be warped and the result put into the provided data buffer.

The output dataset doesn't even really have to exist to use this method as long as the transformation function in the GDALWarpOptions is setup to map to a virtual pixel/line space.

This method will do the whole region in one chunk, so be wary of the amount of memory that might be used.

Parameters
nDstXOffX offset to window of destination data to be produced.
nDstYOffY offset to window of destination data to be produced.
nDstXSizeWidth of output window on destination file to be produced.
nDstYSizeHeight of output window on destination file to be produced.
pDataBufthe data buffer to place result in, of type eBufDataType.
eBufDataTypethe type of the output data buffer. For now this must match GDALWarpOptions::eWorkingDataType.
nSrcXOffsource window X offset (computed if window all zero)
nSrcYOffsource window Y offset (computed if window all zero)
nSrcXSizesource window X size (computed if window all zero)
nSrcYSizesource window Y size (computed if window all zero)
dfProgressBaseminimum progress value reported
dfProgressScalevalue such as dfProgressBase + dfProgressScale is the maximum progress value reported
Returns
CE_None on success or CE_Failure if an error occurs.

The documentation for this class was generated from the following files: