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.

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.

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:

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.

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.

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.

This algorithm 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.

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 segements. Then the contour crossings are connected.

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

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).

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.

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 the 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 center 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 inputs points are split into two smaller sets, and the function recursively called till a sufficiently small set of points if 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.

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 NULL) 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 with the provided gcp count will be used.

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).

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:

SRC_SRS: WKT SRS to be used as an override for hSrcDS.

DST_SRS: WKT SRS to be used as an override for hDstDS.

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 tolernace 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.

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.

DST_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 target dataset. Will be used for pixel/line to georef transformation on the destination dataset.

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.

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.

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).

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.

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.

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 exp ressing 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().

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.

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. (GDAL >= 1.8.0)

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 (GDAL >= 1.8.0)

RPC_DEMINTERPOLATION: the DEM interpolation (near, bilinear or cubic)

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. (GDAL >= 1.11.2)

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).

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 modelled 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).

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.

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). 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

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 (the temporary file driver can be specified like TEMP_FILE_DRIVER=MEM).

This function creates vector polygons for all connected regions of pixels in the raster sharing a common pixel value. Optionally each polygon may be labelled 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() at polygonize.cpp.

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.

papszOptions

a name/value list of additional options

"8CONNECTED": May be set to "8" to use 8 connectedness. Otherwise 4 connectedness will be applied to the algorithm

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

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).

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.

int GDALGenImgProjTransform

(

void *

pTransformArg,

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.

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 availabable 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.

Parameters:

eAlgorithm

Gridding method.

poOptions

Options to control choosen 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.

This function creates vector polygons for all connected regions of pixels in the raster sharing a common pixel value. Optionally each polygon may be labelled 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 32bit integer buffer (Int32), 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() at fpolygonize.cpp.

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.

papszOptions

a name/value list of additional options

"8CONNECTED": May be set to "8" to use 8 connectedness. Otherwise 4 connectedness will be applied to the algorithm

pfnProgress

callback for reporting algorithm progress matching the GDALProgressFunc() semantics. May be NULL.

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 georferenced 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, though currently internally the burning is done either as GDT_Byte or GDT_Float32. This may be improved in the future. 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.

padfGeomBurnValue

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.

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 georferenced 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, though currently internally the burning is done either as GDT_Byte or GDT_Float32. This may be improved in the future. 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.

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 georferenced 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, though currently internally the burning is done either as GDT_Byte or GDT_Float32. This may be improved in the future.

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.

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.

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.

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 isnt 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 images 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.