GDAL

Public Member Functions | Public Attributes | List of all members
GDALWarpKernel Class Reference

This class represents the lowest level of abstraction of warping. More...

`#include <gdalwarper.h>`

## Public Member Functions
CPLErr | Validate ()
CPLErr | PerformWarp ()

## Public Attributes
char ** | papszWarpOptions
| Warp options.
GDALResampleAlg | eResample
| Resample algorithm. More...
GDALDataType | eWorkingDataType
| Working data type. More...
int | nBands
| Number of input and output bands (excluding alpha bands) More...
int | nSrcXSize
| Width of the source image. More...
int | nSrcYSize
| Height of the source image. More...
double | dfSrcXExtraSize
| Extra pixels (included in nSrcXSize) reserved for filter window. More...
double | dfSrcYExtraSize
| Extra pixels (included in nSrcYSize) reserved for filter window. More...
GByte ** | papabySrcImage
| Array of nBands source images of size nSrcXSize * nSrcYSize. More...
GUInt32 ** | papanBandSrcValid
| Array of nBands validity mask of size (nSrcXSize * nSrcYSize + WARP_EXTRA_ELTS) / 8. More...
GUInt32 * | panUnifiedSrcValid
| Unified validity mask of size (nSrcXSize * nSrcYSize + WARP_EXTRA_ELTS) / 8. More...
float * | pafUnifiedSrcDensity
| Unified source density of size nSrcXSize * nSrcYSize + WARP_EXTRA_ELTS. More...
int | nDstXSize
| Width of the destination image. More...
int | nDstYSize
| Height of the destination image. More...
GByte ** | papabyDstImage
| Array of nBands destination images of size nDstXSize * nDstYSize. More...
GUInt32 * | panDstValid
| Validify mask of size (nDstXSize * nDstYSize) / 8. More...
float * | pafDstDensity
| Destination density of size nDstXSize * nDstYSize. More...
double | dfXScale
| X resampling scale, i.e. More...
double | dfYScale
| Y resampling scale, i.e. More...
double | dfXFilter
| X size of filter kernel.
double | dfYFilter
| Y size of filter kernel.
int | nXRadius
| X size of window to filter.
int | nYRadius
| Y size of window to filter.
int | nFiltInitX
| X filtering offset.
int | nFiltInitY
| Y filtering offset.
int | nSrcXOff
| X offset of the source buffer regarding the top-left corner of the image. More...
int | nSrcYOff
| Y offset of the source buffer regarding the top-left corner of the image. More...
int | nDstXOff
| X offset of the destination buffer regarding the top-left corner of the image. More...
int | nDstYOff
| Y offset of the destination buffer regarding the top-left corner of the image. More...
GDALTransformerFunc | pfnTransformer
| Pixel transformation function. More...
void * | pTransformerArg
| User data provided to pfnTransformer. More...
GDALProgressFunc | pfnProgress
| Progress function. More...
void * | pProgress
| User data provided to pfnProgress. More...
double | dfProgressBase
| Base/offset value for progress computation.
double | dfProgressScale
| Scale value for progress computation.
double * | padfDstNoDataReal
| Array of nBands value for destination nodata.

## Detailed Description

This class represents the lowest level of abstraction of warping.

It holds the imagery for one "chunk" of a warp, and the pre-prepared masks. All IO is done before and after its operation. This class is not normally used by the application.

Low level image warping class.

This class is responsible for low level image warping for one "chunk" of imagery. The class is essentially a structure with all data members public - primarily so that new special-case functions can be added without changing the class declaration.

Applications are normally intended to interactive with warping facilities through the GDALWarpOperation class, though the GDALWarpKernel can in theory be used directly if great care is taken in setting up the control data.

### Design Issues

The intention is that PerformWarp() would analyze the setup in terms of the datatype, resampling type, and validity/density mask usage and pick one of many specific implementations of the warping algorithm over a continuum of optimization vs. generality. At one end there will be a reference general purpose implementation of the algorithm that supports any data type (working internally in double precision complex), all three resampling types, and any or all of the validity/density masks. At the other end would be highly optimized algorithms for common cases like nearest neighbour resampling on GDT_Byte data with no masks.

The full set of optimized versions have not been decided but we should expect to have at least:

- One for each resampling algorithm for 8bit data with no masks.
- One for each resampling algorithm for float data with no masks.
- One for each resampling algorithm for float data with any/all masks (essentially the generic case for just float data).
- One for each resampling algorithm for 8bit data with support for input validity masks (per band or per pixel). This handles the common case of nodata masking.
- One for each resampling algorithm for float data with support for input validity masks (per band or per pixel). This handles the common case of nodata masking.

Some of the specializations would operate on all bands in one pass (especially the ones without masking would do this), while others might process each band individually to reduce code complexity.

### Masking Semantics

A detailed explanation of the semantics of the validity and density masks, and their effects on resampling kernels is needed here.

## Member Function Documentation

## ◆ PerformWarp()

CPLErr GDALWarpKernel::PerformWarp | ( |  | ) |

This method performs the warp described in the GDALWarpKernel.

Returns
  CE_None on success or CE_Failure if an error occurs.

## ◆ Validate()

CPLErr GDALWarpKernel::Validate | ( |  | ) |

Check the settings in the GDALWarpKernel, and issue a CPLError() (and return CE_Failure) if the configuration is considered to be invalid for some reason.

This method will also do some standard defaulting such as setting pfnProgress to GDALDummyProgress() if it is NULL.

Returns
  CE_None on success or CE_Failure if an error is detected.

## Member Data Documentation

## ◆ dfSrcXExtraSize

double GDALWarpKernel::dfSrcXExtraSize

Extra pixels (included in nSrcXSize) reserved for filter window.

Should be ignored in scale computation

Number of pixels included in nSrcXSize that are present on the edges of the area of interest to take into account the width of the kernel.

This field is required.

## ◆ dfSrcYExtraSize

double GDALWarpKernel::dfSrcYExtraSize

Extra pixels (included in nSrcYSize) reserved for filter window.

Should be ignored in scale computation

Number of pixels included in nSrcYExtraSize that are present on the edges of the area of interest to take into account the height of the kernel.

This field is required.

## ◆ dfXScale

double GDALWarpKernel::dfXScale

X resampling scale, i.e.

nDstXSize / nSrcXSize

## ◆ dfYScale

double GDALWarpKernel::dfYScale

Y resampling scale, i.e.

nDstYSize / nSrcYSize

## ◆ eResample

GDALResampleAlg GDALWarpKernel::eResample

Resample algorithm.

Resampling algorithm.

The resampling algorithm to use. One of GRA_NearestNeighbour, GRA_Bilinear, GRA_Cubic, GRA_CubicSpline, GRA_Lanczos, GRA_Average, GRA_RMS, GRA_Mode or GRA_Sum.

This field is required. GDT_NearestNeighbour may be used as a default value.

## ◆ eWorkingDataType

GDALDataType GDALWarpKernel::eWorkingDataType

Working data type.

Working pixel data type.

The datatype of pixels in the source image (papabySrcimage) and destination image (papabyDstImage) buffers. Note that operations on some data types (such as GDT_Byte) may be much better optimized than other less common cases.

This field is required. It may not be GDT_Unknown.

## ◆ nBands

int GDALWarpKernel::nBands

Number of input and output bands (excluding alpha bands)

Number of bands.

The number of bands (layers) of imagery being warped. Determines the number of entries in the papabySrcImage, papanBandSrcValid, and papabyDstImage arrays.

This field is required.

## ◆ nDstXOff

int GDALWarpKernel::nDstXOff

X offset of the destination buffer regarding the top-left corner of the image.

X offset to destination pixel coordinates for transformation.

See pfnTransformer.

This field is required.

## ◆ nDstXSize

int GDALWarpKernel::nDstXSize

Width of the destination image.

Width of destination image in pixels.

This field is required.

## ◆ nDstYOff

int GDALWarpKernel::nDstYOff

Y offset of the destination buffer regarding the top-left corner of the image.

Y offset to destination pixel coordinates for transformation.

See pfnTransformer.

This field is required.

## ◆ nDstYSize

int GDALWarpKernel::nDstYSize

Height of the destination image.

Height of destination image in pixels.

This field is required.

## ◆ nSrcXOff

int GDALWarpKernel::nSrcXOff

X offset of the source buffer regarding the top-left corner of the image.

X offset to source pixel coordinates for transformation.

See pfnTransformer.

This field is required.

## ◆ nSrcXSize

int GDALWarpKernel::nSrcXSize

Width of the source image.

Source image width in pixels.

This field is required.

## ◆ nSrcYOff

int GDALWarpKernel::nSrcYOff

Y offset of the source buffer regarding the top-left corner of the image.

Y offset to source pixel coordinates for transformation.

See pfnTransformer.

This field is required.

## ◆ nSrcYSize

int GDALWarpKernel::nSrcYSize

Height of the source image.

Source image height in pixels.

This field is required.

## ◆ pafDstDensity

float * GDALWarpKernel::pafDstDensity

Destination density of size nDstXSize * nDstYSize.

Per pixel density mask for destination pixels.

A single density mask layer that applies to the pixels of all destination bands. It contains values between 0.0 and 1.0.

This pointer may be NULL indicating that all pixels have a density of 1.0.

The density for a pixel may be accessed like this:

float fDensity = 1.0;
int nPixel = 3; // Zero based.
int nLine = 4; // Zero based.
assert( nPixel >= 0 && nPixel < poKern->nDstXSize );
assert( nLine >= 0 && nLine < poKern->nDstYSize );
if( poKern->pafDstDensity != NULL )
fDensity = poKern->pafDstDensity[nPixel + nLine * poKern->nDstXSize];

## ◆ pafUnifiedSrcDensity

float * GDALWarpKernel::pafUnifiedSrcDensity

Unified source density of size nSrcXSize * nSrcYSize + WARP_EXTRA_ELTS.

Per pixel density mask for source pixels.

A single density mask layer that applies to the pixels of all source bands. It contains values between 0.0 and 1.0 indicating the degree to which this pixel should be allowed to contribute to the output result.

This pointer may be NULL indicating that all pixels have a density of 1.0.

The density for a pixel may be accessed like this:

float fDensity = 1.0;
int nPixel = 3; // Zero based.
int nLine = 4; // Zero based.
assert( nPixel >= 0 && nPixel < poKern->nSrcXSize );
assert( nLine >= 0 && nLine < poKern->nSrcYSize );
if( poKern->pafUnifiedSrcDensity != NULL )
fDensity = poKern->pafUnifiedSrcDensity
[nPixel + nLine * poKern->nSrcXSize];

## ◆ panDstValid

GUInt32 * GDALWarpKernel::panDstValid

Validify mask of size (nDstXSize * nDstYSize) / 8.

Per pixel validity mask for destination pixels.

A single validity mask layer that applies to the pixels of all destination bands. It is accessed similarly to papanUnitifiedSrcValid, but based on the size of the destination image.

This pointer may be NULL indicating that all pixels are valid.

## ◆ panUnifiedSrcValid

GUInt32 * GDALWarpKernel::panUnifiedSrcValid

Unified validity mask of size (nSrcXSize * nSrcYSize + WARP_EXTRA_ELTS) / 8.

Per pixel validity mask for source pixels.

A single validity mask layer that applies to the pixels of all source bands. It is accessed similarly to papanBandSrcValid, but without the extra level of band indirection.

This pointer may be NULL indicating that all pixels are valid.

Note that if both panUnifiedSrcValid, and papanBandSrcValid are available, the pixel isn't considered to be valid unless both arrays indicate it is valid.

## ◆ papabyDstImage

GByte ** GDALWarpKernel::papabyDstImage

Array of nBands destination images of size nDstXSize * nDstYSize.

Array of destination image band data.

This is an array of pointers (of size GDALWarpKernel::nBands) pointers to image data. Each individual band of image data is organized as a single block of image data in left to right, then bottom to top order. The actual type of the image data is determined by GDALWarpKernel::eWorkingDataType.

To access the pixel value for the (x=3, y=4) pixel (zero based) of the second band with eWorkingDataType set to GDT_Float32 use code like this:

float dfPixelValue;
int nBand = 2-1; // Band indexes are zero based.
int nPixel = 3; // Zero based.
int nLine = 4; // Zero based.
assert( nPixel >= 0 && nPixel < poKern->nDstXSize );
assert( nLine >= 0 && nLine < poKern->nDstYSize );
assert( nBand >= 0 && nBand < poKern->nBands );
dfPixelValue = ((float *) poKern->papabyDstImage[nBand])
[nPixel + nLine * poKern->nSrcYSize];

This field is required.

## ◆ papabySrcImage

int GDALWarpKernel::papabySrcImage

Array of nBands source images of size nSrcXSize * nSrcYSize.

Each subarray must have WARP_EXTRA_ELTS at the end

Array of source image band data.

This is an array of pointers (of size GDALWarpKernel::nBands) pointers to image data. Each individual band of image data is organized as a single block of image data in left to right, then bottom to top order. The actual type of the image data is determined by GDALWarpKernel::eWorkingDataType.

To access the pixel value for the (x=3, y=4) pixel (zero based) of the second band with eWorkingDataType set to GDT_Float32 use code like this:

float dfPixelValue;
int nBand = 2-1; // Band indexes are zero based.
int nPixel = 3; // Zero based.
int nLine = 4; // Zero based.
assert( nPixel >= 0 && nPixel < poKern->nSrcXSize );
assert( nLine >= 0 && nLine < poKern->nSrcYSize );
assert( nBand >= 0 && nBand < poKern->nBands );
dfPixelValue = ((float *) poKern->papabySrcImage[nBand])
[nPixel + nLine * poKern->nSrcXSize];

This field is required.

## ◆ papanBandSrcValid

GUInt32 ** GDALWarpKernel::papanBandSrcValid

Array of nBands validity mask of size (nSrcXSize * nSrcYSize + WARP_EXTRA_ELTS) / 8.

Per band validity mask for source pixels.

Array of pixel validity mask layers for each source band. Each of the mask layers is the same size (in pixels) as the source image with one bit per pixel. Note that it is legal (and common) for this to be NULL indicating that none of the pixels are invalidated, or for some band validity masks to be NULL in which case all pixels of the band are valid. The following code can be used to test the validity of a particular pixel.

int bIsValid = TRUE;
int nBand = 2-1; // Band indexes are zero based.
int nPixel = 3; // Zero based.
int nLine = 4; // Zero based.
assert( nPixel >= 0 && nPixel < poKern->nSrcXSize );
assert( nLine >= 0 && nLine < poKern->nSrcYSize );
assert( nBand >= 0 && nBand < poKern->nBands );
if( poKern->papanBandSrcValid != NULL
&& poKern->papanBandSrcValid[nBand] != NULL )
{
GUInt32 *panBandMask = poKern->papanBandSrcValid[nBand];
int iPixelOffset = nPixel + nLine * poKern->nSrcXSize;
bIsValid = panBandMask[iPixelOffset>>5]
& (0x01 << (iPixelOffset & 0x1f));
}

## ◆ pfnProgress

GDALProgressFunc GDALWarpKernel::pfnProgress

Progress function.

The function to call to report progress of the algorithm, and to check for a requested termination of the operation. It operates according to GDALProgressFunc() semantics.

Generally speaking the progress function will be invoked for each scanline of the destination buffer that has been processed.

This field may be NULL (internally set to GDALDummyProgress()).

## ◆ pfnTransformer

GDALTransformerFunc GDALWarpKernel::pfnTransformer

Pixel transformation function.

Source/destination location transformer.

The function to call to transform coordinates between source image pixel/line coordinates and destination image pixel/line coordinates. See GDALTransformerFunc() for details of the semantics of this function.

The GDALWarpKern algorithm will only ever use this transformer in "destination to source" mode (bDstToSrc=TRUE), and will always pass partial or complete scanlines of points in the destination image as input. This means, among other things, that it is safe to the the approximating transform GDALApproxTransform() as the transformation function.

Source and destination images may be subsets of a larger overall image. The transformation algorithms will expect and return pixel/line coordinates in terms of this larger image, so coordinates need to be offset by the offsets specified in nSrcXOff, nSrcYOff, nDstXOff, and nDstYOff before passing to pfnTransformer, and after return from it.

The GDALWarpKernel::pfnTransformerArg value will be passed as the callback data to this function when it is called.

This field is required.

## ◆ pProgress

void * GDALWarpKernel::pProgress

User data provided to pfnProgress.

Callback data for pfnProgress.

This field may be NULL if not required for the pfnProgress being used.

## ◆ pTransformerArg

void * GDALWarpKernel::pTransformerArg

User data provided to pfnTransformer.

Callback data for pfnTransformer.

This field may be NULL if not required for the pfnTransformer being used.

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

- gdalwarper.h
- gdalwarpkernel.cpp

GDALWarpKernel::nSrcYSize
int nSrcYSize
Height of the source image.
Definition: gdalwarper.h:355
GDALWarpKernel::nBands
int nBands
Number of input and output bands (excluding alpha bands)
Definition: gdalwarper.h:350
GDALWarpKernel::nDstYSize
int nDstYSize
Height of the destination image.
Definition: gdalwarper.h:373
GDALWarpKernel::nDstXSize
int nDstXSize
Width of the destination image.
Definition: gdalwarper.h:371
GDALWarpKernel::nSrcXSize
int nSrcXSize
Width of the source image.
Definition: gdalwarper.h:353
GUInt32
unsigned int GUInt32
Unsigned int32 type.
Definition: cpl_port.h:195