Warper C++ API
Include file
gdalwarper.h
Warper C++ API
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.
Defines
-
WARP_EXTRA_ELTS
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.
Typedefs
-
typedef void *GDALWarpOperationH
Opaque type representing a GDALWarpOperation object.
Enums
-
enum GDALResampleAlg
Warp Resampling Algorithm
Values:
-
enumerator GRA_NearestNeighbour
Nearest neighbour (select on one input pixel)
-
enumerator GRA_Bilinear
Bilinear (2x2 kernel)
-
enumerator GRA_Cubic
Cubic Convolution Approximation (4x4 kernel)
-
enumerator GRA_CubicSpline
Cubic B-Spline Approximation (4x4 kernel)
-
enumerator GRA_Lanczos
Lanczos windowed sinc interpolation (6x6 kernel)
-
enumerator GRA_Average
Average (computes the weighted average of all non-NODATA contributing pixels)
-
enumerator GRA_Mode
Mode (selects the value which appears most often of all the sampled points)
-
enumerator GRA_Max
Max (selects maximum of all non-NODATA contributing pixels)
-
enumerator GRA_Min
Min (selects minimum of all non-NODATA contributing pixels)
-
enumerator GRA_Med
Med (selects median of all non-NODATA contributing pixels)
-
enumerator GRA_Q1
Q1 (selects first quartile of all non-NODATA contributing pixels)
-
enumerator GRA_Q3
Q3 (selects third quartile of all non-NODATA contributing pixels)
-
enumerator GRA_Sum
Sum (weighed sum of all non-NODATA contributing pixels). Added in GDAL 3.1
-
enumerator GRA_RMS
RMS (weighted root mean square (quadratic mean) of all non-NODATA contributing pixels)
-
enumerator GRA_NearestNeighbour
-
enum GWKAverageOrModeAlg
GWKAverageOrMode Algorithm
Values:
-
enumerator GWKAOM_Average
Average
-
enumerator GWKAOM_Fmode
Mode
-
enumerator GWKAOM_Imode
Mode of GDT_Byte, GDT_UInt16, or GDT_Int16
-
enumerator GWKAOM_Max
Maximum
-
enumerator GWKAOM_Min
Minimum
-
enumerator GWKAOM_Quant
Quantile
-
enumerator GWKAOM_Sum
Sum
-
enumerator GWKAOM_RMS
RMS
-
enumerator GWKAOM_Average
Functions
-
GDALWarpOptions *GDALCreateWarpOptions(void)
Create a warp options structure.
Must be deallocated with GDALDestroyWarpOptions()
-
void GDALDestroyWarpOptions(GDALWarpOptions*)
Destroy a warp options structure.
-
GDALWarpOptions *GDALCloneWarpOptions(const GDALWarpOptions*)
Clone a warp options structure.
Must be deallocated with GDALDestroyWarpOptions()
-
void GDALWarpInitDstNoDataReal(GDALWarpOptions*, double dNoDataReal)
Initialize padfDstNoDataReal with specified value.
- Parameters:
psOptionsIn -- options to initialize.
dNoDataReal -- value to initialize to.
-
void GDALWarpInitSrcNoDataReal(GDALWarpOptions*, double dNoDataReal)
Initialize padfSrcNoDataReal with specified value.
- Parameters:
psOptionsIn -- options to initialize.
dNoDataReal -- value to initialize to.
-
void GDALWarpInitNoDataReal(GDALWarpOptions*, double dNoDataReal)
Initialize padfSrcNoDataReal and padfDstNoDataReal with specified value.
- Parameters:
psOptionsIn -- options to initialize.
dNoDataReal -- value to initialize to.
-
void GDALWarpInitDstNoDataImag(GDALWarpOptions*, double dNoDataImag)
Initialize padfDstNoDataImag with specified value.
- Parameters:
psOptionsIn -- options to initialize.
dNoDataImag -- value to initialize to.
-
void GDALWarpInitSrcNoDataImag(GDALWarpOptions*, double dNoDataImag)
Initialize padfSrcNoDataImag with specified value.
- Parameters:
psOptionsIn -- options to initialize.
dNoDataImag -- value to initialize to.
-
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.
- Parameters:
psOptions -- options to initialize.
-
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.
- Parameters:
psOptionsIn -- options to initialize.
nBandCount -- bands to initialize for.
-
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().
See also
- 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.
-
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.
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.
-
GDALDatasetH GDALAutoCreateWarpedVRTEx(GDALDatasetH hSrcDS, const char *pszSrcWKT, const char *pszDstWKT, GDALResampleAlg eResampleAlg, double dfMaxError, const GDALWarpOptions *psOptions, 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
-
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.
-
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.
-
GDALWarpOperationH GDALCreateWarpOperation(const GDALWarpOptions*)
See also
-
void GDALDestroyWarpOperation(GDALWarpOperationH)
See also
GDALWarpOperation::~GDALWarpOperation()
-
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)
See also
-
CPLErr GDALWarpRegionToBuffer(GDALWarpOperationH, int, int, int, int, void*, GDALDataType, int, int, int, int)
-
struct GDALWarpOptions
- #include <gdalwarper.h>
Warp control options for use with GDALWarpOperation::Initialize()
Public Members
-
char **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 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 at this time 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. Starting with GDAL 2.4, 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: (GDAL >= 2.0) 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: (GDAL >= 2.0). 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: (GDAL >= 2.2). 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: (GDAL >= 2.2). 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.
-
double dfWarpMemoryLimit
In bytes, 0.0 for internal default
-
GDALResampleAlg eResampleAlg
Resampling algorithm to use
-
GDALDataType eWorkingDataType
data type to use during warp operation, GDT_Unknown lets the algorithm select the type
-
GDALDatasetH hSrcDS
Source image dataset.
-
GDALDatasetH hDstDS
Destination image dataset - may be NULL if only using GDALWarpOperation::WarpRegionToBuffer().
-
int nBandCount
Number of bands to process, may be 0 to select all bands.
-
int *panSrcBands
The band numbers for the source bands to process (1 based)
-
int *panDstBands
The band numbers for the destination bands to process (1 based)
-
int nSrcAlphaBand
The source band so use as an alpha (transparency) value, 0=disabled
-
int nDstAlphaBand
The dest. band so use as an alpha (transparency) value, 0=disabled
-
double *padfSrcNoDataReal
The "nodata" value real component for each input band, if NULL there isn't one
-
double *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.
-
double *padfDstNoDataReal
The "nodata" value real component for each output band, if NULL there isn't one
-
double *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.
-
GDALProgressFunc pfnProgress
GDALProgressFunc() compatible progress reporting function, or NULL if there isn't one.
-
void *pProgressArg
Callback argument to be passed to pfnProgress.
-
GDALTransformerFunc pfnTransformer
Type of spatial point transformer function
-
void *pTransformerArg
Handle to image transformer setup structure
-
GDALMaskFunc *papfnSrcPerBandValidityMaskFunc
Unused.
Must be NULL
-
void **papSrcPerBandValidityMaskFuncArg
Unused.
Must be NULL
-
GDALMaskFunc pfnSrcValidityMaskFunc
Unused.
Must be NULL
-
void *pSrcValidityMaskFuncArg
Unused.
Must be NULL
-
GDALMaskFunc pfnSrcDensityMaskFunc
Unused.
Must be NULL
-
void *pSrcDensityMaskFuncArg
Unused.
Must be NULL
-
GDALMaskFunc pfnDstDensityMaskFunc
Unused.
Must be NULL
-
void *pDstDensityMaskFuncArg
Unused.
Must be NULL
-
GDALMaskFunc pfnDstValidityMaskFunc
Unused.
Must be NULL
-
void *pDstValidityMaskFuncArg
Unused.
Must be NULL
-
void *pPreWarpProcessorArg
Unused.
Must be NULL
-
void *pPostWarpProcessorArg
Unused.
Must be NULL
-
void *hCutline
Optional OGRPolygonH for a masking cutline.
-
double dfCutlineBlendDist
Optional blending distance to apply across cutline in pixels, default is zero.
-
char **papszWarpOptions
-
class GDALWarpKernel
- #include <gdalwarper.h>
This class represents the lowest level of abstraction of warping.
Low level image warping class.
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.
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.
Public Functions
-
GDALWarpKernel()
-
virtual ~GDALWarpKernel()
-
CPLErr 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.
-
CPLErr PerformWarp()
This method performs the warp described in the GDALWarpKernel.
- Returns:
CE_None on success or CE_Failure if an error occurs.
Public Members
-
char **papszWarpOptions
Warp options.
-
GDALResampleAlg 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.
-
GDALDataType 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.
-
int 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.
-
int nSrcXSize
Width of the source image.
Source image width in pixels.
This field is required.
-
int nSrcYSize
Height of the source image.
Source image height in pixels.
This field is required.
-
double dfSrcXExtraSize
Extra pixels (included in nSrcXSize) reserved for filter window.
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.
Should be ignored in scale computation
This field is required.
-
double dfSrcYExtraSize
Extra pixels (included in nSrcYSize) reserved for filter window.
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.
Should be ignored in scale computation
This field is required.
-
GByte **papabySrcImage
Array of nBands source images of size nSrcXSize * nSrcYSize.
Array of source image band data.
Each subarray must have WARP_EXTRA_ELTS at the end
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.
-
GUInt32 **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 = CPLMaskGet(panBandMask, iPixelOffset) }
-
GUInt32 *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.
-
float *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];
-
int nDstXSize
Width of the destination image.
Width of destination image in pixels.
This field is required.
-
int nDstYSize
Height of the destination image.
Height of destination image in pixels.
This field is required.
-
GByte **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.
-
GUInt32 *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.
-
float *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];
-
double dfXScale
X resampling scale, i.e.
nDstXSize / nSrcXSize
-
double dfYScale
Y resampling scale, i.e.
nDstYSize / nSrcYSize
-
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.
X offset to source pixel coordinates for transformation.
See pfnTransformer.
This field is required.
-
int 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.
-
int 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.
-
int 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.
-
GDALTransformerFunc 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 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.
-
void *pTransformerArg
User data provided to pfnTransformer.
Callback data for pfnTransformer.
This field may be NULL if not required for the pfnTransformer being used.
-
GDALProgressFunc 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()).
-
void *pProgress
User data provided to pfnProgress.
Callback data for pfnProgress.
This field may be NULL if not required for the pfnProgress being used.
-
double dfProgressBase
Base/offset value for progress computation.
-
double dfProgressScale
Scale value for progress computation.
-
double *padfDstNoDataReal
Array of nBands value for destination nodata.
-
class GDALWarpOperation
- #include "gdalwarper.h"
High level image warping class.
Warper Design
The overall GDAL high performance image warper is split into a few components.
The transformation between input and output file coordinates is handled via GDALTransformerFunc() implementations such as the one returned by GDALCreateGenImgProjTransformer(). The transformers are ultimately responsible for translating pixel/line locations on the destination image to pixel/line locations on the source image.
In order to handle images too large to hold in RAM, the warper needs to segment large images. This is the responsibility of the GDALWarpOperation class. The GDALWarpOperation::ChunkAndWarpImage() invokes GDALWarpOperation::WarpRegion() on chunks of output and input image that are small enough to hold in the amount of memory allowed by the application. This process is described in greater detail in the Image Chunking section.
The GDALWarpOperation::WarpRegion() function creates and loads an output image buffer, and then calls WarpRegionToBuffer().
GDALWarpOperation::WarpRegionToBuffer() is responsible for loading the source imagery corresponding to a particular output region, and generating masks and density masks from the source and destination imagery using the generator functions found in the GDALWarpOptions structure. Binds this all into an instance of GDALWarpKernel on which the GDALWarpKernel::PerformWarp() method is called.
GDALWarpKernel does the actual image warping, but is given an input image and an output image to operate on. The GDALWarpKernel does no IO, and in fact knows nothing about GDAL. It invokes the transformation function to get sample locations, builds output values based on the resampling algorithm in use. It also takes any validity and density masks into account during this operation.
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.
Public Functions
-
GDALWarpOperation()
-
virtual ~GDALWarpOperation()
-
CPLErr 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:
psNewOptions -- input 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.
-
void *CreateDestinationBuffer(int nDstXSize, int nDstYSize, int *pbWasInitialized = nullptr)
This method creates a destination buffer for use with WarpRegionToBuffer.
The output is initialized based on the INIT_DEST settings.
- Parameters:
nDstXSize -- Width of output window on destination buffer to be produced.
nDstYSize -- Height of output window on destination buffer to be produced.
pbInitialized -- Filled with boolean indicating if the buffer was initialized.
- Returns:
Buffer capable for use as a warp operation output destination
-
void InitializeDestinationBuffer(void *pDstBuffer, int nDstXSize, int nDstYSize, int *pbWasInitialized = nullptr)
This method initializes a destination buffer for use with WarpRegionToBuffer.
It is initialized based on the INIT_DEST settings.
This method is called by CreateDestinationBuffer(). It is meant at being used by callers that have already allocated the destination buffer without using CreateDestinationBuffer().
- Since
3.10
- Parameters:
pDstBuffer -- Buffer of size GDALGetDataTypeSizeBytes(psOptions->eWorkingDataType) * nDstXSize * nDstYSize * psOptions->nBandCount bytes.
nDstXSize -- Width of output window on destination buffer to be produced.
nDstYSize -- Height of output window on destination buffer to be produced.
pbInitialized -- Filled with boolean indicating if the buffer was initialized.
-
const GDALWarpOptions *GetOptions()
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.
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:
nDstXOff -- X offset to window of destination data to be produced.
nDstYOff -- Y offset to window of destination data to be produced.
nDstXSize -- Width of output window on destination file to be produced.
nDstYSize -- Height of output window on destination file to be produced.
- Returns:
CE_None on success or CE_Failure if an error occurs.
-
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.
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:
nDstXOff -- X offset to window of destination data to be produced.
nDstYOff -- Y offset to window of destination data to be produced.
nDstXSize -- Width of output window on destination file to be produced.
nDstYSize -- Height of output window on destination file to be produced.
- Returns:
CE_None on success or CE_Failure if an error occurs.
-
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.
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:
nDstXOff -- X offset to window of destination data to be produced.
nDstYOff -- Y offset to window of destination data to be produced.
nDstXSize -- Width of output window on destination file to be produced.
nDstYSize -- Height of output window on destination file to be produced.
nSrcXOff -- source window X offset (computed if window all zero)
nSrcYOff -- source window Y offset (computed if window all zero)
nSrcXSize -- source window X size (computed if window all zero)
nSrcYSize -- source window Y size (computed if window all zero)
dfProgressBase -- minimum progress value reported
dfProgressScale -- value such as dfProgressBase + dfProgressScale is the maximum progress value reported
- Returns:
CE_None on success or CE_Failure if an error occurs.
-
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.
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:
nDstXOff -- X offset to window of destination data to be produced.
nDstYOff -- Y offset to window of destination data to be produced.
nDstXSize -- Width of output window on destination file to be produced.
nDstYSize -- Height of output window on destination file to be produced.
nSrcXOff -- source window X offset (computed if window all zero)
nSrcYOff -- source window Y offset (computed if window all zero)
nSrcXSize -- source window X size (computed if window all zero)
nSrcYSize -- source window Y size (computed if window all zero)
dfSrcXExtraSize -- Extra pixels (included in nSrcXSize) reserved for filter window. Should be ignored in scale computation
dfSrcYExtraSize -- Extra pixels (included in nSrcYSize) reserved for filter window. Should be ignored in scale computation
dfProgressBase -- minimum progress value reported
dfProgressScale -- value such as dfProgressBase + dfProgressScale is the maximum progress value reported
- Returns:
CE_None on success or CE_Failure if an error occurs.
-
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.
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:
nDstXOff -- X offset to window of destination data to be produced.
nDstYOff -- Y offset to window of destination data to be produced.
nDstXSize -- Width of output window on destination file to be produced.
nDstYSize -- Height of output window on destination file to be produced.
pDataBuf -- the data buffer to place result in, of type eBufDataType.
eBufDataType -- the type of the output data buffer. For now this must match GDALWarpOptions::eWorkingDataType.
nSrcXOff -- source window X offset (computed if window all zero)
nSrcYOff -- source window Y offset (computed if window all zero)
nSrcXSize -- source window X size (computed if window all zero)
nSrcYSize -- source window Y size (computed if window all zero)
dfProgressBase -- minimum progress value reported
dfProgressScale -- value such as dfProgressBase + dfProgressScale is the maximum progress value reported
- Returns:
CE_None on success or CE_Failure if an error occurs.
-
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.
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:
nDstXOff -- X offset to window of destination data to be produced.
nDstYOff -- Y offset to window of destination data to be produced.
nDstXSize -- Width of output window on destination file to be produced.
nDstYSize -- Height of output window on destination file to be produced.
pDataBuf -- the data buffer to place result in, of type eBufDataType.
eBufDataType -- the type of the output data buffer. For now this must match GDALWarpOptions::eWorkingDataType.
nSrcXOff -- source window X offset (computed if window all zero)
nSrcYOff -- source window Y offset (computed if window all zero)
nSrcXSize -- source window X size (computed if window all zero)
nSrcYSize -- source window Y size (computed if window all zero)
dfSrcXExtraSize -- Extra pixels (included in nSrcXSize) reserved for filter window. Should be ignored in scale computation
dfSrcYExtraSize -- Extra pixels (included in nSrcYSize) reserved for filter window. Should be ignored in scale computation
dfProgressBase -- minimum progress value reported
dfProgressScale -- value such as dfProgressBase + dfProgressScale is the maximum progress value reported
- Returns:
CE_None on success or CE_Failure if an error occurs.
Public Static Functions
-
static void DestroyDestinationBuffer(void *pDstBuffer)
This method destroys a buffer previously retrieved from CreateDestinationBuffer.
- Parameters:
pDstBuffer -- destination buffer to be destroyed
Protected 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).
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.
-
double GetWorkingMemoryForWindow(int nSrcXSize, int nSrcYSize, int nDstXSize, int nDstYSize) const
Returns 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.
Private Functions
-
void WipeOptions()
-
int ValidateOptions()
-
bool ComputeSourceWindowTransformPoints(int nDstXOff, int nDstYOff, int nDstXSize, int nDstYSize, bool bUseGrid, bool bAll, int nStepCount, bool bTryWithCheckWithInvertProj, double &dfMinXOut, double &dfMinYOut, double &dfMaxXOut, double &dfMaxYOut, int &nSamplePoints, int &nFailedCount)
-
void ComputeSourceWindowStartingFromSource(int nDstXOff, int nDstYOff, int nDstXSize, int nDstYSize, double *padfSrcMinX, double *padfSrcMinY, double *padfSrcMaxX, double *padfSrcMaxY)
-
void WipeChunkList()
-
void CollectChunkList(int nDstXOff, int nDstYOff, int nDstXSize, int nDstYSize)
-
void ReportTiming(const char*)
Private Members
-
GDALWarpOptions *psOptions
-
int nChunkListCount
-
int nChunkListMax
-
GDALWarpChunk *pasChunkList
-
int bReportTimings
-
unsigned long nLastTimeReported
-
void *psThreadData
-
std::vector<std::pair<double, double>> aDstXYSpecialPoints = {}
-
bool m_bIsTranslationOnPixelBoundaries = false
Private Static Functions
-
static CPLErr CreateKernelMask(GDALWarpKernel*, int iBand, const char *pszType)
Friends
- friend class VRTWarpedDataset