Public (C callable) GDAL algorithm entry points, and definitions. More...

Classes
struct	GDALGridInverseDistanceToAPowerOptions
	Inverse distance to a power method control options. More...

struct	GDALGridInverseDistanceToAPowerNearestNeighborOptions
	Inverse distance to a power, with nearest neighbour search, control options. More...

struct	GDALGridMovingAverageOptions
	Moving average method control options. More...

struct	GDALGridNearestNeighborOptions
	Nearest neighbor method control options. More...

struct	GDALGridDataMetricsOptions
	Data metrics method control options. More...

struct	GDALGridLinearOptions
	Linear method control options. More...

struct	GDALTriFacet
	Triangle fact. More...

struct	GDALTriBarycentricCoefficients
	Triangle barycentric coefficients. More...

struct	GDALTriangulation
	Triangulation structure. More...

Macros
#define	GDAL_SWO_ROUND_UP_SIZE 0x1
	Flag for GDALSuggestedWarpOutput2() to ask to round-up output size.

#define	GDAL_SWO_FORCE_SQUARE_PIXEL 0x2
	Flag for GDALSuggestedWarpOutput2() to ask to force square pixels

Typedefs
typedef int(*	GDALTransformerFunc) (void pTransformerArg, int bDstToSrc, int nPointCount, double x, double y, double z, int *panSuccess)

typedef CPLErr(*	GDALContourWriter) (double dfLevel, int nPoints, double padfX, double padfY, void *)
	Contour writer callback type.

typedef void *	GDALContourGeneratorH
	Contour generator opaque type.

typedef struct GDALGridContext	GDALGridContext
	Grid context opaque type.

Enumerations
enum	GDALViewshedMode { GVM_Diagonal = 1 , GVM_Edge = 2 , GVM_Max = 3 , GVM_Min = 4 }
	Viewshed Modes.

enum	GDALViewshedOutputType { GVOT_NORMAL = 1 , GVOT_MIN_TARGET_HEIGHT_FROM_DEM = 2 , GVOT_MIN_TARGET_HEIGHT_FROM_GROUND = 3 }
	Viewshed output types.

enum	GDALGridAlgorithm { GGA_InverseDistanceToAPower = 1 , GGA_MovingAverage = 2 , GGA_NearestNeighbor = 3 , GGA_MetricMinimum = 4 , GGA_MetricMaximum = 5 , GGA_MetricRange = 6 , GGA_MetricCount = 7 , GGA_MetricAverageDistance = 8 , GGA_MetricAverageDistancePts = 9 , GGA_Linear = 10 , GGA_InverseDistanceToAPowerNearestNeighbor = 11 }
	Gridding Algorithms. More...

Functions
int	GDALComputeMedianCutPCT (GDALRasterBandH hRed, GDALRasterBandH hGreen, GDALRasterBandH hBlue, int(pfnIncludePixel)(int, int, void ), int nColors, GDALColorTableH hColorTable, GDALProgressFunc pfnProgress, void *pProgressArg)
	Compute optimal PCT for RGB image. More...

int	GDALDitherRGB2PCT (GDALRasterBandH hRed, GDALRasterBandH hGreen, GDALRasterBandH hBlue, GDALRasterBandH hTarget, GDALColorTableH hColorTable, GDALProgressFunc pfnProgress, void *pProgressArg)
	24bit to 8bit conversion with dithering. More...

int	GDALChecksumImage (GDALRasterBandH hBand, int nXOff, int nYOff, int nXSize, int nYSize)
	Compute checksum for image region. More...

CPLErr	GDALComputeProximity (GDALRasterBandH hSrcBand, GDALRasterBandH hProximityBand, char *papszOptions, GDALProgressFunc pfnProgress, void pProgressArg)
	Compute the proximity of all pixels in the image to a set of pixels in the source image. More...

CPLErr	GDALFillNodata (GDALRasterBandH hTargetBand, GDALRasterBandH hMaskBand, double dfMaxSearchDist, int bDeprecatedOption, int nSmoothingIterations, char *papszOptions, GDALProgressFunc pfnProgress, void pProgressArg)
	Fill selected raster regions by interpolation from the edges. More...

CPLErr	GDALPolygonize (GDALRasterBandH hSrcBand, GDALRasterBandH hMaskBand, OGRLayerH hOutLayer, int iPixValField, char *papszOptions, GDALProgressFunc pfnProgress, void pProgressArg)
	Create polygon coverage from raster data. More...

CPLErr	GDALFPolygonize (GDALRasterBandH hSrcBand, GDALRasterBandH hMaskBand, OGRLayerH hOutLayer, int iPixValField, char *papszOptions, GDALProgressFunc pfnProgress, void pProgressArg)
	Create polygon coverage from raster data. More...

CPLErr	GDALSieveFilter (GDALRasterBandH hSrcBand, GDALRasterBandH hMaskBand, GDALRasterBandH hDstBand, int nSizeThreshold, int nConnectedness, char *papszOptions, GDALProgressFunc pfnProgress, void pProgressArg)
	Removes small raster polygons. More...

void *	GDALCreateGenImgProjTransformer (GDALDatasetH hSrcDS, const char pszSrcWKT, GDALDatasetH hDstDS, const char pszDstWKT, int bGCPUseOK, double dfGCPErrorThreshold, int nOrder)
	Create image to image transformer. More...

void *	GDALCreateGenImgProjTransformer2 (GDALDatasetH hSrcDS, GDALDatasetH hDstDS, char **papszOptions)
	Create image to image transformer. More...

void *	GDALCreateGenImgProjTransformer3 (const char pszSrcWKT, const double padfSrcGeoTransform, const char pszDstWKT, const double padfDstGeoTransform)
	Create image to image transformer. More...

void *	GDALCreateGenImgProjTransformer4 (OGRSpatialReferenceH hSrcSRS, const double padfSrcGeoTransform, OGRSpatialReferenceH hDstSRS, const double padfDstGeoTransform, const char const papszOptions)
	Create image to image transformer. More...

void	GDALSetGenImgProjTransformerDstGeoTransform (void , const double )
	Set GenImgProj output geotransform. More...

void	GDALDestroyGenImgProjTransformer (void *)
	GenImgProjTransformer deallocator. More...

int	GDALGenImgProjTransform (void pTransformArg, int bDstToSrc, int nPointCount, double x, double y, double z, int *panSuccess)
	Perform general image reprojection transformation. More...

void	GDALSetTransformerDstGeoTransform (void , const double )
	Set ApproxTransformer or GenImgProj output geotransform. More...

void	GDALGetTransformerDstGeoTransform (void , double )
	Get ApproxTransformer or GenImgProj output geotransform. More...

void *	GDALCreateReprojectionTransformer (const char pszSrcWKT, const char pszDstWKT)
	Create reprojection transformer. More...

void *	GDALCreateReprojectionTransformerEx (OGRSpatialReferenceH hSrcSRS, OGRSpatialReferenceH hDstSRS, const char const papszOptions)
	Create reprojection transformer. More...

void	GDALDestroyReprojectionTransformer (void *)
	Destroy reprojection transformation. More...

int	GDALReprojectionTransform (void pTransformArg, int bDstToSrc, int nPointCount, double x, double y, double z, int *panSuccess)
	Perform reprojection transformation. More...

void *	GDALCreateGCPTransformer (int nGCPCount, const GDAL_GCP *pasGCPList, int nReqOrder, int bReversed)
	Create GCP based polynomial transformer. More...

void *	GDALCreateGCPRefineTransformer (int nGCPCount, const GDAL_GCP *pasGCPList, int nReqOrder, int bReversed, double tolerance, int minimumGcps)
	Create GCP based polynomial transformer, with a tolerance threshold to discard GCPs that transform badly.

void	GDALDestroyGCPTransformer (void *pTransformArg)
	Destroy GCP transformer. More...

int	GDALGCPTransform (void pTransformArg, int bDstToSrc, int nPointCount, double x, double y, double z, int *panSuccess)
	Transforms point based on GCP derived polynomial model. More...

void *	GDALCreateTPSTransformer (int nGCPCount, const GDAL_GCP *pasGCPList, int bReversed)
	Create Thin Plate Spline transformer from GCPs. More...

void	GDALDestroyTPSTransformer (void *pTransformArg)
	Destroy TPS transformer. More...

int	GDALTPSTransform (void pTransformArg, int bDstToSrc, int nPointCount, double x, double y, double z, int *panSuccess)
	Transforms point based on GCP derived polynomial model. More...

void *	GDALCreateRPCTransformerV2 (const GDALRPCInfoV2 psRPC, int bReversed, double dfPixErrThreshold, char *papszOptions)
	Create an RPC based transformer. More...

void	GDALDestroyRPCTransformer (void *pTransformArg)
	Destroy RPC tranformer.

int	GDALRPCTransform (void pTransformArg, int bDstToSrc, int nPointCount, double x, double y, double z, int *panSuccess)
	RPC transform.

void *	GDALCreateGeoLocTransformer (GDALDatasetH hBaseDS, char **papszGeolocationInfo, int bReversed)
	Create GeoLocation transformer.

void	GDALDestroyGeoLocTransformer (void *pTransformArg)
	Destroy GeoLocation transformer.

int	GDALGeoLocTransform (void pTransformArg, int bDstToSrc, int nPointCount, double x, double y, double z, int *panSuccess)
	Use GeoLocation transformer.

void *	GDALCreateApproxTransformer (GDALTransformerFunc pfnRawTransformer, void *pRawTransformerArg, double dfMaxError)
	Create an approximating transformer. More...

void	GDALApproxTransformerOwnsSubtransformer (void *pCBData, int bOwnFlag)
	Set bOwnSubtransformer flag.

void	GDALDestroyApproxTransformer (void *pApproxArg)
	Cleanup approximate transformer. More...

int	GDALApproxTransform (void pTransformArg, int bDstToSrc, int nPointCount, double x, double y, double z, int *panSuccess)
	Perform approximate transformation. More...

int	GDALSimpleImageWarp (GDALDatasetH hSrcDS, GDALDatasetH hDstDS, int nBandCount, int panBandList, GDALTransformerFunc pfnTransform, void pTransformArg, GDALProgressFunc pfnProgress, void pProgressArg, char *papszWarpOptions)
	Perform simple image warp. More...

CPLErr	GDALSuggestedWarpOutput (GDALDatasetH hSrcDS, GDALTransformerFunc pfnTransformer, void pTransformArg, double padfGeoTransformOut, int pnPixels, int pnLines)
	Suggest output file size. More...

CPLErr	GDALSuggestedWarpOutput2 (GDALDatasetH hSrcDS, GDALTransformerFunc pfnTransformer, void pTransformArg, double padfGeoTransformOut, int pnPixels, int pnLines, double *padfExtent, int nOptions)
	Suggest output file size. More...

CPLErr	GDALTransformGeolocations (GDALRasterBandH hXBand, GDALRasterBandH hYBand, GDALRasterBandH hZBand, GDALTransformerFunc pfnTransformer, void pTransformArg, GDALProgressFunc pfnProgress, void pProgressArg, char **papszOptions)
	Transform locations held in bands. More...

GDALContourGeneratorH	GDAL_CG_Create (int nWidth, int nHeight, int bNoDataSet, double dfNoDataValue, double dfContourInterval, double dfContourBase, GDALContourWriter pfnWriter, void *pCBData)
	Create contour generator.

CPLErr	GDAL_CG_FeedLine (GDALContourGeneratorH hCG, double *padfScanline)
	Feed a line to the contour generator.

void	GDAL_CG_Destroy (GDALContourGeneratorH hCG)
	Destroy contour generator.

CPLErr	GDALContourGenerate (GDALRasterBandH hBand, double dfContourInterval, double dfContourBase, int nFixedLevelCount, double padfFixedLevels, int bUseNoData, double dfNoDataValue, void hLayer, int iIDField, int iElevField, GDALProgressFunc pfnProgress, void *pProgressArg)
	Create vector contours from raster DEM. More...

CPLErr	GDALContourGenerateEx (GDALRasterBandH hBand, void hLayer, CSLConstList options, GDALProgressFunc pfnProgress, void pProgressArg)
	Create vector contours from raster DEM. More...

GDALDatasetH	GDALViewshedGenerate (GDALRasterBandH hBand, const char pszDriverName, const char pszTargetRasterName, CSLConstList papszCreationOptions, double dfObserverX, double dfObserverY, double dfObserverHeight, double dfTargetHeight, double dfVisibleVal, double dfInvisibleVal, double dfOutOfRangeVal, double dfNoDataVal, double dfCurvCoeff, GDALViewshedMode eMode, double dfMaxDistance, GDALProgressFunc pfnProgress, void *pProgressArg, GDALViewshedOutputType heightMode, CSLConstList papszExtraOptions)
	Create viewshed from raster DEM. More...

bool	GDALIsLineOfSightVisible (const GDALRasterBandH, const int xA, const int yA, const double zA, const int xB, const int yB, const double zB, int pnxTerrainIntersection, int pnyTerrainIntersection, CSLConstList papszOptions)
	Check Line of Sight between two points. More...

CPLErr	GDALRasterizeGeometries (GDALDatasetH hDS, int nBandCount, const int panBandList, int nGeomCount, const OGRGeometryH pahGeometries, GDALTransformerFunc pfnTransformer, void pTransformArg, const double padfGeomBurnValues, CSLConstList papszOptions, GDALProgressFunc pfnProgress, void *pProgressArg)
	Burn geometries into raster. More...

CPLErr	GDALRasterizeGeometriesInt64 (GDALDatasetH hDS, int nBandCount, const int panBandList, int nGeomCount, const OGRGeometryH pahGeometries, GDALTransformerFunc pfnTransformer, void pTransformArg, const int64_t panGeomBurnValues, CSLConstList papszOptions, GDALProgressFunc pfnProgress, void *pProgressArg)
	Burn geometries into raster. More...

CPLErr	GDALRasterizeLayers (GDALDatasetH hDS, int nBandCount, int panBandList, int nLayerCount, OGRLayerH pahLayers, GDALTransformerFunc pfnTransformer, void pTransformArg, double padfLayerBurnValues, char *papszOptions, GDALProgressFunc pfnProgress, void pProgressArg)
	Burn geometries from the specified list of layers into raster. More...

CPLErr	GDALRasterizeLayersBuf (void pData, int nBufXSize, int nBufYSize, GDALDataType eBufType, int nPixelSpace, int nLineSpace, int nLayerCount, OGRLayerH pahLayers, const char pszDstProjection, double padfDstGeoTransform, GDALTransformerFunc pfnTransformer, void pTransformArg, double dfBurnValue, char papszOptions, GDALProgressFunc pfnProgress, void pProgressArg)
	Burn geometries from the specified list of layer into raster. More...

CPLErr	GDALGridCreate (GDALGridAlgorithm, const void , GUInt32, const double , const double , const double , double, double, double, double, GUInt32, GUInt32, GDALDataType, void , GDALProgressFunc, void )
	Create regular grid from the scattered data. More...

GDALGridContext *	GDALGridContextCreate (GDALGridAlgorithm eAlgorithm, const void poOptions, GUInt32 nPoints, const double padfX, const double padfY, const double padfZ, int bCallerWillKeepPointArraysAlive)
	Creates a context to do regular gridding from the scattered data. More...

void	GDALGridContextFree (GDALGridContext *psContext)
	Free a context used created by GDALGridContextCreate() More...

CPLErr	GDALGridContextProcess (GDALGridContext psContext, double dfXMin, double dfXMax, double dfYMin, double dfYMax, GUInt32 nXSize, GUInt32 nYSize, GDALDataType eType, void pData, GDALProgressFunc pfnProgress, void *pProgressArg)
	Do the gridding of a window of a raster. More...

GDAL_GCP *	GDALComputeMatchingPoints (GDALDatasetH hFirstImage, GDALDatasetH hSecondImage, char *papszOptions, int pnGCPCount)
	GDALComputeMatchingPoints. More...

int	GDALHasTriangulation (void)
	Returns if GDAL is built with Delaunay triangulation support. More...

GDALTriangulation *	GDALTriangulationCreateDelaunay (int nPoints, const double padfX, const double padfY)
	Computes a Delaunay triangulation of the passed points. More...

int	GDALTriangulationComputeBarycentricCoefficients (GDALTriangulation psDT, const double padfX, const double *padfY)
	Computes barycentric coefficients for each triangles of the triangulation. More...

int	GDALTriangulationComputeBarycentricCoordinates (const GDALTriangulation psDT, int nFacetIdx, double dfX, double dfY, double pdfL1, double pdfL2, double pdfL3)
	Computes the barycentric coordinates of a point. More...

int	GDALTriangulationFindFacetBruteForce (const GDALTriangulation psDT, double dfX, double dfY, int panOutputFacetIdx)
	Returns the index of the triangle that contains the point by iterating over all triangles. More...

int	GDALTriangulationFindFacetDirected (const GDALTriangulation psDT, int nFacetIdx, double dfX, double dfY, int panOutputFacetIdx)
	Returns the index of the triangle that contains the point by walking in the triangulation. More...

void	GDALTriangulationFree (GDALTriangulation *psDT)
	Free a triangulation. More...

GDALDatasetH	GDALOpenVerticalShiftGrid (const char pszProj4Geoidgrids, int pbError)
	Load proj.4 geoidgrids as GDAL dataset. More...

GDALDatasetH	GDALApplyVerticalShiftGrid (GDALDatasetH hSrcDataset, GDALDatasetH hGridDataset, int bInverse, double dfSrcUnitToMeter, double dfDstUnitToMeter, const char const papszOptions)
	Apply a vertical shift grid to a source (DEM typically) dataset. More...

Detailed Description

Public (C callable) GDAL algorithm entry points, and definitions.

Typedef Documentation

◆ GDALTransformerFunc

typedef int(* GDALTransformerFunc)(void *pTransformerArg, intbDstToSrc, int nPointCount, double *x, double *y, double *z, int *panSuccess)

Generic signature for spatial point transformers.

This function signature is used for a variety of functions that accept passed in functions used to transform point locations between two coordinate spaces.

The GDALCreateGenImgProjTransformer(), GDALCreateReprojectionTransformerEx(), GDALCreateGCPTransformer() and GDALCreateApproxTransformer() functions can be used to prepare argument data for some built-in transformers. As well, applications can implement their own transformers to the following signature.

typedef int
(*GDALTransformerFunc)( void *pTransformerArg,
                        int bDstToSrc, int nPointCount,
                        double *x, double *y, double *z, int *panSuccess );

Parameters

pTransformerArg	application supplied callback data used by the transformer.
bDstToSrc	if TRUE the transformation will be from the destination coordinate space to the source coordinate system, otherwise the transformation will be from the source coordinate system to the destination coordinate system.
nPointCount	number of points in the x, y and z arrays.
x	input X coordinates. Results returned in same array.
y	input Y coordinates. Results returned in same array.
z	input Z coordinates. Results returned in same array.
panSuccess	array of ints in which success (TRUE) or failure (FALSE) flags are returned for the translation of each point.

Returns: TRUE if the overall transformation succeeds (though some individual points may have failed) or FALSE if the overall transformation fails.

Enumeration Type Documentation

◆ GDALGridAlgorithm

enum GDALGridAlgorithm

Gridding Algorithms.

Enumerator
GGA_InverseDistanceToAPower	Inverse distance to a power
GGA_MovingAverage	Moving Average
GGA_NearestNeighbor	Nearest Neighbor
GGA_MetricMinimum	Minimum Value (Data Metric)
GGA_MetricMaximum	Maximum Value (Data Metric)
GGA_MetricRange	Data Range (Data Metric)
GGA_MetricCount	Number of Points (Data Metric)
GGA_MetricAverageDistance	Average Distance (Data Metric)
GGA_MetricAverageDistancePts	Average Distance Between Data Points (Data Metric)
GGA_Linear	Linear interpolation (from Delaunay triangulation. Since GDAL 2.1
GGA_InverseDistanceToAPowerNearestNeighbor	Inverse distance to a power with nearest neighbor search for max points

Function Documentation

◆ GDALApplyVerticalShiftGrid()

GDALDatasetH GDALApplyVerticalShiftGrid	(	GDALDatasetH	hSrcDataset,
		GDALDatasetH	hGridDataset,
		int	bInverse,
		double	dfSrcUnitToMeter,
		double	dfDstUnitToMeter,
		const char const	papszOptions
	)

Apply a vertical shift grid to a source (DEM typically) dataset.

hGridDataset will typically use WGS84 as horizontal datum (but this is not a requirement) and its values are the values to add to go from geoid elevations to WGS84 ellipsoidal heights.

hGridDataset will be on-the-fly reprojected and resampled to the projection and resolution of hSrcDataset, using bilinear resampling by default.

Both hSrcDataset and hGridDataset must be single band datasets, and have a valid geotransform and projection.

On success, a reference will be taken on hSrcDataset and hGridDataset. Reference counting semantics on the source and grid datasets should be honoured. That is, don't just GDALClose() it, unless it was opened with GDALOpenShared(), but rather use GDALReleaseDataset() if wanting to immediately release the reference(s) and make the returned dataset the owner of them.

Valid use cases:

hSrcDataset = GDALOpen(...)
hGridDataset = GDALOpen(...)
hDstDataset = GDALApplyVerticalShiftGrid(hSrcDataset, hGridDataset, ...)
GDALReleaseDataset(hSrcDataset);
GDALReleaseDataset(hGridDataset);
if( hDstDataset )
{
    // Do things with hDstDataset
    GDALClose(hDstDataset) // will close hSrcDataset and hGridDataset
}

Parameters

hSrcDataset	source (DEM) dataset. Must not be NULL.
hGridDataset	vertical grid shift dataset. Must not be NULL.
bInverse	if set to FALSE, hGridDataset values will be added to hSrcDataset. If set to TRUE, they will be subtracted.
dfSrcUnitToMeter	the factor to convert values from hSrcDataset to meters (1.0 if source values are in meter).
dfDstUnitToMeter	the factor to convert shifted values from meter (1.0 if output values must be in meter).
papszOptions	list of options, or NULL. Supported options are: RESAMPLING=NEAREST/BILINEAR/CUBIC. Defaults to BILINEAR. MAX_ERROR=val. Maximum error measured in input pixels that is allowed in approximating the transformation (0.0 for exact calculations). Defaults to 0.125 DATATYPE=Byte/UInt16/Int16/Float32/Float64. Output data type. If not specified will be the same as the one of hSrcDataset. ERROR_ON_MISSING_VERT_SHIFT=YES/NO. Whether a missing/nodata value in hGridDataset should cause I/O requests to fail. Default is NO (in which case 0 will be used) SRC_SRS=srs_def. Override projection on hSrcDataset;

Returns: a new dataset corresponding to hSrcDataset adjusted with hGridDataset, or NULL. If not NULL, it must be closed with GDALClose().

Since: GDAL 2.2

Deprecated:: GDAL 3.4. Will be removed in GDAL 4.0. This function was used by gdalwarp initially, but is no longer needed.

◆ GDALApproxTransform()

int GDALApproxTransform	(	void *	pCBData,
		int	bDstToSrc,
		int	nPoints,
		double *	x,
		double *	y,
		double *	z,
		int *	panSuccess
	)

Perform approximate transformation.

Actually performs the approximate transformation described in GDALCreateApproxTransformer(). This function matches the GDALTransformerFunc() signature. Details of the arguments are described there.

◆ GDALChecksumImage()

int GDALChecksumImage	(	GDALRasterBandH	hBand,
		int	nXOff,
		int	nYOff,
		int	nXSize,
		int	nYSize
	)

Compute checksum for image region.

Computes a 16bit (0-65535) checksum from a region of raster data on a GDAL supported band. Floating point data is converted to 32bit integer so decimal portions of such raster data will not affect the checksum. Real and Imaginary components of complex bands influence the result.

Parameters

hBand	the raster band to read from.
nXOff	pixel offset of window to read.
nYOff	line offset of window to read.
nXSize	pixel size of window to read.
nYSize	line size of window to read.

Returns: Checksum value, or -1 in case of error (starting with GDAL 3.6)

◆ GDALComputeMatchingPoints()

GDAL_GCP * GDALComputeMatchingPoints	(	GDALDatasetH	hFirstImage,
		GDALDatasetH	hSecondImage,
		char **	papszOptions,
		int *	pnGCPCount
	)

GDALComputeMatchingPoints.

TODO document

◆ GDALComputeMedianCutPCT()

int GDALComputeMedianCutPCT	(	GDALRasterBandH	hRed,
		GDALRasterBandH	hGreen,
		GDALRasterBandH	hBlue,
		int()(int, int, void )	pfnIncludePixel,
		int	nColors,
		GDALColorTableH	hColorTable,
		GDALProgressFunc	pfnProgress,
		void *	pProgressArg
	)

Compute optimal PCT for RGB image.

This function implements a median cut algorithm to compute an "optimal" pseudocolor table for representing an input RGB image. This PCT could then be used with GDALDitherRGB2PCT() to convert a 24bit RGB image into an eightbit pseudo-colored image.

This code was based on the tiffmedian.c code from libtiff (www.libtiff.org) which was based on a paper by Paul Heckbert:

*   "Color  Image Quantization for Frame Buffer Display", Paul
*   Heckbert, SIGGRAPH proceedings, 1982, pp. 297-307.
*

The red, green and blue input bands do not necessarily need to come from the same file, but they must be the same width and height. They will be clipped to 8bit during reading, so non-eight bit bands are generally inappropriate.

Parameters

hRed	Red input band.
hGreen	Green input band.
hBlue	Blue input band.
pfnIncludePixel	function used to test which pixels should be included in the analysis. At this time this argument is ignored and all pixels are utilized. This should normally be NULL.
nColors	the desired number of colors to be returned (2-256).
hColorTable	the colors will be returned in this color table object.
pfnProgress	callback for reporting algorithm progress matching the GDALProgressFunc() semantics. May be NULL.
pProgressArg	callback argument passed to pfnProgress.

Returns: returns CE_None on success or CE_Failure if an error occurs.

◆ GDALComputeProximity()

CPLErr GDALComputeProximity	(	GDALRasterBandH	hSrcBand,
		GDALRasterBandH	hProximityBand,
		char **	papszOptions,
		GDALProgressFunc	pfnProgress,
		void *	pProgressArg
	)

Compute the proximity of all pixels in the image to a set of pixels in the source image.

This function attempts to compute the proximity of all pixels in the image to a set of pixels in the source image. The following options are used to define the behavior of the function. By default all non-zero pixels in hSrcBand will be considered the "target", and all proximities will be computed in pixels. Note that target pixels are set to the value corresponding to a distance of zero.

The progress function args may be NULL or a valid progress reporting function such as GDALTermProgress/NULL.

Options:

VALUES=n[,n]*

A list of target pixel values to measure the distance from. If this option is not provided proximity will be computed from non-zero pixel values. Currently pixel values are internally processed as integers.

DISTUNITS=[PIXEL]/GEO

Indicates whether distances will be computed in pixel units or in georeferenced units. The default is pixel units. This also determines the interpretation of MAXDIST.

MAXDIST=n

The maximum distance to search. Proximity distances greater than this value will not be computed. Instead output pixels will be set to a nodata value.

NODATA=n

The NODATA value to use on the output band for pixels that are beyond MAXDIST. If not provided, the hProximityBand will be queried for a nodata value. If one is not found, 65535 will be used.

USE_INPUT_NODATA=YES/NO

If this option is set, the input data set no-data value will be respected. Leaving no data pixels in the input as no data pixels in the proximity output.

FIXED_BUF_VAL=n

If this option is set, all pixels within the MAXDIST threadhold are set to this fixed value instead of to a proximity distance.

◆ GDALContourGenerate()

CPLErr GDALContourGenerate	(	GDALRasterBandH	hBand,
		double	dfContourInterval,
		double	dfContourBase,
		int	nFixedLevelCount,
		double *	padfFixedLevels,
		int	bUseNoData,
		double	dfNoDataValue,
		void *	hLayer,
		int	iIDField,
		int	iElevField,
		GDALProgressFunc	pfnProgress,
		void *	pProgressArg
	)

Create vector contours from raster DEM.

This function is kept for compatibility reason and will call the new variant GDALContourGenerateEx that is more extensible and provide more options.

Details about the algorithm are also given in the documentation of the new GDALContourenerateEx function.

Parameters

hBand	The band to read raster data from. The whole band will be processed.
dfContourInterval	The elevation interval between contours generated.
dfContourBase	The "base" relative to which contour intervals are applied. This is normally zero, but could be different. To generate 10m contours at 5, 15, 25, ... the ContourBase would be 5.
nFixedLevelCount	The number of fixed levels. If this is greater than zero, then fixed levels will be used, and ContourInterval and ContourBase are ignored.
padfFixedLevels	The list of fixed contour levels at which contours should be generated. It will contain FixedLevelCount entries, and may be NULL if fixed levels are disabled (FixedLevelCount = 0).
bUseNoData	If TRUE the dfNoDataValue will be used.
dfNoDataValue	The value to use as a "nodata" value. That is, a pixel value which should be ignored in generating contours as if the value of the pixel were not known.
hLayer	The layer to which new contour vectors will be written. Each contour will have a LINESTRING geometry attached to it. This is really of type OGRLayerH, but void * is used to avoid pulling the ogr_api.h file in here.
iIDField	If not -1 this will be used as a field index to indicate where a unique id should be written for each feature (contour) written.
iElevField	If not -1 this will be used as a field index to indicate where the elevation value of the contour should be written.
pfnProgress	A GDALProgressFunc that may be used to report progress to the user, or to interrupt the algorithm. May be NULL if not required.
pProgressArg	The callback data for the pfnProgress function.

Returns: CE_None on success or CE_Failure if an error occurs.

◆ GDALContourGenerateEx()

CPLErr GDALContourGenerateEx	(	GDALRasterBandH	hBand,
		void *	hLayer,
		CSLConstList	options,
		GDALProgressFunc	pfnProgress,
		void *	pProgressArg
	)

Create vector contours from raster DEM.

This algorithm is an implementation of "Marching squares" [1] that will generate contour vectors for the input raster band on the requested set of contour levels. The vector contours are written to the passed in OGR vector layer. Also, a NODATA value may be specified to identify pixels that should not be considered in contour line generation.

The gdal/apps/gdal_contour.cpp mainline can be used as an example of how to use this function.

[1] see https://en.wikipedia.org/wiki/Marching_squares

ALGORITHM RULES

For contouring purposes raster pixel values are assumed to represent a point value at the center of the corresponding pixel region. For the purpose of contour generation we virtually connect each pixel center to the values to the left, right, top and bottom. We assume that the pixel value is linearly interpolated between the pixel centers along each line, and determine where (if any) contour lines will appear along these line segments. Then the contour crossings are connected.

This means that contour lines' nodes will not actually be on pixel edges, but rather along vertical and horizontal lines connecting the pixel centers.

General Case:

      5 |                  | 3
     -- + ---------------- + --
        |                  |
        |                  |
        |                  |
        |                  |
     10 +                  |
        |\                 |
        | \                |
     -- + -+-------------- + --
     12 |  10              | 1

Saddle Point:

      5 |                  | 12
     -- + -------------+-- + --
        |               \  |
        |                 \|
        |                  +
        |                  |
        +                  |
        |\                 |
        | \                |
     -- + -+-------------- + --
     12 |                  | 1

or:

      5 |                  | 12
     -- + -------------+-- + --
        |          __/     |
        |      ___/        |
        |  ___/          __+
        | /           __/  |
        +'         __/     |
        |       __/        |
        |   ,__/           |
     -- + -+-------------- + --
     12 |                  | 1

Nodata:

In the "nodata" case we treat the whole nodata pixel as a no-mans land. We extend the corner pixels near the nodata out to half way and then construct extra lines from those points to the center which is assigned an averaged value from the two nearby points (in this case (12+3+5)/3).

      5 |                  | 3
     -- + ---------------- + --
        |                  |
        |                  |
        |      6.7         |
        |        +---------+ 3
     10 +___     |
        |   \____+ 10
        |        |
     -- + -------+        +
     12 |       12           (nodata)

Parameters

hBand	The band to read raster data from. The whole band will be processed.
hLayer	The layer to which new contour vectors will be written. Each contour will have a LINESTRING geometry attached to it (or POLYGON if POLYGONIZE=YES). This is really of type OGRLayerH, but void * is used to avoid pulling the ogr_api.h file in here.
pfnProgress	A GDALProgressFunc that may be used to report progress to the user, or to interrupt the algorithm. May be NULL if not required.
pProgressArg	The callback data for the pfnProgress function.
options	List of options

Options:

LEVEL_INTERVAL=f

The elevation interval between contours generated.

LEVEL_BASE=f

The "base" relative to which contour intervals are applied. This is normally zero, but could be different. To generate 10m contours at 5, 15, 25, ... the LEVEL_BASE would be 5.

LEVEL_EXP_BASE=f

If greater than 0, contour levels are generated on an exponential scale. Levels will then be generated by LEVEL_EXP_BASE^k where k is a positive integer.

FIXED_LEVELS=f[,f]*

The list of fixed contour levels at which contours should be generated. This option has precedence on LEVEL_INTERVAL

NODATA=f

The value to use as a "nodata" value. That is, a pixel value which should be ignored in generating contours as if the value of the pixel were not known.

ID_FIELD=d

This will be used as a field index to indicate where a unique id should be written for each feature (contour) written.

ELEV_FIELD=d

This will be used as a field index to indicate where the elevation value of the contour should be written. Only used in line contouring mode.

ELEV_FIELD_MIN=d

This will be used as a field index to indicate where the minimum elevation value of the polygon contour should be written. Only used in polygonal contouring mode.

 ELEV_FIELD_MAX=d

This will be used as a field index to indicate where the maximum elevation value of the polygon contour should be written. Only used in polygonal contouring mode.

 POLYGONIZE=YES|NO

If YES, contour polygons will be created, rather than polygon lines.

Returns: CE_None on success or CE_Failure if an error occurs.

◆ GDALCreateApproxTransformer()

void * GDALCreateApproxTransformer	(	GDALTransformerFunc	pfnBaseTransformer,
		void *	pBaseTransformArg,
		double	dfMaxError
	)

Create an approximating transformer.

This function creates a context for an approximated transformer. Basically a high precision transformer is supplied as input and internally linear approximations are computed to generate results to within a defined precision.

The approximation is actually done at the point where GDALApproxTransform() calls are made, and depend on the assumption that they are roughly linear. The first and last point passed in must be the extreme values and the intermediate values should describe a curve between the end points. The approximator transforms and centers using the approximate transformer, and then compares the true middle transformed value to a linear approximation based on the end points. If the error is within the supplied threshold then the end points are used to linearly approximate all the values otherwise the input points are split into two smaller sets, and the function is recursively called until a sufficiently small set of points is found that the linear approximation is OK, or that all the points are exactly computed.

This function is very suitable for approximating transformation results from output pixel/line space to input coordinates for warpers that operate on one input scanline at a time. Care should be taken using it in other circumstances as little internal validation is done in order to keep things fast.

Parameters

pfnBaseTransformer	the high precision transformer which should be approximated.
pBaseTransformArg	the callback argument for the high precision transformer.
dfMaxError	the maximum cartesian error in the "output" space that is to be accepted in the linear approximation.

Returns: callback pointer suitable for use with GDALApproxTransform(). It should be deallocated with GDALDestroyApproxTransformer().

◆ GDALCreateGCPTransformer()

void * GDALCreateGCPTransformer	(	int	nGCPCount,
		const GDAL_GCP *	pasGCPList,
		int	nReqOrder,
		int	bReversed
	)

Create GCP based polynomial transformer.

Computes least squares fit polynomials from a provided set of GCPs, and stores the coefficients for later transformation of points between pixel/line and georeferenced coordinates.

The return value should be used as a TransformArg in combination with the transformation function GDALGCPTransform which fits the GDALTransformerFunc signature. The returned transform argument should be deallocated with GDALDestroyGCPTransformer when no longer needed.

This function may fail (returning nullptr) if the provided set of GCPs are inadequate for the requested order, the determinate is zero or they are otherwise "ill conditioned".

Note that 2nd order requires at least 6 GCPs, and 3rd order requires at least 10 gcps. If nReqOrder is 0 the highest order possible (limited to 2) with the provided gcp count will be used.

Parameters

nGCPCount	the number of GCPs in pasGCPList.
pasGCPList	an array of GCPs to be used as input.
nReqOrder	the requested polynomial order. It should be 1, 2 or 3. Using 3 is not recommended due to potential numeric instabilities issues.
bReversed	set it to TRUE to compute the reversed transformation.

Returns: the transform argument or nullptr if creation fails.

◆ GDALCreateGenImgProjTransformer()

void * GDALCreateGenImgProjTransformer	(	GDALDatasetH	hSrcDS,
		const char *	pszSrcWKT,
		GDALDatasetH	hDstDS,
		const char *	pszDstWKT,
		int	bGCPUseOK,
		double	dfGCPErrorThreshold,
		int	nOrder
	)

Create image to image transformer.

This function creates a transformation object that maps from pixel/line coordinates on one image to pixel/line coordinates on another image. The images may potentially be georeferenced in different coordinate systems, and may used GCPs to map between their pixel/line coordinates and georeferenced coordinates (as opposed to the default assumption that their geotransform should be used).

This transformer potentially performs three concatenated transformations.

The first stage is from source image pixel/line coordinates to source image georeferenced coordinates, and may be done using the geotransform, or if not defined using a polynomial model derived from GCPs. If GCPs are used this stage is accomplished using GDALGCPTransform().

The second stage is to change projections from the source coordinate system to the destination coordinate system, assuming they differ. This is accomplished internally using GDALReprojectionTransform().

The third stage is converting from destination image georeferenced coordinates to destination image coordinates. This is done using the destination image geotransform, or if not available, using a polynomial model derived from GCPs. If GCPs are used this stage is accomplished using GDALGCPTransform(). This stage is skipped if hDstDS is NULL when the transformation is created.

Parameters

hSrcDS	source dataset, or NULL.
pszSrcWKT	the coordinate system for the source dataset. If NULL, it will be read from the dataset itself.
hDstDS	destination dataset (or NULL).
pszDstWKT	the coordinate system for the destination dataset. If NULL, and hDstDS not NULL, it will be read from the destination dataset.
bGCPUseOK	TRUE if GCPs should be used if the geotransform is not available on the source dataset (not destination).
dfGCPErrorThreshold	ignored/deprecated.
nOrder	the maximum order to use for GCP derived polynomials if possible. Use 0 to autoselect, or -1 for thin plate splines.

Returns: handle suitable for use GDALGenImgProjTransform(), and to be deallocated with GDALDestroyGenImgProjTransformer().

◆ GDALCreateGenImgProjTransformer2()

void * GDALCreateGenImgProjTransformer2	(	GDALDatasetH	hSrcDS,
		GDALDatasetH	hDstDS,
		char **	papszOptions
	)

Create image to image transformer.

This function creates a transformation object that maps from pixel/line coordinates on one image to pixel/line coordinates on another image. The images may potentially be georeferenced in different coordinate systems, and may used GCPs to map between their pixel/line coordinates and georeferenced coordinates (as opposed to the default assumption that their geotransform should be used).

This transformer potentially performs three concatenated transformations.

The first stage is from source image pixel/line coordinates to source image georeferenced coordinates, and may be done using the geotransform, or if not defined using a polynomial model derived from GCPs. If GCPs are used this stage is accomplished using GDALGCPTransform().

The second stage is to change projections from the source coordinate system to the destination coordinate system, assuming they differ. This is accomplished internally using GDALReprojectionTransform().

The third stage is converting from destination image georeferenced coordinates to destination image coordinates. This is done using the destination image geotransform, or if not available, using a polynomial model derived from GCPs. If GCPs are used this stage is accomplished using GDALGCPTransform(). This stage is skipped if hDstDS is NULL when the transformation is created.

Supported Options (specified with the -to switch of gdalwarp for example):

SRC_SRS: WKT SRS, or any string recognized by OGRSpatialReference::SetFromUserInput(), to be used as an override for hSrcDS.
DST_SRS: WKT SRS, or any string recognized by OGRSpatialReference::SetFromUserInput(), to be used as an override for hDstDS.
COORDINATE_OPERATION: (GDAL >= 3.0) Coordinate operation, as a PROJ or WKT string, used as an override over the normally computed pipeline. The pipeline must take into account the axis order of the source and target SRS.
COORDINATE_EPOCH: (GDAL >= 3.0) Coordinate epoch, expressed as a decimal year. Useful for time-dependant coordinate operations.
SRC_COORDINATE_EPOCH: (GDAL >= 3.4) Coordinate epoch of source CRS, expressed as a decimal year. Useful for time-dependant coordinate operations.
DST_COORDINATE_EPOCH: (GDAL >= 3.4) Coordinate epoch of target CRS, expressed as a decimal year. Useful for time-dependant coordinate operations.
GCPS_OK: If false, GCPs will not be used, default is TRUE.
REFINE_MINIMUM_GCPS: The minimum amount of GCPs that should be available after the refinement.
REFINE_TOLERANCE: The tolerance that specifies when a GCP will be eliminated.
MAX_GCP_ORDER: the maximum order to use for GCP derived polynomials if possible. The default is to autoselect based on the number of GCPs. A value of -1 triggers use of Thin Plate Spline instead of polynomials.
GCP_ANTIMERIDIAN_UNWRAP=AUTO/YES/NO. (GDAL >= 3.8) Whether to "unwrap" longitudes of ground control points that span the antimeridian. For datasets with GCPs in longitude/latitude coordinate space spanning the antimeridian, longitudes will have a discontinuity on +/- 180 deg, and will result in a subset of the GCPs with longitude in the [-180,-170] range and another subset in [170, 180]. By default (AUTO), that situation will be detected and longitudes in [-180,-170] will be shifted to [180, 190] to get a continuous set. This option can be set to YES to force that behavior (useful if no SRS information is available), or to NO to disable it.
SRC_METHOD: may have a value which is one of GEOTRANSFORM, GCP_POLYNOMIAL, GCP_TPS, GEOLOC_ARRAY, RPC to force only one geolocation method to be considered on the source dataset. Will be used for pixel/line to georef transformation on the source dataset. NO_GEOTRANSFORM can be used to specify the identity geotransform (ungeoreference image)
DST_METHOD: may have a value which is one of GEOTRANSFORM, GCP_POLYNOMIAL, GCP_TPS, GEOLOC_ARRAY (added in 3.5), RPC to force only one geolocation method to be considered on the target dataset. Will be used for pixel/line to georef transformation on the destination dataset. NO_GEOTRANSFORM can be used to specify the identity geotransform (ungeoreference image)
RPC_HEIGHT: A fixed height to be used with RPC calculations.
RPC_DEM: The name of a DEM file to be used with RPC calculations. See GDALCreateRPCTransformerV2() for more details.
Other RPC related options. See GDALCreateRPCTransformerV2()
INSERT_CENTER_LONG: May be set to FALSE to disable setting up a CENTER_LONG value on the coordinate system to rewrap things around the center of the image.
SRC_APPROX_ERROR_IN_SRS_UNIT=err_threshold_in_SRS_units. (GDAL >= 2.2) Use an approximate transformer for the source transformer. Must be defined together with SRC_APPROX_ERROR_IN_PIXEL to be taken into account.
SRC_APPROX_ERROR_IN_PIXEL=err_threshold_in_pixel. (GDAL >= 2.2) Use an approximate transformer for the source transformer.. Must be defined together with SRC_APPROX_ERROR_IN_SRS_UNIT to be taken into account.
DST_APPROX_ERROR_IN_SRS_UNIT=err_threshold_in_SRS_units. (GDAL >= 2.2) Use an approximate transformer for the destination transformer. Must be defined together with DST_APPROX_ERROR_IN_PIXEL to be taken into account.
DST_APPROX_ERROR_IN_PIXEL=err_threshold_in_pixel. (GDAL >= 2.2) Use an approximate transformer for the destination transformer. Must be defined together with DST_APPROX_ERROR_IN_SRS_UNIT to be taken into account.
REPROJECTION_APPROX_ERROR_IN_SRC_SRS_UNIT=err_threshold_in_src_SRS_units. (GDAL >= 2.2) Use an approximate transformer for the coordinate reprojection. Must be used together with REPROJECTION_APPROX_ERROR_IN_DST_SRS_UNIT to be taken into account.
REPROJECTION_APPROX_ERROR_IN_DST_SRS_UNIT=err_threshold_in_dst_SRS_units. (GDAL >= 2.2) Use an approximate transformer for the coordinate reprojection. Must be used together with REPROJECTION_APPROX_ERROR_IN_SRC_SRS_UNIT to be taken into account.
AREA_OF_INTEREST=west_lon_deg,south_lat_deg,east_lon_deg,north_lat_deg. (GDAL >= 3.0) Area of interest, used to compute the best coordinate operation between the source and target SRS. If not specified, the bounding box of the source raster will be used.
GEOLOC_BACKMAP_OVERSAMPLE_FACTOR=[0.1,2]. (GDAL >= 3.5) Oversample factor used to derive the size of the "backmap" used for geolocation array transformers. Default value is 1.3.
GEOLOC_USE_TEMP_DATASETS=YES/NO. (GDAL >= 3.5) Whether temporary GeoTIFF datasets should be used to store the backmap. The default is NO, that is to use in-memory arrays, unless the number of pixels of the geolocation array is greater than 16 megapixels.
GEOLOC_ARRAY/SRC_GEOLOC_ARRAY=filename. (GDAL >= 3.5.2) Name of a GDAL dataset containing a geolocation array and associated metadata. This is an alternative to having geolocation information described in the GEOLOCATION metadata domain of the source dataset. The dataset specified may have a GEOLOCATION metadata domain containing appropriate metadata, however default values are assigned for all omitted items. X_BAND defaults to 1 and Y_BAND to 2, however the dataset must contain exactly 2 bands. PIXEL_OFFSET and LINE_OFFSET default to 0. PIXEL_STEP and LINE_STEP default to the ratio of the width/height of the source dataset divided by the with/height of the geolocation array. SRS defaults to the geolocation array dataset's spatial reference system if set, otherwise WGS84 is used. GEOREFERENCING_CONVENTION is selected from the main metadata domain if it is omitted from the GEOLOCATION domain, and if not available TOP_LEFT_CORNER is assigned as a default. If GEOLOC_ARRAY is set SRC_METHOD defaults to GEOLOC_ARRAY.
DST_GEOLOC_ARRAY=filename. (GDAL >= 3.5.2) Name of a GDAL dataset that contains at least 2 bands with the X and Y geolocation bands. This is an alternative to having geolocation information described in the GEOLOCATION metadata domain of the destination dataset. See SRC_GEOLOC_ARRAY description for details, assumptions, and defaults. If this option is set, DST_METHOD=GEOLOC_ARRAY will be assumed if not set.

The use case for the *_APPROX_ERROR_* options is when defining an approximate transformer on top of the GenImgProjTransformer globally is not practical. Such a use case is when the source dataset has RPC with a RPC DEM. In such case we don't want to use the approximate transformer on the RPC transformation, as the RPC DEM generally involves non-linearities that the approximate transformer will not detect. In such case, we must a non-approximated GenImgProjTransformer, but it might be worthwhile to use approximate sub- transformers, for example on coordinate reprojection. For example if warping from a source dataset with RPC to a destination dataset with a UTM projection, since the inverse UTM transformation is rather costly. In which case, one can use the REPROJECTION_APPROX_ERROR_IN_SRC_SRS_UNIT and REPROJECTION_APPROX_ERROR_IN_DST_SRS_UNIT options.

Parameters

hSrcDS	source dataset, or NULL.
hDstDS	destination dataset (or NULL).
papszOptions	NULL-terminated list of string options (or NULL).

Returns: handle suitable for use GDALGenImgProjTransform(), and to be deallocated with GDALDestroyGenImgProjTransformer() or NULL on failure.

◆ GDALCreateGenImgProjTransformer3()

void * GDALCreateGenImgProjTransformer3	(	const char *	pszSrcWKT,
		const double *	padfSrcGeoTransform,
		const char *	pszDstWKT,
		const double *	padfDstGeoTransform
	)

Create image to image transformer.

This function creates a transformation object that maps from pixel/line coordinates on one image to pixel/line coordinates on another image. The images may potentially be georeferenced in different coordinate systems, and may used GCPs to map between their pixel/line coordinates and georeferenced coordinates (as opposed to the default assumption that their geotransform should be used).

This transformer potentially performs three concatenated transformations.

The first stage is from source image pixel/line coordinates to source image georeferenced coordinates, and may be done using the geotransform, or if not defined using a polynomial model derived from GCPs. If GCPs are used this stage is accomplished using GDALGCPTransform().

The second stage is to change projections from the source coordinate system to the destination coordinate system, assuming they differ. This is accomplished internally using GDALReprojectionTransform().

The third stage is converting from destination image georeferenced coordinates to destination image coordinates. This is done using the destination image geotransform, or if not available, using a polynomial model derived from GCPs. If GCPs are used this stage is accomplished using GDALGCPTransform(). This stage is skipped if hDstDS is NULL when the transformation is created.

Parameters

pszSrcWKT	source WKT (or NULL).
padfSrcGeoTransform	source geotransform (or NULL).
pszDstWKT	destination WKT (or NULL).
padfDstGeoTransform	destination geotransform (or NULL).

Returns: handle suitable for use GDALGenImgProjTransform(), and to be deallocated with GDALDestroyGenImgProjTransformer() or NULL on failure.

◆ GDALCreateGenImgProjTransformer4()

void * GDALCreateGenImgProjTransformer4	(	OGRSpatialReferenceH	hSrcSRS,
		const double *	padfSrcGeoTransform,
		OGRSpatialReferenceH	hDstSRS,
		const double *	padfDstGeoTransform,
		const char const	papszOptions
	)

Create image to image transformer.

Similar to GDALCreateGenImgProjTransformer3(), except that it takes OGRSpatialReferenceH objects and options. The options are the ones supported by GDALCreateReprojectionTransformerEx()

Since: GDAL 3.0

◆ GDALCreateReprojectionTransformer()

void * GDALCreateReprojectionTransformer	(	const char *	pszSrcWKT,
		const char *	pszDstWKT
	)

Create reprojection transformer.

Creates a callback data structure suitable for use with GDALReprojectionTransformation() to represent a transformation from one geographic or projected coordinate system to another. On input the coordinate systems are described in OpenGIS WKT format.

Internally the OGRCoordinateTransformation object is used to implement the reprojection.

Parameters

pszSrcWKT	the coordinate system for the source coordinate system.
pszDstWKT	the coordinate system for the destination coordinate system.

Returns: Handle for use with GDALReprojectionTransform(), or NULL if the system fails to initialize the reprojection.

◆ GDALCreateReprojectionTransformerEx()

void * GDALCreateReprojectionTransformerEx	(	OGRSpatialReferenceH	hSrcSRS,
		OGRSpatialReferenceH	hDstSRS,
		const char const	papszOptions
	)

Create reprojection transformer.

Creates a callback data structure suitable for use with GDALReprojectionTransformation() to represent a transformation from one geographic or projected coordinate system to another.

Internally the OGRCoordinateTransformation object is used to implement the reprojection.

Parameters

hSrcSRS	the coordinate system for the source coordinate system.
hDstSRS	the coordinate system for the destination coordinate system.
papszOptions	NULL-terminated list of options, or NULL. Currently supported options are: AREA_OF_INTEREST=west_long,south_lat,east_long,north_lat: Values in degrees. longitudes in [-180,180], latitudes in [-90,90]. COORDINATE_OPERATION=string: PROJ or WKT string representing a coordinate operation, overriding the default computed transformation. COORDINATE_EPOCH=decimal_year: Coordinate epoch, expressed as a decimal year. Useful for time-dependant coordinate operations. SRC_COORDINATE_EPOCH: (GDAL >= 3.4) Coordinate epoch of source CRS, expressed as a decimal year. Useful for time-dependant coordinate operations. DST_COORDINATE_EPOCH: (GDAL >= 3.4) Coordinate epoch of target CRS, expressed as a decimal year. Useful for time-dependant coordinate operations.

Returns: Handle for use with GDALReprojectionTransform(), or NULL if the system fails to initialize the reprojection.

Since: GDAL 3.0

◆ GDALCreateRPCTransformerV2()

void * GDALCreateRPCTransformerV2	(	const GDALRPCInfoV2 *	psRPCInfo,
		int	bReversed,
		double	dfPixErrThreshold,
		char **	papszOptions
	)

Create an RPC based transformer.

The geometric sensor model describing the physical relationship between image coordinates and ground coordinate is known as a Rigorous Projection Model. A Rigorous Projection Model expresses the mapping of the image space coordinates of rows and columns (r,c) onto the object space reference surface geodetic coordinates (long, lat, height).

RPC supports a generic description of the Rigorous Projection Models. The approximation used by GDAL (RPC00) is a set of rational polynomials expressing the normalized row and column values, (rn , cn), as a function of normalized geodetic latitude, longitude, and height, (P, L, H), given a set of normalized polynomial coefficients (LINE_NUM_COEF_n, LINE_DEN_COEF_n, SAMP_NUM_COEF_n, SAMP_DEN_COEF_n). Normalized values, rather than actual values are used in order to minimize introduction of errors during the calculations. The transformation between row and column values (r,c), and normalized row and column values (rn, cn), and between the geodetic latitude, longitude, and height and normalized geodetic latitude, longitude, and height (P, L, H), is defined by a set of normalizing translations (offsets) and scales that ensure all values are contained i the range -1 to +1.

This function creates a GDALTransformFunc compatible transformer for going between image pixel/line and long/lat/height coordinates using RPCs. The RPCs are provided in a GDALRPCInfo structure which is normally read from metadata using GDALExtractRPCInfo().

GDAL RPC Metadata has the following entries (also described in GDAL RFC 22 and the GeoTIFF RPC document http://geotiff.maptools.org/rpc_prop.html .

ERR_BIAS: Error - Bias. The RMS bias error in meters per horizontal axis of all points in the image (-1.0 if unknown)
ERR_RAND: Error - Random. RMS random error in meters per horizontal axis of each point in the image (-1.0 if unknown)
LINE_OFF: Line Offset
SAMP_OFF: Sample Offset
LAT_OFF: Geodetic Latitude Offset
LONG_OFF: Geodetic Longitude Offset
HEIGHT_OFF: Geodetic Height Offset
LINE_SCALE: Line Scale
SAMP_SCALE: Sample Scale
LAT_SCALE: Geodetic Latitude Scale
LONG_SCALE: Geodetic Longitude Scale
HEIGHT_SCALE: Geodetic Height Scale
LINE_NUM_COEFF (1-20): Line Numerator Coefficients. Twenty coefficients for the polynomial in the Numerator of the rn equation. (space separated)
LINE_DEN_COEFF (1-20): Line Denominator Coefficients. Twenty coefficients for the polynomial in the Denominator of the rn equation. (space separated)
SAMP_NUM_COEFF (1-20): Sample Numerator Coefficients. Twenty coefficients for the polynomial in the Numerator of the cn equation. (space separated)
SAMP_DEN_COEFF (1-20): Sample Denominator Coefficients. Twenty coefficients for the polynomial in the Denominator of the cn equation. (space separated)

The transformer normally maps from pixel/line/height to long/lat/height space as a forward transformation though in RPC terms that would be considered an inverse transformation (and is solved by iterative approximation using long/lat/height to pixel/line transformations). The default direction can be reversed by passing bReversed=TRUE.

The iterative solution of pixel/line to lat/long/height is currently run for up to 10 iterations or until the apparent error is less than dfPixErrThreshold pixels. Passing zero will not avoid all error, but will cause the operation to run for the maximum number of iterations.

Starting with GDAL 2.1, debugging of the RPC inverse transformer can be done by setting the RPC_INVERSE_VERBOSE configuration option to YES (in which case extra debug information will be displayed in the "RPC" debug category, so requiring CPL_DEBUG to be also set) and/or by setting RPC_INVERSE_LOG to a filename that will contain the content of iterations (this last option only makes sense when debugging point by point, since each time RPCInverseTransformPoint() is called, the file is rewritten).

Additional options to the transformer can be supplied in papszOptions.

Options:

RPC_HEIGHT: a fixed height offset to be applied to all points passed in. In this situation the Z passed into the transformation function is assumed to be height above ground, and the RPC_HEIGHT is assumed to be an average height above sea level for ground in the target scene.
RPC_HEIGHT_SCALE: a factor used to multiply heights above ground. Useful when elevation offsets of the DEM are not expressed in meters.
RPC_DEM: the name of a GDAL dataset (a DEM file typically) used to extract elevation offsets from. In this situation the Z passed into the transformation function is assumed to be height above ground. This option should be used in replacement of RPC_HEIGHT to provide a way of defining a non uniform ground for the target scene
RPC_DEMINTERPOLATION: the DEM interpolation ("near", "bilinear" or "cubic"). Default is "bilinear".
RPC_DEM_MISSING_VALUE: value of DEM height that must be used in case the DEM has nodata value at the sampling point, or if its extent does not cover the requested coordinate. When not specified, missing values will cause a failed transform.
RPC_DEM_SRS: (GDAL >= 3.2) WKT SRS, or any string recognized by OGRSpatialReference::SetFromUserInput(), to be used as an override for DEM SRS. Useful if DEM SRS does not have an explicit vertical component.
RPC_DEM_APPLY_VDATUM_SHIFT: whether the vertical component of a compound SRS for the DEM should be used (when it is present). This is useful so as to be able to transform the "raw" values from the DEM expressed with respect to a geoid to the heights with respect to the WGS84 ellipsoid. When this is enabled, the GTIFF_REPORT_COMPD_CS configuration option will be also set temporarily so as to get the vertical information from GeoTIFF files. Defaults to TRUE. (GDAL >= 2.1.0)
RPC_PIXEL_ERROR_THRESHOLD: overrides the dfPixErrThreshold parameter, ie the error (measured in pixels) allowed in the iterative solution of pixel/line to lat/long computations (the other way is always exact given the equations). (GDAL >= 2.1.0)
RPC_MAX_ITERATIONS: maximum number of iterations allowed in the iterative solution of pixel/line to lat/long computations. Default value is 10 in the absence of a DEM, or 20 if there is a DEM. (GDAL >= 2.1.0)
RPC_FOOTPRINT: WKT or GeoJSON polygon (in long / lat coordinate space) with a validity footprint for the RPC. Any coordinate transformation that goes from or arrive outside this footprint will be considered invalid. This is useful in situations where the RPC values become highly unstable outside of the area on which they have been computed for, potentially leading to undesirable "echoes" / false positives. This requires GDAL to be built against GEOS.

Parameters

psRPCInfo	Definition of the RPC parameters.
bReversed	If true "forward" transformation will be lat/long to pixel/line instead of the normal pixel/line to lat/long.
dfPixErrThreshold	the error (measured in pixels) allowed in the iterative solution of pixel/line to lat/long computations (the other way is always exact given the equations). Starting with GDAL 2.1, this may also be set through the RPC_PIXEL_ERROR_THRESHOLD transformer option. If a negative or null value is provided, then this defaults to 0.1 pixel.
papszOptions	Other transformer options (i.e. RPC_HEIGHT=z).

Returns: transformer callback data (deallocate with GDALDestroyTransformer()).

◆ GDALCreateTPSTransformer()

void * GDALCreateTPSTransformer	(	int	nGCPCount,
		const GDAL_GCP *	pasGCPList,
		int	bReversed
	)

Create Thin Plate Spline transformer from GCPs.

The thin plate spline transformer produces exact transformation at all control points and smoothly varying transformations between control points with greatest influence from local control points. It is suitable for for many applications not well modeled by polynomial transformations.

Creating the TPS transformer involves solving systems of linear equations related to the number of control points involved. This solution is computed within this function call. It can be quite an expensive operation for large numbers of GCPs. For instance, for reference, it takes on the order of 10s for 400 GCPs on a 2GHz Athlon processor.

TPS Transformers are serializable.

The GDAL Thin Plate Spline transformer is based on code provided by Gilad Ronnen on behalf of VIZRT Inc (http://www.visrt.com). Incorporation of the algorithm into GDAL was supported by the Centro di Ecologia Alpina (http://www.cealp.it).

Parameters

nGCPCount	the number of GCPs in pasGCPList.
pasGCPList	an array of GCPs to be used as input.
bReversed	set it to TRUE to compute the reversed transformation.

Returns: the transform argument or NULL if creation fails.

◆ GDALDestroyApproxTransformer()

void GDALDestroyApproxTransformer ( void * pCBData )

Cleanup approximate transformer.

Deallocates the resources allocated by GDALCreateApproxTransformer().

Parameters

pCBData callback data originally returned by GDALCreateApproxTransformer().

◆ GDALDestroyGCPTransformer()

void GDALDestroyGCPTransformer ( void * pTransformArg )

Destroy GCP transformer.

This function is used to destroy information about a GCP based polynomial transformation created with GDALCreateGCPTransformer().

Parameters

pTransformArg the transform arg previously returned by GDALCreateGCPTransformer().

◆ GDALDestroyGenImgProjTransformer()

void GDALDestroyGenImgProjTransformer ( void * hTransformArg )

GenImgProjTransformer deallocator.

This function is used to deallocate the handle created with GDALCreateGenImgProjTransformer().

Parameters

hTransformArg the handle to deallocate.

◆ GDALDestroyReprojectionTransformer()

void GDALDestroyReprojectionTransformer ( void * pTransformArg )

Destroy reprojection transformation.

Parameters

pTransformArg the transformation handle returned by GDALCreateReprojectionTransformer().

◆ GDALDestroyTPSTransformer()

void GDALDestroyTPSTransformer ( void * pTransformArg )

Destroy TPS transformer.

This function is used to destroy information about a GCP based polynomial transformation created with GDALCreateTPSTransformer().

Parameters

pTransformArg the transform arg previously returned by GDALCreateTPSTransformer().

◆ GDALDitherRGB2PCT()

int GDALDitherRGB2PCT	(	GDALRasterBandH	hRed,
		GDALRasterBandH	hGreen,
		GDALRasterBandH	hBlue,
		GDALRasterBandH	hTarget,
		GDALColorTableH	hColorTable,
		GDALProgressFunc	pfnProgress,
		void *	pProgressArg
	)

24bit to 8bit conversion with dithering.

This functions utilizes Floyd-Steinberg dithering in the process of converting a 24bit RGB image into a pseudocolored 8bit image using a provided color table.

The red, green and blue input bands do not necessarily need to come from the same file, but they must be the same width and height. They will be clipped to 8bit during reading, so non-eight bit bands are generally inappropriate. Likewise the hTarget band will be written with 8bit values and must match the width and height of the source bands.

The color table cannot have more than 256 entries.

Parameters

hRed	Red input band.
hGreen	Green input band.
hBlue	Blue input band.
hTarget	Output band.
hColorTable	the color table to use with the output band.
pfnProgress	callback for reporting algorithm progress matching the GDALProgressFunc() semantics. May be NULL.
pProgressArg	callback argument passed to pfnProgress.

Returns: CE_None on success or CE_Failure if an error occurs.

◆ GDALFillNodata()

CPLErr GDALFillNodata	(	GDALRasterBandH	hTargetBand,
		GDALRasterBandH	hMaskBand,
		double	dfMaxSearchDist,
		int	bDeprecatedOption,
		int	nSmoothingIterations,
		char **	papszOptions,
		GDALProgressFunc	pfnProgress,
		void *	pProgressArg
	)

Fill selected raster regions by interpolation from the edges.

This algorithm will interpolate values for all designated nodata pixels (marked by zeros in hMaskBand). For each pixel a four direction conic search is done to find values to interpolate from (using inverse distance weighting by default). Once all values are interpolated, zero or more smoothing iterations (3x3 average filters on interpolated pixels) are applied to smooth out artifacts.

This algorithm is generally suitable for interpolating missing regions of fairly continuously varying rasters (such as elevation models for instance). It is also suitable for filling small holes and cracks in more irregularly varying images (like airphotos). It is generally not so great for interpolating a raster from sparse point data - see the algorithms defined in gdal_grid.h for that case.

Parameters

hTargetBand	the raster band to be modified in place.
hMaskBand	a mask band indicating pixels to be interpolated (zero valued). If hMaskBand is set to NULL, this method will internally use the mask band returned by GDALGetMaskBand(hTargetBand).
dfMaxSearchDist	the maximum number of pixels to search in all directions to find values to interpolate from.
bDeprecatedOption	unused argument, should be zero.
nSmoothingIterations	the number of 3x3 smoothing filter passes to run (0 or more).
papszOptions	additional name=value options in a string list. TEMP_FILE_DRIVER=gdal_driver_name. For example MEM. NODATA=value (starting with GDAL 2.4). Source pixels at that value will be ignored by the interpolator. Warning: currently this will not be honored by smoothing passes. INTERPOLATION=INV_DIST/NEAREST (GDAL >= 3.9). By default, pixels are interpolated using an inverse distance weighting (INV_DIST). It is also possible to choose a nearest neighbour (NEAREST) strategy.
pfnProgress	the progress function to report completion.
pProgressArg	callback data for progress function.

Returns: CE_None on success or CE_Failure if something goes wrong.

◆ GDALFPolygonize()

CPLErr GDALFPolygonize	(	GDALRasterBandH	hSrcBand,
		GDALRasterBandH	hMaskBand,
		OGRLayerH	hOutLayer,
		int	iPixValField,
		char **	papszOptions,
		GDALProgressFunc	pfnProgress,
		void *	pProgressArg
	)

Create polygon coverage from raster data.

This function creates vector polygons for all connected regions of pixels in the raster sharing a common pixel value. Optionally each polygon may be labeled with the pixel value in an attribute. Optionally a mask band can be provided to determine which pixels are eligible for processing.

The source pixel band values are read into a 32bit float buffer. If you want to use a (probably faster) version using signed 32bit integer buffer, see GDALPolygonize().

Polygon features will be created on the output layer, with polygon geometries representing the polygons. The polygon geometries will be in the georeferenced coordinate system of the image (based on the geotransform of the source dataset). It is acceptable for the output layer to already have features. Note that GDALFPolygonize() does not set the coordinate system on the output layer. Application code should do this when the layer is created, presumably matching the raster coordinate system.

The algorithm used attempts to minimize memory use so that very large rasters can be processed. However, if the raster has many polygons or very large/complex polygons, the memory use for holding polygon enumerations and active polygon geometries may grow to be quite large.

The algorithm will generally produce very dense polygon geometries, with edges that follow exactly on pixel boundaries for all non-interior pixels. For non-thematic raster data (such as satellite images) the result will essentially be one small polygon per pixel, and memory and output layer sizes will be substantial. The algorithm is primarily intended for relatively simple thematic imagery, masks, and classification results.

Parameters

hSrcBand	the source raster band to be processed.
hMaskBand	an optional mask band. All pixels in the mask band with a value other than zero will be considered suitable for collection as polygons.
hOutLayer	the vector feature layer to which the polygons should be written.
iPixValField	the attribute field index indicating the feature attribute into which the pixel value of the polygon should be written. Or -1 to indicate that the pixel value must not be written.
papszOptions	a name/value list of additional options 8CONNECTED=8: May be set to "8" to use 8 connectedness. Otherwise 4 connectedness will be applied to the algorithm DATASET_FOR_GEOREF=dataset_name: Name of a dataset from which to read the geotransform. This useful if hSrcBand has no related dataset, which is typical for mask bands.
pfnProgress	callback for reporting algorithm progress matching the GDALProgressFunc() semantics. May be NULL.
pProgressArg	callback argument passed to pfnProgress.

Returns: CE_None on success or CE_Failure on a failure.

Since: GDAL 1.9.0

◆ GDALGCPTransform()

int GDALGCPTransform	(	void *	pTransformArg,
		int	bDstToSrc,
		int	nPointCount,
		double *	x,
		double *	y,
		double *	z,
		int *	panSuccess
	)

Transforms point based on GCP derived polynomial model.

This function matches the GDALTransformerFunc signature, and can be used to transform one or more points from pixel/line coordinates to georeferenced coordinates (SrcToDst) or vice versa (DstToSrc).

Parameters

pTransformArg	return value from GDALCreateGCPTransformer().
bDstToSrc	TRUE if transformation is from the destination (georeferenced) coordinates to pixel/line or FALSE when transforming from pixel/line to georeferenced coordinates.
nPointCount	the number of values in the x, y and z arrays.
x	array containing the X values to be transformed.
y	array containing the Y values to be transformed.
z	array containing the Z values to be transformed.
panSuccess	array in which a flag indicating success (TRUE) or failure (FALSE) of the transformation are placed.

Returns: TRUE.

◆ GDALGenImgProjTransform()

int GDALGenImgProjTransform	(	void *	pTransformArgIn,
		int	bDstToSrc,
		int	nPointCount,
		double *	padfX,
		double *	padfY,
		double *	padfZ,
		int *	panSuccess
	)

Perform general image reprojection transformation.

Actually performs the transformation setup in GDALCreateGenImgProjTransformer(). This function matches the signature required by the GDALTransformerFunc(), and more details on the arguments can be found in that topic.

◆ GDALGetTransformerDstGeoTransform()

void GDALGetTransformerDstGeoTransform	(	void *	pTransformArg,
		double *	padfGeoTransform
	)

Get ApproxTransformer or GenImgProj output geotransform.

Parameters

pTransformArg	transformer handle.
padfGeoTransform	(output) the destination geotransform to return (six doubles).

◆ GDALGridContextCreate()

GDALGridContext * GDALGridContextCreate	(	GDALGridAlgorithm	eAlgorithm,
		const void *	poOptions,
		GUInt32	nPoints,
		const double *	padfX,
		const double *	padfY,
		const double *	padfZ,
		int	bCallerWillKeepPointArraysAlive
	)

Creates a context to do regular gridding from the scattered data.

This function takes the arrays of X and Y coordinates and corresponding Z values as input to prepare computation of regular grid (or call it a raster) from these scattered data.

On Intel/AMD i386/x86_64 architectures, some gridding methods will be optimized with SSE instructions (provided GDAL has been compiled with such support, and it is available at runtime). Currently, only 'invdist' algorithm with default parameters has an optimized implementation. This can provide substantial speed-up, but sometimes at the expense of reduced floating point precision. This can be disabled by setting the GDAL_USE_SSE configuration option to NO. A further optimized version can use the AVX instruction set. This can be disabled by setting the GDAL_USE_AVX configuration option to NO.

It is possible to set the GDAL_NUM_THREADS configuration option to parallelize the processing. The value to set is the number of worker threads, or ALL_CPUS to use all the cores/CPUs of the computer (default value).

Parameters

eAlgorithm	Gridding method.
poOptions	Options to control chosen gridding method.
nPoints	Number of elements in input arrays.
padfX	Input array of X coordinates.
padfY	Input array of Y coordinates.
padfZ	Input array of Z values.
bCallerWillKeepPointArraysAlive	Whether the provided padfX, padfY, padfZ arrays will still be "alive" during the calls to GDALGridContextProcess(). Setting to TRUE prevent them from being duplicated in the context. If unsure, set to FALSE.

Returns: the context (to be freed with GDALGridContextFree()) or NULL in case or error.

Since: GDAL 2.1

◆ GDALGridContextFree()

void GDALGridContextFree ( GDALGridContext * psContext )

Free a context used created by GDALGridContextCreate()

Parameters

psContext the context.

Since: GDAL 2.1

◆ GDALGridContextProcess()

CPLErr GDALGridContextProcess	(	GDALGridContext *	psContext,
		double	dfXMin,
		double	dfXMax,
		double	dfYMin,
		double	dfYMax,
		GUInt32	nXSize,
		GUInt32	nYSize,
		GDALDataType	eType,
		void *	pData,
		GDALProgressFunc	pfnProgress,
		void *	pProgressArg
	)

Do the gridding of a window of a raster.

This function takes the gridding context as input to preprare computation of regular grid (or call it a raster) from these scattered data. You should supply the extent of the output grid and allocate array sufficient to hold such a grid.

Parameters

psContext	Gridding context.
dfXMin	Lowest X border of output grid.
dfXMax	Highest X border of output grid.
dfYMin	Lowest Y border of output grid.
dfYMax	Highest Y border of output grid.
nXSize	Number of columns in output grid.
nYSize	Number of rows in output grid.
eType	Data type of output array.
pData	Pointer to array where the computed grid will be stored.
pfnProgress	a GDALProgressFunc() compatible callback function for reporting progress or NULL.
pProgressArg	argument to be passed to pfnProgress. May be NULL.

Returns: CE_None on success or CE_Failure if something goes wrong.

Since: GDAL 2.1

◆ GDALGridCreate()

CPLErr GDALGridCreate	(	GDALGridAlgorithm	eAlgorithm,
		const void *	poOptions,
		GUInt32	nPoints,
		const double *	padfX,
		const double *	padfY,
		const double *	padfZ,
		double	dfXMin,
		double	dfXMax,
		double	dfYMin,
		double	dfYMax,
		GUInt32	nXSize,
		GUInt32	nYSize,
		GDALDataType	eType,
		void *	pData,
		GDALProgressFunc	pfnProgress,
		void *	pProgressArg
	)

Create regular grid from the scattered data.

This function takes the arrays of X and Y coordinates and corresponding Z values as input and computes regular grid (or call it a raster) from these scattered data. You should supply geometry and extent of the output grid and allocate array sufficient to hold such a grid.

Starting with GDAL 1.10, it is possible to set the GDAL_NUM_THREADS configuration option to parallelize the processing. The value to set is the number of worker threads, or ALL_CPUS to use all the cores/CPUs of the computer (default value).

Starting with GDAL 1.10, on Intel/AMD i386/x86_64 architectures, some gridding methods will be optimized with SSE instructions (provided GDAL has been compiled with such support, and it is available at runtime). Currently, only 'invdist' algorithm with default parameters has an optimized implementation. This can provide substantial speed-up, but sometimes at the expense of reduced floating point precision. This can be disabled by setting the GDAL_USE_SSE configuration option to NO. Starting with GDAL 1.11, a further optimized version can use the AVX instruction set. This can be disabled by setting the GDAL_USE_AVX configuration option to NO.

Note: it will be more efficient to use GDALGridContextCreate(), GDALGridContextProcess() and GDALGridContextFree() when doing repeated gridding operations with the same algorithm, parameters and points, and moving the window in the output grid.

Parameters

eAlgorithm	Gridding method.
poOptions	Options to control chosen gridding method.
nPoints	Number of elements in input arrays.
padfX	Input array of X coordinates.
padfY	Input array of Y coordinates.
padfZ	Input array of Z values.
dfXMin	Lowest X border of output grid.
dfXMax	Highest X border of output grid.
dfYMin	Lowest Y border of output grid.
dfYMax	Highest Y border of output grid.
nXSize	Number of columns in output grid.
nYSize	Number of rows in output grid.
eType	Data type of output array.
pData	Pointer to array where the computed grid will be stored.
pfnProgress	a GDALProgressFunc() compatible callback function for reporting progress or NULL.
pProgressArg	argument to be passed to pfnProgress. May be NULL.

Returns: CE_None on success or CE_Failure if something goes wrong.

◆ GDALHasTriangulation()

int GDALHasTriangulation ( void )

Returns if GDAL is built with Delaunay triangulation support.

Returns: TRUE if GDAL is built with Delaunay triangulation support.

Since: GDAL 2.1

◆ GDALIsLineOfSightVisible()

bool GDALIsLineOfSightVisible	(	const GDALRasterBandH	hBand,
		const int	xA,
		const int	yA,
		const double	zA,
		const int	xB,
		const int	yB,
		const double	zB,
		int *	pnxTerrainIntersection,
		int *	pnyTerrainIntersection,
		CSLConstList	papszOptions
	)

Check Line of Sight between two points.

Both input coordinates must be within the raster coordinate bounds.

This algorithm will check line of sight using a Bresenham algorithm. https://www.researchgate.net/publication/2411280_Efficient_Line-of-Sight_Algorithms_for_Real_Terrain_Data Line of sight is computed in raster coordinate space, and thus may not be appropriate. For example, datasets referenced against geographic coordinate at high latitudes may have issues.

Parameters

	hBand	The band to read the DEM data from. This must NOT be null.
	xA	The X location (raster column) of the first point to check on the raster.
	yA	The Y location (raster row) of the first point to check on the raster.
	zA	The Z location (height) of the first point to check.
	xB	The X location (raster column) of the second point to check on the raster.
	yB	The Y location (raster row) of the second point to check on the raster.
	zB	The Z location (height) of the second point to check.
[out]	pnxTerrainIntersection	The X location where the LOS line intersects with terrain, or nullptr if it does not intersect terrain. Not implemented currently (*pnxTerrainIntersection is set to -1)
[out]	pnyTerrainIntersection	The Y location where the LOS line intersects with terrain, or nullptr if it does not intersect terrain. Not implemented currently (*pnyTerrainIntersection is set to -1)
	papszOptions	Options for the line of sight algorithm (currently ignored).

Returns: True if the two points are within Line of Sight.

Since: GDAL 3.9

Todo:: In order to reduce CPU cost and avoid a sqrt operation, consider the approach to just the ratio along x or y depending on whether the line is steep or shallow. See https://github.com/OSGeo/gdal/pull/9506#discussion_r1532459689.

◆ GDALOpenVerticalShiftGrid()

GDALDatasetH GDALOpenVerticalShiftGrid	(	const char *	pszProj4Geoidgrids,
		int *	pbError
	)

Load proj.4 geoidgrids as GDAL dataset.

Parameters

pszProj4Geoidgrids	Value of proj.4 geoidgrids parameter.
pbError	If not NULL, the pointed value will be set to TRUE if an error occurred.

Returns: a dataset. If not NULL, it must be closed with GDALClose().

Since: GDAL 2.2

Deprecated:: GDAL 3.4. Will be removed in GDAL 4.0. This function was used by gdalwarp initially, but is no longer needed.

◆ GDALPolygonize()

CPLErr GDALPolygonize	(	GDALRasterBandH	hSrcBand,
		GDALRasterBandH	hMaskBand,
		OGRLayerH	hOutLayer,
		int	iPixValField,
		char **	papszOptions,
		GDALProgressFunc	pfnProgress,
		void *	pProgressArg
	)

Create polygon coverage from raster data.

This function creates vector polygons for all connected regions of pixels in the raster sharing a common pixel value. Optionally each polygon may be labeled with the pixel value in an attribute. Optionally a mask band can be provided to determine which pixels are eligible for processing.

Note that currently the source pixel band values are read into a signed 64bit integer buffer (Int64), so floating point or complex bands will be implicitly truncated before processing. If you want to use a version using 32bit float buffers, see GDALFPolygonize().

Polygon features will be created on the output layer, with polygon geometries representing the polygons. The polygon geometries will be in the georeferenced coordinate system of the image (based on the geotransform of the source dataset). It is acceptable for the output layer to already have features. Note that GDALPolygonize() does not set the coordinate system on the output layer. Application code should do this when the layer is created, presumably matching the raster coordinate system.

The algorithm used attempts to minimize memory use so that very large rasters can be processed. However, if the raster has many polygons or very large/complex polygons, the memory use for holding polygon enumerations and active polygon geometries may grow to be quite large.

The algorithm will generally produce very dense polygon geometries, with edges that follow exactly on pixel boundaries for all non-interior pixels. For non-thematic raster data (such as satellite images) the result will essentially be one small polygon per pixel, and memory and output layer sizes will be substantial. The algorithm is primarily intended for relatively simple thematic imagery, masks, and classification results.

Parameters

hSrcBand	the source raster band to be processed.
hMaskBand	an optional mask band. All pixels in the mask band with a value other than zero will be considered suitable for collection as polygons.
hOutLayer	the vector feature layer to which the polygons should be written.
iPixValField	the attribute field index indicating the feature attribute into which the pixel value of the polygon should be written. Or -1 to indicate that the pixel value must not be written.
papszOptions	a name/value list of additional options 8CONNECTED=8: May be set to "8" to use 8 connectedness. Otherwise 4 connectedness will be applied to the algorithm DATASET_FOR_GEOREF=dataset_name: Name of a dataset from which to read the geotransform. This useful if hSrcBand has no related dataset, which is typical for mask bands.
pfnProgress	callback for reporting algorithm progress matching the GDALProgressFunc() semantics. May be NULL.
pProgressArg	callback argument passed to pfnProgress.

Returns: CE_None on success or CE_Failure on a failure.

◆ GDALRasterizeGeometries()

CPLErr GDALRasterizeGeometries	(	GDALDatasetH	hDS,
		int	nBandCount,
		const int *	panBandList,
		int	nGeomCount,
		const OGRGeometryH *	pahGeometries,
		GDALTransformerFunc	pfnTransformer,
		void *	pTransformArg,
		const double *	padfGeomBurnValues,
		CSLConstList	papszOptions,
		GDALProgressFunc	pfnProgress,
		void *	pProgressArg
	)

Burn geometries into raster.

Rasterize a list of geometric objects into a raster dataset. The geometries are passed as an array of OGRGeometryH handlers.

If the geometries are in the georeferenced coordinates of the raster dataset, then the pfnTransform may be passed in NULL and one will be derived internally from the geotransform of the dataset. The transform needs to transform the geometry locations into pixel/line coordinates on the raster dataset.

The output raster may be of any GDAL supported datatype. An explicit list of burn values for each geometry for each band must be passed in.

The papszOption list of options currently only supports one option. The "ALL_TOUCHED" option may be enabled by setting it to "TRUE".

Parameters

hDS	output data, must be opened in update mode.
nBandCount	the number of bands to be updated.
panBandList	the list of bands to be updated.
nGeomCount	the number of geometries being passed in pahGeometries.
pahGeometries	the array of geometries to burn in.
pfnTransformer	transformation to apply to geometries to put into pixel/line coordinates on raster. If NULL a geotransform based one will be created internally.
pTransformArg	callback data for transformer.
padfGeomBurnValues	the array of values to burn into the raster. There should be nBandCount values for each geometry.
papszOptions	special options controlling rasterization "ALL_TOUCHED": May be set to TRUE to set all pixels touched by the line or polygons, not just those whose center is within the polygon or that are selected by brezenhams line algorithm. Defaults to FALSE. "BURN_VALUE_FROM": May be set to "Z" to use the Z values of the geometries. dfBurnValue is added to this before burning. Defaults to GDALBurnValueSrc.GBV_UserBurnValue in which case just the dfBurnValue is burned. This is implemented only for points and lines for now. The M value may be supported in the future. "MERGE_ALG": May be REPLACE (the default) or ADD. REPLACE results in overwriting of value, while ADD adds the new value to the existing raster, suitable for heatmaps for instance. "CHUNKYSIZE": The height in lines of the chunk to operate on. The larger the chunk size the less times we need to make a pass through all the shapes. If it is not set or set to zero the default chunk size will be used. Default size will be estimated based on the GDAL cache buffer size using formula: cache_size_bytes/scanline_size_bytes, so the chunk will not exceed the cache. Not used in OPTIM=RASTER mode.
pfnProgress	the progress function to report completion.
pProgressArg	callback data for progress function.

Returns: CE_None on success or CE_Failure on error.

Example
GDALRasterizeGeometries rasterize output to MEM Dataset :

      int nBufXSize      = 1024;
      int nBufYSize      = 1024;
      int nBandCount     = 1;
      GDALDataType eType = GDT_Byte;
      int nDataTypeSize  = GDALGetDataTypeSizeBytes(eType);
 
      void* pData = CPLCalloc( nBufXSize*nBufYSize*nBandCount, nDataTypeSize );
      char memdsetpath[1024];
      sprintf(memdsetpath,"MEM:::DATAPOINTER=0x%p,PIXELS=%d,LINES=%d,"
              "BANDS=%d,DATATYPE=%s,PIXELOFFSET=%d,LINEOFFSET=%d",
              pData,nBufXSize,nBufYSize,nBandCount,GDALGetDataTypeName(eType),
              nBandCount*nDataTypeSize, nBufXSize*nBandCount*nDataTypeSize );
 
       // Open Memory Dataset
       GDALDatasetH hMemDset = GDALOpen(memdsetpath, GA_Update);
       // or create it as follows
       // GDALDriverH hMemDriver = GDALGetDriverByName("MEM");
       // GDALDatasetH hMemDset = GDALCreate(hMemDriver, "", nBufXSize,
*nBufYSize, nBandCount, eType, NULL);
 
       double adfGeoTransform[6];
       // Assign GeoTransform parameters,Omitted here.
 
       GDALSetGeoTransform(hMemDset,adfGeoTransform);
       GDALSetProjection(hMemDset,pszProjection); // Can not
 
       // Do something ...
       // Need an array of OGRGeometry objects,The assumption here is pahGeoms
 
       int bandList[3] = { 1, 2, 3};
       std::vector<double> geomBurnValue(nGeomCount*nBandCount,255.0);
       CPLErr err = GDALRasterizeGeometries(hMemDset, nBandCount, bandList,
                               nGeomCount, pahGeoms, pfnTransformer,
*pTransformArg, geomBurnValue.data(), papszOptions, pfnProgress, pProgressArg);
       if( err != CE_None )
       {
           // Do something ...
       }
       GDALClose(hMemDset);
       CPLFree(pData);

◆ GDALRasterizeGeometriesInt64()

CPLErr GDALRasterizeGeometriesInt64	(	GDALDatasetH	hDS,
		int	nBandCount,
		const int *	panBandList,
		int	nGeomCount,
		const OGRGeometryH *	pahGeometries,
		GDALTransformerFunc	pfnTransformer,
		void *	pTransformArg,
		const int64_t *	panGeomBurnValues,
		CSLConstList	papszOptions,
		GDALProgressFunc	pfnProgress,
		void *	pProgressArg
	)

Burn geometries into raster.

Same as GDALRasterizeGeometries(), except that the burn values array is of type Int64. And the datatype of the output raster must be GDT_Int64.

Since: GDAL 3.5

◆ GDALRasterizeLayers()

CPLErr GDALRasterizeLayers	(	GDALDatasetH	hDS,
		int	nBandCount,
		int *	panBandList,
		int	nLayerCount,
		OGRLayerH *	pahLayers,
		GDALTransformerFunc	pfnTransformer,
		void *	pTransformArg,
		double *	padfLayerBurnValues,
		char **	papszOptions,
		GDALProgressFunc	pfnProgress,
		void *	pProgressArg
	)

Burn geometries from the specified list of layers into raster.

Rasterize all the geometric objects from a list of layers into a raster dataset. The layers are passed as an array of OGRLayerH handlers.

If the geometries are in the georeferenced coordinates of the raster dataset, then the pfnTransform may be passed in NULL and one will be derived internally from the geotransform of the dataset. The transform needs to transform the geometry locations into pixel/line coordinates on the raster dataset.

The output raster may be of any GDAL supported datatype. An explicit list of burn values for each layer for each band must be passed in.

Parameters

hDS	output data, must be opened in update mode.
nBandCount	the number of bands to be updated.
panBandList	the list of bands to be updated.
nLayerCount	the number of layers being passed in pahLayers array.
pahLayers	the array of layers to burn in.
pfnTransformer	transformation to apply to geometries to put into pixel/line coordinates on raster. If NULL a geotransform based one will be created internally.
pTransformArg	callback data for transformer.
padfLayerBurnValues	the array of values to burn into the raster. There should be nBandCount values for each layer.
papszOptions	special options controlling rasterization: "ATTRIBUTE": Identifies an attribute field on the features to be used for a burn in value. The value will be burned into all output bands. If specified, padfLayerBurnValues will not be used and can be a NULL pointer. "CHUNKYSIZE": The height in lines of the chunk to operate on. The larger the chunk size the less times we need to make a pass through all the shapes. If it is not set or set to zero the default chunk size will be used. Default size will be estimated based on the GDAL cache buffer size using formula: cache_size_bytes/scanline_size_bytes, so the chunk will not exceed the cache. "ALL_TOUCHED": May be set to TRUE to set all pixels touched by the line or polygons, not just those whose center is within the polygon or that are selected by brezenhams line algorithm. Defaults to FALSE. "BURN_VALUE_FROM": May be set to "Z" to use the Z values of the geometries. The value from padfLayerBurnValues or the attribute field value is added to this before burning. In default case dfBurnValue is burned as it is. This is implemented properly only for points and lines for now. Polygons will be burned using the Z value from the first point. The M value may be supported in the future. "MERGE_ALG": May be REPLACE (the default) or ADD. REPLACE results in overwriting of value, while ADD adds the new value to the existing raster, suitable for heatmaps for instance.
pfnProgress	the progress function to report completion.
pProgressArg	callback data for progress function.

Returns: CE_None on success or CE_Failure on error.

◆ GDALRasterizeLayersBuf()

CPLErr GDALRasterizeLayersBuf	(	void *	pData,
		int	nBufXSize,
		int	nBufYSize,
		GDALDataType	eBufType,
		int	nPixelSpace,
		int	nLineSpace,
		int	nLayerCount,
		OGRLayerH *	pahLayers,
		const char *	pszDstProjection,
		double *	padfDstGeoTransform,
		GDALTransformerFunc	pfnTransformer,
		void *	pTransformArg,
		double	dfBurnValue,
		char **	papszOptions,
		GDALProgressFunc	pfnProgress,
		void *	pProgressArg
	)

Burn geometries from the specified list of layer into raster.

Rasterize all the geometric objects from a list of layers into supplied raster buffer. The layers are passed as an array of OGRLayerH handlers.

If the geometries are in the georeferenced coordinates of the raster dataset, then the pfnTransform may be passed in NULL and one will be derived internally from the geotransform of the dataset. The transform needs to transform the geometry locations into pixel/line coordinates of the target raster.

The output raster may be of any GDAL supported datatype(non complex).

Parameters

pData	pointer to the output data array.
nBufXSize	width of the output data array in pixels.
nBufYSize	height of the output data array in pixels.
eBufType	data type of the output data array.
nPixelSpace	The byte offset from the start of one pixel value in pData to the start of the next pixel value within a scanline. If defaulted (0) the size of the datatype eBufType is used.
nLineSpace	The byte offset from the start of one scanline in pData to the start of the next. If defaulted the size of the datatype eBufType * nBufXSize is used.
nLayerCount	the number of layers being passed in pahLayers array.
pahLayers	the array of layers to burn in.
pszDstProjection	WKT defining the coordinate system of the target raster.
padfDstGeoTransform	geotransformation matrix of the target raster.
pfnTransformer	transformation to apply to geometries to put into pixel/line coordinates on raster. If NULL a geotransform based one will be created internally.
pTransformArg	callback data for transformer.
dfBurnValue	the value to burn into the raster.
papszOptions	special options controlling rasterization: "ATTRIBUTE": Identifies an attribute field on the features to be used for a burn in value. The value will be burned into all output bands. If specified, padfLayerBurnValues will not be used and can be a NULL pointer. "ALL_TOUCHED": May be set to TRUE to set all pixels touched by the line or polygons, not just those whose center is within the polygon or that are selected by brezenhams line algorithm. Defaults to FALSE. "BURN_VALUE_FROM": May be set to "Z" to use the Z values of the geometries. dfBurnValue or the attribute field value is added to this before burning. In default case dfBurnValue is burned as it is. This is implemented properly only for points and lines for now. Polygons will be burned using the Z value from the first point. The M value may be supported in the future. "MERGE_ALG": May be REPLACE (the default) or ADD. REPLACE results in overwriting of value, while ADD adds the new value to the existing raster, suitable for heatmaps for instance.
pfnProgress	the progress function to report completion.
pProgressArg	callback data for progress function.

Returns: CE_None on success or CE_Failure on error.

◆ GDALReprojectionTransform()

int GDALReprojectionTransform	(	void *	pTransformArg,
		int	bDstToSrc,
		int	nPointCount,
		double *	padfX,
		double *	padfY,
		double *	padfZ,
		int *	panSuccess
	)

Perform reprojection transformation.

Actually performs the reprojection transformation described in GDALCreateReprojectionTransformer(). This function matches the GDALTransformerFunc() signature. Details of the arguments are described there.

◆ GDALSetGenImgProjTransformerDstGeoTransform()

void GDALSetGenImgProjTransformerDstGeoTransform	(	void *	hTransformArg,
		const double *	padfGeoTransform
	)

Set GenImgProj output geotransform.

Normally the "destination geotransform", or transformation between georeferenced output coordinates and pixel/line coordinates on the destination file is extracted from the destination file by GDALCreateGenImgProjTransformer() and stored in the GenImgProj private info. However, sometimes it is inconvenient to have an output file handle with appropriate geotransform information when creating the transformation. For these cases, this function can be used to apply the destination geotransform.

Parameters

hTransformArg	the handle to update.
padfGeoTransform	the destination geotransform to apply (six doubles).

◆ GDALSetTransformerDstGeoTransform()

void GDALSetTransformerDstGeoTransform	(	void *	pTransformArg,
		const double *	padfGeoTransform
	)

Set ApproxTransformer or GenImgProj output geotransform.

This is a layer above GDALSetGenImgProjTransformerDstGeoTransform() that checks that the passed hTransformArg is compatible.

Normally the "destination geotransform", or transformation between georeferenced output coordinates and pixel/line coordinates on the destination file is extracted from the destination file by GDALCreateGenImgProjTransformer() and stored in the GenImgProj private info. However, sometimes it is inconvenient to have an output file handle with appropriate geotransform information when creating the transformation. For these cases, this function can be used to apply the destination geotransform.

Parameters

pTransformArg	the handle to update.
padfGeoTransform	the destination geotransform to apply (six doubles).

◆ GDALSieveFilter()

CPLErr GDALSieveFilter	(	GDALRasterBandH	hSrcBand,
		GDALRasterBandH	hMaskBand,
		GDALRasterBandH	hDstBand,
		int	nSizeThreshold,
		int	nConnectedness,
		char **	papszOptions,
		GDALProgressFunc	pfnProgress,
		void *	pProgressArg
	)

Removes small raster polygons.

The function removes raster polygons smaller than a provided threshold size (in pixels) and replaces them with the pixel value of the largest neighbour polygon.

Polygon are determined (per GDALRasterPolygonEnumerator) as regions of the raster where the pixels all have the same value, and that are contiguous (connected).

Pixels determined to be "nodata" per hMaskBand will not be treated as part of a polygon regardless of their pixel values. Nodata areas will never be changed nor affect polygon sizes.

Polygons smaller than the threshold with no neighbours that are as large as the threshold will not be altered. Polygons surrounded by nodata areas will therefore not be altered.

The algorithm makes three passes over the input file to enumerate the polygons and collect limited information about them. Memory use is proportional to the number of polygons (roughly 24 bytes per polygon), but is not directly related to the size of the raster. So very large raster files can be processed effectively if there aren't too many polygons. But extremely noisy rasters with many one pixel polygons will end up being expensive (in memory) to process.

Parameters

hSrcBand	the source raster band to be processed.
hMaskBand	an optional mask band. All pixels in the mask band with a value other than zero will be considered suitable for inclusion in polygons.
hDstBand	the output raster band. It may be the same as hSrcBand to update the source in place.
nSizeThreshold	raster polygons with sizes smaller than this will be merged into their largest neighbour.
nConnectedness	either 4 indicating that diagonal pixels are not considered directly adjacent for polygon membership purposes or 8 indicating they are.
papszOptions	algorithm options in name=value list form. None currently supported.
pfnProgress	callback for reporting algorithm progress matching the GDALProgressFunc() semantics. May be NULL.
pProgressArg	callback argument passed to pfnProgress.

Returns: CE_None on success or CE_Failure if an error occurs.

◆ GDALSimpleImageWarp()

int GDALSimpleImageWarp	(	GDALDatasetH	hSrcDS,
		GDALDatasetH	hDstDS,
		int	nBandCount,
		int *	panBandList,
		GDALTransformerFunc	pfnTransform,
		void *	pTransformArg,
		GDALProgressFunc	pfnProgress,
		void *	pProgressArg,
		char **	papszWarpOptions
	)

Perform simple image warp.

Copies an image from a source dataset to a destination dataset applying an application defined transformation. This algorithm is called simple because it lacks many options such as resampling kernels (other than nearest neighbour), support for data types other than 8bit, and the ability to warp images without holding the entire source and destination image in memory.

The following option(s) may be passed in papszWarpOptions.

"INIT=v[,v...]": This option indicates that the output dataset should be initialized to the indicated value in any area valid data is not written. Distinct values may be listed for each band separated by columns.

Parameters

hSrcDS	the source image dataset.
hDstDS	the destination image dataset.
nBandCount	the number of bands to be warped. If zero, all bands will be processed.
panBandList	the list of bands to translate.
pfnTransform	the transformation function to call. See GDALTransformerFunc().
pTransformArg	the callback handle to pass to pfnTransform.
pfnProgress	the function used to report progress. See GDALProgressFunc().
pProgressArg	the callback handle to pass to pfnProgress.
papszWarpOptions	additional options controlling the warp.

Returns: TRUE if the operation completes, or FALSE if an error occurs.

◆ GDALSuggestedWarpOutput()

CPLErr GDALSuggestedWarpOutput	(	GDALDatasetH	hSrcDS,
		GDALTransformerFunc	pfnTransformer,
		void *	pTransformArg,
		double *	padfGeoTransformOut,
		int *	pnPixels,
		int *	pnLines
	)

Suggest output file size.

This function is used to suggest the size, and georeferenced extents appropriate given the indicated transformation and input file. It walks the edges of the input file (approximately 20 sample points along each edge) transforming into output coordinates in order to get an extents box.

Then a resolution is computed with the intent that the length of the distance from the top left corner of the output imagery to the bottom right corner would represent the same number of pixels as in the source image. Note that if the image is somewhat rotated the diagonal taken isn't of the whole output bounding rectangle, but instead of the locations where the top/left and bottom/right corners transform. The output pixel size is always square. This is intended to approximately preserve the resolution of the input data in the output file.

The values returned in padfGeoTransformOut, pnPixels and pnLines are the suggested number of pixels and lines for the output file, and the geotransform relating those pixels to the output georeferenced coordinates.

The trickiest part of using the function is ensuring that the transformer created is from source file pixel/line coordinates to output file georeferenced coordinates. This can be accomplished with GDALCreateGenImgProjTransformer() by passing a NULL for the hDstDS.

Parameters

hSrcDS	the input image (it is assumed the whole input image is being transformed).
pfnTransformer	the transformer function.
pTransformArg	the callback data for the transformer function.
padfGeoTransformOut	the array of six doubles in which the suggested geotransform is returned.
pnPixels	int in which the suggest pixel width of output is returned.
pnLines	int in which the suggest pixel height of output is returned.

Returns: CE_None if successful or CE_Failure otherwise.

◆ GDALSuggestedWarpOutput2()

CPLErr GDALSuggestedWarpOutput2	(	GDALDatasetH	hSrcDS,
		GDALTransformerFunc	pfnTransformer,
		void *	pTransformArg,
		double *	padfGeoTransformOut,
		int *	pnPixels,
		int *	pnLines,
		double *	padfExtent,
		int	nOptions
	)

Suggest output file size.

This function is used to suggest the size, and georeferenced extents appropriate given the indicated transformation and input file. It walks the edges of the input file (approximately 20 sample points along each edge) transforming into output coordinates in order to get an extents box.

Then a resolution is computed with the intent that the length of the distance from the top left corner of the output imagery to the bottom right corner would represent the same number of pixels as in the source image. Note that if the image is somewhat rotated the diagonal taken isn't of the whole output bounding rectangle, but instead of the locations where the top/left and bottom/right corners transform. The output pixel size is always square. This is intended to approximately preserve the resolution of the input data in the output file.

The values returned in padfGeoTransformOut, pnPixels and pnLines are the suggested number of pixels and lines for the output file, and the geotransform relating those pixels to the output georeferenced coordinates.

The trickiest part of using the function is ensuring that the transformer created is from source file pixel/line coordinates to output file georeferenced coordinates. This can be accomplished with GDALCreateGenImgProjTransformer() by passing a NULL for the hDstDS.

Parameters

hSrcDS	the input image (it is assumed the whole input image is being transformed).
pfnTransformer	the transformer function.
pTransformArg	the callback data for the transformer function.
padfGeoTransformOut	the array of six doubles in which the suggested geotransform is returned.
pnPixels	int in which the suggest pixel width of output is returned.
pnLines	int in which the suggest pixel height of output is returned.
padfExtent	Four entry array to return extents as (xmin, ymin, xmax, ymax).
nOptions	Options flags. Zero or GDAL_SWO_ROUND_UP_SIZE to ask pnPixels and pnLines to be rounded up instead of being rounded to the closes integer, or GDAL_SWO_FORCE_SQUARE_PIXEL to indicate that the generated pixel size is a square.

Returns: CE_None if successful or CE_Failure otherwise.

◆ GDALTPSTransform()

int GDALTPSTransform	(	void *	pTransformArg,
		int	bDstToSrc,
		int	nPointCount,
		double *	x,
		double *	y,
		double *	z,
		int *	panSuccess
	)

Transforms point based on GCP derived polynomial model.

This function matches the GDALTransformerFunc signature, and can be used to transform one or more points from pixel/line coordinates to georeferenced coordinates (SrcToDst) or vice versa (DstToSrc).

Parameters

pTransformArg	return value from GDALCreateTPSTransformer().
bDstToSrc	TRUE if transformation is from the destination (georeferenced) coordinates to pixel/line or FALSE when transforming from pixel/line to georeferenced coordinates.
nPointCount	the number of values in the x, y and z arrays.
x	array containing the X values to be transformed.
y	array containing the Y values to be transformed.
z	array containing the Z values to be transformed.
panSuccess	array in which a flag indicating success (TRUE) or failure (FALSE) of the transformation are placed.

Returns: TRUE.

◆ GDALTransformGeolocations()

CPLErr GDALTransformGeolocations	(	GDALRasterBandH	hXBand,
		GDALRasterBandH	hYBand,
		GDALRasterBandH	hZBand,
		GDALTransformerFunc	pfnTransformer,
		void *	pTransformArg,
		GDALProgressFunc	pfnProgress,
		void *	pProgressArg,
		char **	papszOptions
	)

Transform locations held in bands.

The X/Y and possibly Z values in the identified bands are transformed using a spatial transformer. The changed values are written back to the source bands so they need to be updateable.

Parameters

hXBand	the band containing the X locations (usually long/easting).
hYBand	the band containing the Y locations (usually lat/northing).
hZBand	the band containing the Z locations (may be NULL).
pfnTransformer	the transformer function.
pTransformArg	the callback data for the transformer function.
pfnProgress	callback for reporting algorithm progress matching the GDALProgressFunc() semantics. May be NULL.
pProgressArg	callback argument passed to pfnProgress.
papszOptions	list of name/value options - none currently supported.

Returns: CE_None on success or CE_Failure if an error occurs.

◆ GDALTriangulationComputeBarycentricCoefficients()

int GDALTriangulationComputeBarycentricCoefficients	(	GDALTriangulation *	psDT,
		const double *	padfX,
		const double *	padfY
	)

Computes barycentric coefficients for each triangles of the triangulation.

Parameters

psDT	triangulation.
padfX	x coordinates of the points. Must be identical to the one passed to GDALTriangulationCreateDelaunay().
padfY	y coordinates of the points. Must be identical to the one passed to GDALTriangulationCreateDelaunay().

Returns: TRUE in case of success.

Since: GDAL 2.1

◆ GDALTriangulationComputeBarycentricCoordinates()

int GDALTriangulationComputeBarycentricCoordinates	(	const GDALTriangulation *	psDT,
		int	nFacetIdx,
		double	dfX,
		double	dfY,
		double *	pdfL1,
		double *	pdfL2,
		double *	pdfL3
	)

Computes the barycentric coordinates of a point.

Parameters

psDT	triangulation.
nFacetIdx	index of the triangle in the triangulation
dfX	x coordinate of the point.
dfY	y coordinate of the point.
pdfL1	(output) pointer to the 1st barycentric coordinate.
pdfL2	(output) pointer to the 2nd barycentric coordinate.
pdfL3	(output) pointer to the 2nd barycentric coordinate.

Returns: TRUE in case of success.

Since: GDAL 2.1

◆ GDALTriangulationCreateDelaunay()

GDALTriangulation * GDALTriangulationCreateDelaunay	(	int	nPoints,
		const double *	padfX,
		const double *	padfY
	)

Computes a Delaunay triangulation of the passed points.

Parameters

nPoints	number of points
padfX	x coordinates of the points.
padfY	y coordinates of the points.

Returns: triangulation that must be freed with GDALTriangulationFree(), or NULL in case of error.

Since: GDAL 2.1

◆ GDALTriangulationFindFacetBruteForce()

int GDALTriangulationFindFacetBruteForce	(	const GDALTriangulation *	psDT,
		double	dfX,
		double	dfY,
		int *	panOutputFacetIdx
	)

Returns the index of the triangle that contains the point by iterating over all triangles.

If the function returns FALSE and *panOutputFacetIdx >= 0, then it means the point is outside the hull of the triangulation, and *panOutputFacetIdx is the closest triangle to the point.

Parameters

psDT	triangulation.
dfX	x coordinate of the point.
dfY	y coordinate of the point.
panOutputFacetIdx	(output) pointer to the index of the triangle, or -1 in case of failure.

Returns: index >= 0 of the triangle in case of success, -1 otherwise.

Since: GDAL 2.1

◆ GDALTriangulationFindFacetDirected()

int GDALTriangulationFindFacetDirected	(	const GDALTriangulation *	psDT,
		int	nFacetIdx,
		double	dfX,
		double	dfY,
		int *	panOutputFacetIdx
	)

Returns the index of the triangle that contains the point by walking in the triangulation.

If the function returns FALSE and *panOutputFacetIdx >= 0, then it means the point is outside the hull of the triangulation, and *panOutputFacetIdx is the closest triangle to the point.

Parameters

psDT	triangulation.
nFacetIdx	index of first triangle to start with. Must be >= 0 && < psDT->nFacets
dfX	x coordinate of the point.
dfY	y coordinate of the point.
panOutputFacetIdx	(output) pointer to the index of the triangle, or -1 in case of failure.

Returns: TRUE in case of success, FALSE otherwise.

Since: GDAL 2.1

◆ GDALTriangulationFree()

void GDALTriangulationFree ( GDALTriangulation * psDT )

Free a triangulation.

Parameters

psDT	triangulation.

Since: GDAL 2.1

◆ GDALViewshedGenerate()

GDALDatasetH GDALViewshedGenerate	(	GDALRasterBandH	hBand,
		const char *	pszDriverName,
		const char *	pszTargetRasterName,
		CSLConstList	papszCreationOptions,
		double	dfObserverX,
		double	dfObserverY,
		double	dfObserverHeight,
		double	dfTargetHeight,
		double	dfVisibleVal,
		double	dfInvisibleVal,
		double	dfOutOfRangeVal,
		double	dfNoDataVal,
		double	dfCurvCoeff,
		GDALViewshedMode	eMode,
		double	dfMaxDistance,
		GDALProgressFunc	pfnProgress,
		void *	pProgressArg,
		GDALViewshedOutputType	heightMode,
		CSLConstList	papszExtraOptions
	)

Create viewshed from raster DEM.

This algorithm will generate a viewshed raster from an input DEM raster by using a modified algorithm of "Generating Viewsheds without Using Sightlines" published at https://www.asprs.org/wp-content/uploads/pers/2000journal/january/2000_jan_87-90.pdf This appoach provides a relatively fast calculation, since the output raster is generated in a single scan. The gdal/apps/gdal_viewshed.cpp mainline can be used as an example of how to use this function. The output raster will be of type Byte or Float64.

Note: The algorithm as implemented currently will only output meaningful results if the georeferencing is in a projected coordinate reference system.

Parameters

hBand	The band to read the DEM data from. Only the part of the raster within the specified maxdistance around the observer point is processed.
pszDriverName	Driver name (GTiff if set to NULL)
pszTargetRasterName	The name of the target raster to be generated. Must not be NULL
papszCreationOptions	creation options.
dfObserverX	observer X value (in SRS units)
dfObserverY	observer Y value (in SRS units)
dfObserverHeight	The height of the observer above the DEM surface.
dfTargetHeight	The height of the target above the DEM surface. (default 0)
dfVisibleVal	pixel value for visibility (default 255)
dfInvisibleVal	pixel value for invisibility (default 0)
dfOutOfRangeVal	The value to be set for the cells that fall outside of the range specified by dfMaxDistance.
dfNoDataVal	The value to be set for the cells that have no data. If set to a negative value, nodata is not set. Note: currently, no special processing of input cells at a nodata value is done (which may result in erroneous results).
dfCurvCoeff	Coefficient to consider the effect of the curvature and refraction. The height of the DEM is corrected according to the following formula: [Height] -= dfCurvCoeff * [Target Distance]^2 / [Earth Diameter] For the effect of the atmospheric refraction we can use 0.85714.
eMode	The mode of the viewshed calculation. Possible values GVM_Diagonal = 1, GVM_Edge = 2 (default), GVM_Max = 3, GVM_Min = 4.
dfMaxDistance	maximum distance range to compute viewshed. It is also used to clamp the extent of the output raster. If set to 0, then unlimited range is assumed, that is to say the computation is performed on the extent of the whole raster.
pfnProgress	A GDALProgressFunc that may be used to report progress to the user, or to interrupt the algorithm. May be NULL if not required.
pProgressArg	The callback data for the pfnProgress function.
heightMode	Type of information contained in output raster. Possible values GVOT_NORMAL = 1 (default), GVOT_MIN_TARGET_HEIGHT_FROM_DEM = 2, GVOT_MIN_TARGET_HEIGHT_FROM_GROUND = 3

GVOT_NORMAL returns a raster of type Byte containing visible locations.

              GVOT_MIN_TARGET_HEIGHT_FROM_DEM and

GVOT_MIN_TARGET_HEIGHT_FROM_GROUND will return a raster of type Float64 containing the minimum target height for target to be visible from the DEM surface or ground level respectively. Parameters dfTargetHeight, dfVisibleVal and dfInvisibleVal will be ignored.

Parameters

papszExtraOptions Future extra options. Must be set to NULL currently.

Returns: not NULL output dataset on success (to be closed with GDALClose()) or NULL if an error occurs.

Since: GDAL 3.1

Classes

Macros

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ GDALTransformerFunc

Enumeration Type Documentation

◆ GDALGridAlgorithm

Function Documentation

◆ GDALApplyVerticalShiftGrid()

◆ GDALApproxTransform()

◆ GDALChecksumImage()

◆ GDALComputeMatchingPoints()

◆ GDALComputeMedianCutPCT()

◆ GDALComputeProximity()

◆ GDALContourGenerate()

◆ GDALContourGenerateEx()

◆ GDALCreateApproxTransformer()

◆ GDALCreateGCPTransformer()

◆ GDALCreateGenImgProjTransformer()

◆ GDALCreateGenImgProjTransformer2()

◆ GDALCreateGenImgProjTransformer3()

◆ GDALCreateGenImgProjTransformer4()

◆ GDALCreateReprojectionTransformer()

◆ GDALCreateReprojectionTransformerEx()

◆ GDALCreateRPCTransformerV2()

◆ GDALCreateTPSTransformer()

◆ GDALDestroyApproxTransformer()

◆ GDALDestroyGCPTransformer()

◆ GDALDestroyGenImgProjTransformer()

◆ GDALDestroyReprojectionTransformer()

◆ GDALDestroyTPSTransformer()

◆ GDALDitherRGB2PCT()

◆ GDALFillNodata()

◆ GDALFPolygonize()

◆ GDALGCPTransform()

◆ GDALGenImgProjTransform()

◆ GDALGetTransformerDstGeoTransform()

◆ GDALGridContextCreate()

◆ GDALGridContextFree()

◆ GDALGridContextProcess()

◆ GDALGridCreate()

◆ GDALHasTriangulation()

◆ GDALIsLineOfSightVisible()

◆ GDALOpenVerticalShiftGrid()

◆ GDALPolygonize()

◆ GDALRasterizeGeometries()

◆ GDALRasterizeGeometriesInt64()

◆ GDALRasterizeLayers()

◆ GDALRasterizeLayersBuf()

◆ GDALReprojectionTransform()

◆ GDALSetGenImgProjTransformerDstGeoTransform()

◆ GDALSetTransformerDstGeoTransform()

◆ GDALSieveFilter()

◆ GDALSimpleImageWarp()

◆ GDALSuggestedWarpOutput()

◆ GDALSuggestedWarpOutput2()

◆ GDALTPSTransform()

◆ GDALTransformGeolocations()

◆ GDALTriangulationComputeBarycentricCoefficients()

◆ GDALTriangulationComputeBarycentricCoordinates()

◆ GDALTriangulationCreateDelaunay()

◆ GDALTriangulationFindFacetBruteForce()

◆ GDALTriangulationFindFacetDirected()

◆ GDALTriangulationFree()

◆ GDALViewshedGenerate()