GDAL

Public Attributes | List of all members
GDALWarpOptions Struct Reference

Warp control options for use with GDALWarpOperation::Initialize()
More...

`#include <gdalwarper.h>`

## Public Attributes
char ** | papszWarpOptions
| A string list of additional options controlling the warp operation in name=value format.
double | dfWarpMemoryLimit
GDALResampleAlg | eResampleAlg
GDALDataType | eWorkingDataType
GDALDatasetH | hSrcDS
GDALDatasetH | hDstDS
int | nBandCount
int * | panSrcBands
int * | panDstBands
int | nSrcAlphaBand
int | nDstAlphaBand
double * | padfSrcNoDataReal
double * | padfSrcNoDataImag
double * | padfDstNoDataReal
double * | padfDstNoDataImag
GDALProgressFunc | pfnProgress
void * | pProgressArg
GDALTransformerFunc | pfnTransformer
void * | pTransformerArg
GDALMaskFunc * | papfnSrcPerBandValidityMaskFunc
| Unused.
void ** | papSrcPerBandValidityMaskFuncArg
| Unused.
GDALMaskFunc | pfnSrcValidityMaskFunc
| Unused.
void * | pSrcValidityMaskFuncArg
| Unused.
GDALMaskFunc | pfnSrcDensityMaskFunc
| Unused.
void * | pSrcDensityMaskFuncArg
| Unused.
GDALMaskFunc | pfnDstDensityMaskFunc
| Unused.
void * | pDstDensityMaskFuncArg
| Unused.
GDALMaskFunc | pfnDstValidityMaskFunc
| Unused.
void * | pDstValidityMaskFuncArg
| Unused.
CPLErr(* | pfnPreWarpChunkProcessor )(void *pKern, void *pArg)
| Unused.
void * | pPreWarpProcessorArg
| Unused.
CPLErr(* | pfnPostWarpChunkProcessor )(void *pKern, void *pArg)
| Unused.
void * | pPostWarpProcessorArg
| Unused.
void * | hCutline
double | dfCutlineBlendDist
GWKTieStrategy | eTieStrategy
| Tie-breaking method.

## Detailed Description

Warp control options for use with GDALWarpOperation::Initialize()

## Member Data Documentation

## ◆ dfCutlineBlendDist

double GDALWarpOptions::dfCutlineBlendDist

Optional blending distance to apply across cutline in pixels, default is zero.

## ◆ dfWarpMemoryLimit

double GDALWarpOptions::dfWarpMemoryLimit

In bytes, 0.0 for internal default

## ◆ eResampleAlg

GDALResampleAlg GDALWarpOptions::eResampleAlg

Resampling algorithm to use

## ◆ eWorkingDataType

GDALDataType GDALWarpOptions::eWorkingDataType

data type to use during warp operation, GDT_Unknown lets the algorithm select the type

## ◆ hCutline

void* GDALWarpOptions::hCutline

Optional OGRPolygonH for a masking cutline.

## ◆ hDstDS

GDALDatasetH GDALWarpOptions::hDstDS

Destination image dataset - may be NULL if only using GDALWarpOperation::WarpRegionToBuffer().

## ◆ hSrcDS

GDALDatasetH GDALWarpOptions::hSrcDS

Source image dataset.

## ◆ nBandCount

int GDALWarpOptions::nBandCount

Number of bands to process, may be 0 to select all bands.

## ◆ nDstAlphaBand

int GDALWarpOptions::nDstAlphaBand

The dest. band so use as an alpha (transparency) value, 0=disabled

## ◆ nSrcAlphaBand

int GDALWarpOptions::nSrcAlphaBand

The source band so use as an alpha (transparency) value, 0=disabled

## ◆ padfDstNoDataImag

double* GDALWarpOptions::padfDstNoDataImag

The "nodata" value imaginary component - may be NULL even if real component is provided. Note that warp operations only use real component for flagging invalid data.

## ◆ padfDstNoDataReal

double* GDALWarpOptions::padfDstNoDataReal

The "nodata" value real component for each output band, if NULL there isn't one

## ◆ padfSrcNoDataImag

double* GDALWarpOptions::padfSrcNoDataImag

The "nodata" value imaginary component - may be NULL even if real component is provided. This value is not used to flag invalid values. Only the real component is used.

## ◆ padfSrcNoDataReal

double* GDALWarpOptions::padfSrcNoDataReal

The "nodata" value real component for each input band, if NULL there isn't one

## ◆ panDstBands

int* GDALWarpOptions::panDstBands

The band numbers for the destination bands to process (1 based)

## ◆ panSrcBands

int* GDALWarpOptions::panSrcBands

The band numbers for the source bands to process (1 based)

## ◆ papfnSrcPerBandValidityMaskFunc

GDALMaskFunc* GDALWarpOptions::papfnSrcPerBandValidityMaskFunc

Unused.

Must be NULL

## ◆ papSrcPerBandValidityMaskFuncArg

void** GDALWarpOptions::papSrcPerBandValidityMaskFuncArg

Unused.

Must be NULL

## ◆ papszWarpOptions

char ** GDALWarpOptions::papszWarpOptions

A string list of additional options controlling the warp operation in name=value format.

A suitable string list can be prepared with CSLSetNameValue().

The available options can also be retrieved programmatically with GDALWarpGetOptionList().

The following values are currently supported:

- INIT_DEST=[value] or INIT_DEST=NO_DATA: This option forces the destination image to be initialized to the indicated value (for all bands) or indicates that it should be initialized to the NO_DATA value in padfDstNoDataReal/padfDstNoDataImag. If this value isn't set the destination image will be read and overlaid.

- WRITE_FLUSH=YES/NO: This option forces a flush to disk of data after each chunk is processed. In some cases this helps ensure a serial writing of the output data otherwise a block of data may be written to disk each time a block of data is read for the input buffer resulting in a lot of extra seeking around the disk, and reduced IO throughput. The default is NO.

- SKIP_NOSOURCE=YES/NO: Skip all processing for chunks for which there is no corresponding input data. This will disable initializing the destination (INIT_DEST) and all other processing, and so should be used carefully. Mostly useful to short circuit a lot of extra work in mosaicing situations. gdalwarp will automatically enable this option when it is assumed to be safe to do so.

- UNIFIED_SRC_NODATA=YES/NO/PARTIAL: This setting determines how to take into account nodata values when there are several input bands.

  - When YES, all bands are considered as nodata if and only if, all bands match the corresponding nodata values. Note: UNIFIED_SRC_NODATA=YES is set by default, when called from gdalwarp / GDALWarp() with an explicit -srcnodata setting.

        Example with nodata values at (1, 2, 3) and target alpha band requested.
        <ul>
        <li>input pixel = (1, 2, 3) ==> output pixel = (0, 0, 0, 0)</li>
        <li>input pixel = (1, 2, 127) ==> output pixel = (1, 2, 127, 255)</li>
        </ul>

  - When NO, nodata masking values is considered independently for each band. A potential target alpha band will always be valid if there are multiple bands.

    Example with nodata values at (1, 2, 3) and target alpha band requested.

    - input pixel = (1, 2, 3) ==> output pixel = (0, 0, 0, 255)
    - input pixel = (1, 2, 127) ==> output pixel = (0, 0, 127, 255)

    Note: NO was the default behavior before GDAL 3.3.2

  - When PARTIAL, or not specified at all (default behavior), nodata masking values is considered independently for each band. But, and this is the difference with NO, if for a given pixel, it evaluates to the nodata value of each band, the target pixel is considered as globally invalid, which impacts the value of a potential target alpha band.

    Note: PARTIAL is new to GDAL 3.3.2 and should not be used with earlier versions. The default behavior of GDAL < 3.3.2 was NO.

    Example with nodata values at (1, 2, 3) and target alpha band requested.

    - input pixel = (1, 2, 3) ==> output pixel = (0, 0, 0, 0)
    - input pixel = (1, 2, 127) ==> output pixel = (0, 0, 127, 255)

- CUTLINE: This may contain the WKT geometry for a cutline. It will be converted into a geometry by GDALWarpOperation::Initialize() and assigned to the GDALWarpOptions hCutline field. The coordinates must be expressed in source pixel/line coordinates. Note: this is different from the assumptions made for the -cutline option of the gdalwarp utility !

- CUTLINE_BLEND_DIST: This may be set with a distance in pixels which will be assigned to the dfCutlineBlendDist field in the GDALWarpOptions.

- CUTLINE_ALL_TOUCHED: This defaults to FALSE, but may be set to TRUE to enable ALL_TOUCHED mode when rasterizing cutline polygons. This is useful to ensure that that all pixels overlapping the cutline polygon will be selected, not just those whose center point falls within the polygon.

- XSCALE: Ratio expressing the resampling factor (number of destination pixels per source pixel) along the target horizontal axis. The scale is used to determine the number of source pixels along the x-axis that are considered by the resampling algorithm. Equals to one for no resampling, below one for downsampling and above one for upsampling. This is automatically computed, for each processing chunk, and may thus vary among them, depending on the shape of output regions vs input regions. Such variations can be undesired in some situations. If the resampling factor can be considered as constant over the warped area, setting a constant value can lead to more reproducible pixel output.

- YSCALE: Same as XSCALE, but along the horizontal axis.

- OPTIMIZE_SIZE: This defaults to FALSE, but may be set to TRUE typically when writing to a compressed dataset (GeoTIFF with COMPRESS creation option set for example) for achieving a smaller file size. This is achieved by writing at once data aligned on full blocks of the target dataset, which avoids partial writes of compressed blocks and lost space when they are rewritten at the end of the file. However sticking to target block size may cause major processing slowdown for some particular reprojections. Starting with GDAL 3.8, OPTIMIZE_SIZE mode is automatically enabled when it is safe to do so. As this parameter influences the shape of warping chunk, and by default the XSCALE and YSCALE parameters are computed per warping chunk, this parameter may influence the pixel output.

- NUM_THREADS: (GDAL >= 1.10) Can be set to a numeric value or ALL_CPUS to set the number of threads to use to parallelize the computation part of the warping. If not set, computation will be done in a single thread.

- STREAMABLE_OUTPUT: This defaults to FALSE, but may be set to TRUE typically when writing to a streamed file. The gdalwarp utility automatically sets this option when writing to /vsistdout/ or a named pipe (on Unix). This option has performance impacts for some reprojections. Note: band interleaved output is not currently supported by the warping algorithm in a streamable compatible way.

- SRC_COORD_PRECISION: Advanced setting. This defaults to 0, to indicate that no rounding of computing source image coordinates corresponding to the target image must be done. If greater than 0 (and typically below 1), this value, expressed in pixel, will be used to round computed source image coordinates. The purpose of this option is to make the results of warping with the approximated transformer more reproducible and not sensitive to changes in warping memory size. To achieve that, SRC_COORD_PRECISION must be at least 10 times greater than the error threshold. The higher the SRC_COORD_PRECISION/error_threshold ratio, the higher the performance will be, since exact reprojections must statistically be done with a frequency of 4*error_threshold/SRC_COORD_PRECISION.

- SRC_ALPHA_MAX: Maximum value for the alpha band of the source dataset. If the value is not set and the alpha band has a NBITS metadata item, it is used to set SRC_ALPHA_MAX = 2^NBITS-1. Otherwise, if the value is not set and the alpha band is of type UInt16 (resp Int16), 65535 (resp 32767) is used. Otherwise, 255 is used.

- DST_ALPHA_MAX: Maximum value for the alpha band of the destination dataset. If the value is not set and the alpha band has a NBITS metadata item, it is used to set DST_ALPHA_MAX = 2^NBITS-1. Otherwise, if the value is not set and the alpha band is of type UInt16 (resp Int16), 65535 (resp 32767) is used. Otherwise, 255 is used.

Normally when computing the source raster data to load to generate a particular output area, the warper samples transforms 21 points along each edge of the destination region back onto the source file, and uses this to compute a bounding window on the source image that is sufficient. Depending on the transformation in effect, the source window may be a bit too small, or even missing large areas. Problem situations are those where the transformation is very non-linear or "inside out". Examples are transforming from WGS84 to Polar Stereographic for areas around the pole, or transformations where some of the image is untransformable. The following options provide some additional control to deal with errors in computing the source window:

- SAMPLE_GRID=YES/NO: Setting this option to YES will force the sampling to include internal points as well as edge points which can be important if the transformation is esoteric inside out, or if large sections of the destination image are not transformable into the source coordinate system.

- SAMPLE_STEPS: Modifies the density of the sampling grid. The default number of steps is 21. Increasing this can increase the computational cost, but improves the accuracy with which the source region is computed. Starting with GDAL 3.7, this can be set to ALL to mean to sample along all edge points of the destination region (if SAMPLE_GRID=NO or not specified), or all points of the destination region if SAMPLE_GRID=YES.

- SOURCE_EXTRA: This is a number of extra pixels added around the source window for a given request, and by default it is 1 to take care of rounding error. Setting this larger will increase the amount of data that needs to be read, but can avoid missing source data.
- APPLY_VERTICAL_SHIFT=YES/NO: Force the use of vertical shift. This option is generally not necessary, except when using an explicit coordinate transformation (COORDINATE_OPERATION), and not specifying an explicit source and target SRS.

- MULT_FACTOR_VERTICAL_SHIFT: Multiplication factor for the vertical shift. Default 1.0

- EXCLUDED_VALUES: (GDAL >= 3.9) Comma-separated tuple of values (thus typically "R,G,B"), that are ignored as contributing source pixels during resampling. The number of values in the tuple must be the same as the number of bands, excluding the alpha band. Several tuples of excluded values may be specified using the "(R1,G1,B2),(R2,G2,B2)" syntax. Only taken into account by Average currently. This concept is a bit similar to nodata/alpha, but the main difference is that pixels matching one of the excluded value tuples are still considered as valid, when determining the target pixel validity/density.

- EXCLUDED_VALUES_PCT_THRESHOLD=[0-100]: (GDAL >= 3.9) Minimum percentage of source pixels that must be set at one of the EXCLUDED_VALUES to cause the excluded value, that is in majority among source pixels, to be used as the target pixel value. Default value is 50 (%). Only taken into account by Average currently.

- NODATA_VALUES_PCT_THRESHOLD=[0-100]: (GDAL >= 3.9) Minimum percentage of source pixels that must be at nodata (or alpha=0 or any other way to express transparent pixel) to cause the target pixel value to not be set. Default value is 100 (%), which means that a target pixel is not set only if all contributing source pixels are not set. Note that NODATA_VALUES_PCT_THRESHOLD is taken into account before EXCLUDED_VALUES_PCT_THRESHOLD. Only taken into account by Average currently.

- MODE_TIES=FIRST/MIN/MAX: (GDAL >= 3.11) Strategy to use when breaking ties with MODE resampling. By default, the first value encountered will be used. Alternatively, the minimum or maximum value can be selected.

## ◆ pDstDensityMaskFuncArg

void* GDALWarpOptions::pDstDensityMaskFuncArg

Unused.

Must be NULL

## ◆ pDstValidityMaskFuncArg

void* GDALWarpOptions::pDstValidityMaskFuncArg

Unused.

Must be NULL

## ◆ pfnDstDensityMaskFunc

GDALMaskFunc GDALWarpOptions::pfnDstDensityMaskFunc

Unused.

Must be NULL

## ◆ pfnDstValidityMaskFunc

GDALMaskFunc GDALWarpOptions::pfnDstValidityMaskFunc

Unused.

Must be NULL

## ◆ pfnPostWarpChunkProcessor

CPLErr(* GDALWarpOptions::pfnPostWarpChunkProcessor) (void *pKern, void *pArg)

Unused.

Must be NULL

## ◆ pfnPreWarpChunkProcessor

CPLErr(* GDALWarpOptions::pfnPreWarpChunkProcessor) (void *pKern, void *pArg)

Unused.

Must be NULL

## ◆ pfnProgress

GDALProgressFunc GDALWarpOptions::pfnProgress

GDALProgressFunc() compatible progress reporting function, or NULL if there isn't one.

## ◆ pfnSrcDensityMaskFunc

GDALMaskFunc GDALWarpOptions::pfnSrcDensityMaskFunc

Unused.

Must be NULL

## ◆ pfnSrcValidityMaskFunc

GDALMaskFunc GDALWarpOptions::pfnSrcValidityMaskFunc

Unused.

Must be NULL

## ◆ pfnTransformer

GDALTransformerFunc GDALWarpOptions::pfnTransformer

Type of spatial point transformer function

## ◆ pPostWarpProcessorArg

void* GDALWarpOptions::pPostWarpProcessorArg

Unused.

Must be NULL

## ◆ pPreWarpProcessorArg

void* GDALWarpOptions::pPreWarpProcessorArg

Unused.

Must be NULL

## ◆ pProgressArg

void* GDALWarpOptions::pProgressArg

Callback argument to be passed to pfnProgress.

## ◆ pSrcDensityMaskFuncArg

void* GDALWarpOptions::pSrcDensityMaskFuncArg

Unused.

Must be NULL

## ◆ pSrcValidityMaskFuncArg

void* GDALWarpOptions::pSrcValidityMaskFuncArg

Unused.

Must be NULL

## ◆ pTransformerArg

void* GDALWarpOptions::pTransformerArg

Handle to image transformer setup structure

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

- gdalwarper.h
- gdalwarper.cpp