#include "gdal_version.h"
#include "cpl_port.h"
#include "cpl_error.h"
Go to the source code of this file.
Classes | |
struct | GDALOptionDefinition |
struct | GDAL_GCP |
struct | GDALRPCInfo |
struct | GDALColorEntry |
Defines | |
#define | CPLE_WrongFormat 200 |
#define | GDAL_DMD_LONGNAME "DMD_LONGNAME" |
#define | GDAL_DMD_HELPTOPIC "DMD_HELPTOPIC" |
#define | GDAL_DMD_MIMETYPE "DMD_MIMETYPE" |
#define | GDAL_DMD_EXTENSION "DMD_EXTENSION" |
#define | GDAL_DMD_CREATIONOPTIONLIST "DMD_CREATIONOPTIONLIST" |
#define | GDAL_DMD_CREATIONDATATYPES "DMD_CREATIONDATATYPES" |
#define | GDAL_DCAP_CREATE "DCAP_CREATE" |
#define | GDAL_DCAP_CREATECOPY "DCAP_CREATECOPY" |
Typedefs | |
typedef void * | GDALMajorObjectH |
typedef void * | GDALDatasetH |
typedef void * | GDALRasterBandH |
typedef void * | GDALDriverH |
typedef void * | GDALProjDefH |
typedef void * | GDALColorTableH |
typedef int(* | GDALProgressFunc )(double, const char *, void *) |
Enumerations | |
enum | GDALDataType { GDT_Unknown = 0, GDT_Byte = 1, GDT_UInt16 = 2, GDT_Int16 = 3, GDT_UInt32 = 4, GDT_Int32 = 5, GDT_Float32 = 6, GDT_Float64 = 7, GDT_CInt16 = 8, GDT_CInt32 = 9, GDT_CFloat32 = 10, GDT_CFloat64 = 11, GDT_TypeCount = 12 } |
enum | GDALAccess { GA_ReadOnly = 0, GA_Update = 1 } |
enum | GDALRWFlag { GF_Read = 0, GF_Write = 1 } |
enum | GDALColorInterp { GCI_Undefined = 0, GCI_GrayIndex = 1, GCI_PaletteIndex = 2, GCI_RedBand = 3, GCI_GreenBand = 4, GCI_BlueBand = 5, GCI_AlphaBand = 6, GCI_HueBand = 7, GCI_SaturationBand = 8, GCI_LightnessBand = 9, GCI_CyanBand = 10, GCI_MagentaBand = 11, GCI_YellowBand = 12, GCI_BlackBand = 13, GCI_YCbCr_YBand = 14, GCI_YCbCr_CbBand = 15, GCI_YCbCr_CrBand = 16, GCI_Max = 16 } |
enum | GDALPaletteInterp { GPI_Gray = 0, GPI_RGB = 1, GPI_CMYK = 2, GPI_HLS = 3 } |
Functions | |
int | GDALGetDataTypeSize (GDALDataType) |
int | GDALDataTypeIsComplex (GDALDataType) |
const char * | GDALGetDataTypeName (GDALDataType) |
GDALDataType | GDALGetDataTypeByName (const char *) |
GDALDataType | GDALDataTypeUnion (GDALDataType, GDALDataType) |
const char * | GDALGetColorInterpretationName (GDALColorInterp) |
const char * | GDALGetPaletteInterpretationName (GDALPaletteInterp) |
int | GDALDummyProgress (double, const char *, void *) |
int | GDALTermProgress (double, const char *, void *) |
int | GDALScaledProgress (double, const char *, void *) |
void * | GDALCreateScaledProgress (double, double, GDALProgressFunc, void *) |
void | GDALDestroyScaledProgress (void *) |
void | GDALAllRegister (void) |
GDALDatasetH | GDALCreate (GDALDriverH hDriver, const char *, int, int, int, GDALDataType, char **) |
GDALDatasetH | GDALCreateCopy (GDALDriverH, const char *, GDALDatasetH, int, char **, GDALProgressFunc, void *) |
GDALDatasetH | GDALOpen (const char *pszFilename, GDALAccess eAccess) |
GDALDatasetH | GDALOpenShared (const char *, GDALAccess) |
int | GDALDumpOpenDatasets (FILE *) |
GDALDriverH | GDALGetDriverByName (const char *) |
int | GDALGetDriverCount () |
GDALDriverH | GDALGetDriver (int) |
int | GDALRegisterDriver (GDALDriverH) |
void | GDALDeregisterDriver (GDALDriverH) |
void | GDALDestroyDriverManager (void) |
CPLErr | GDALDeleteDataset (GDALDriverH, const char *) |
const char * | GDALGetDriverShortName (GDALDriverH) |
const char * | GDALGetDriverLongName (GDALDriverH) |
const char * | GDALGetDriverHelpTopic (GDALDriverH) |
void | GDALInitGCPs (int, GDAL_GCP *) |
void | GDALDeinitGCPs (int, GDAL_GCP *) |
GDAL_GCP * | GDALDuplicateGCPs (int, const GDAL_GCP *) |
int | GDALGCPsToGeoTransform (int nGCPCount, const GDAL_GCP *pasGCPs, double *padfGeoTransform, int bApproxOK) |
int | GDALInvGeoTransform (double *padfGeoTransformIn, double *padfInvGeoTransformOut) |
void | GDALApplyGeoTransform (double *, double, double, double *, double *) |
char ** | GDALGetMetadata (GDALMajorObjectH, const char *) |
CPLErr | GDALSetMetadata (GDALMajorObjectH, char **, const char *) |
const char * | GDALGetMetadataItem (GDALMajorObjectH, const char *, const char *) |
CPLErr | GDALSetMetadataItem (GDALMajorObjectH, const char *, const char *, const char *) |
const char * | GDALGetDescription (GDALMajorObjectH) |
void | GDALSetDescription (GDALMajorObjectH, const char *) |
GDALDriverH | GDALGetDatasetDriver (GDALDatasetH) |
void | GDALClose (GDALDatasetH) |
int | GDALGetRasterXSize (GDALDatasetH) |
int | GDALGetRasterYSize (GDALDatasetH) |
int | GDALGetRasterCount (GDALDatasetH) |
GDALRasterBandH | GDALGetRasterBand (GDALDatasetH, int) |
CPLErr | GDALAddBand (GDALDatasetH hDS, GDALDataType eType, char **papszOptions) |
CPLErr | GDALDatasetRasterIO (GDALDatasetH hDS, GDALRWFlag eRWFlag, int nDSXOff, int nDSYOff, int nDSXSize, int nDSYSize, void *pBuffer, int nBXSize, int nBYSize, GDALDataType eBDataType, int nBandCount, int *panBandCount, int nPixelSpace, int nLineSpace, int nBandSpace) |
CPLErr | GDALDatasetAdviseRead (GDALDatasetH hDS, int nDSXOff, int nDSYOff, int nDSXSize, int nDSYSize, int nBXSize, int nBYSize, GDALDataType eBDataType, int nBandCount, int *panBandCount, char **papszOptions) |
const char * | GDALGetProjectionRef (GDALDatasetH) |
CPLErr | GDALSetProjection (GDALDatasetH, const char *) |
CPLErr | GDALGetGeoTransform (GDALDatasetH, double *) |
CPLErr | GDALSetGeoTransform (GDALDatasetH, double *) |
int | GDALGetGCPCount (GDALDatasetH) |
const char * | GDALGetGCPProjection (GDALDatasetH) |
const GDAL_GCP * | GDALGetGCPs (GDALDatasetH) |
CPLErr | GDALSetGCPs (GDALDatasetH, int, const GDAL_GCP *, const char *) |
void * | GDALGetInternalHandle (GDALDatasetH, const char *) |
int | GDALReferenceDataset (GDALDatasetH) |
int | GDALDereferenceDataset (GDALDatasetH) |
CPLErr | GDALBuildOverviews (GDALDatasetH, const char *, int, int *, int, int *, GDALProgressFunc, void *) |
void | GDALGetOpenDatasets (GDALDatasetH ***hDS, int *pnCount) |
int | GDALGetAccess (GDALDatasetH hDS) |
void | GDALFlushCache (GDALDatasetH hDS) |
GDALDataType | GDALGetRasterDataType (GDALRasterBandH) |
void | GDALGetBlockSize (GDALRasterBandH, int *pnXSize, int *pnYSize) |
CPLErr | GDALRasterAdviseRead (GDALRasterBandH hRB, int nDSXOff, int nDSYOff, int nDSXSize, int nDSYSize, int nBXSize, int nBYSize, GDALDataType eBDataType, char **papszOptions) |
CPLErr | GDALRasterIO (GDALRasterBandH hRBand, GDALRWFlag eRWFlag, int nDSXOff, int nDSYOff, int nDSXSize, int nDSYSize, void *pBuffer, int nBXSize, int nBYSize, GDALDataType eBDataType, int nPixelSpace, int nLineSpace) |
CPLErr | GDALReadBlock (GDALRasterBandH, int, int, void *) |
CPLErr | GDALWriteBlock (GDALRasterBandH, int, int, void *) |
int | GDALGetRasterBandXSize (GDALRasterBandH) |
int | GDALGetRasterBandYSize (GDALRasterBandH) |
char ** | GDALGetRasterMetadata (GDALRasterBandH) |
GDALAccess | GDALGetRasterAccess (GDALRasterBandH) |
int | GDALGetBandNumber (GDALRasterBandH) |
GDALDatasetH | GDALGetBandDataset (GDALRasterBandH) |
GDALColorInterp | GDALGetRasterColorInterpretation (GDALRasterBandH) |
CPLErr | GDALSetRasterColorInterpretation (GDALRasterBandH, GDALColorInterp) |
GDALColorTableH | GDALGetRasterColorTable (GDALRasterBandH) |
CPLErr | GDALSetRasterColorTable (GDALRasterBandH, GDALColorTableH) |
int | GDALHasArbitraryOverviews (GDALRasterBandH) |
int | GDALGetOverviewCount (GDALRasterBandH) |
GDALRasterBandH | GDALGetOverview (GDALRasterBandH, int) |
double | GDALGetRasterNoDataValue (GDALRasterBandH, int *) |
CPLErr | GDALSetRasterNoDataValue (GDALRasterBandH, double) |
char ** | GDALGetRasterCategoryNames (GDALRasterBandH) |
CPLErr | GDALSetRasterCategoryNames (GDALRasterBandH, char **) |
double | GDALGetRasterMinimum (GDALRasterBandH, int *pbSuccess) |
double | GDALGetRasterMaximum (GDALRasterBandH, int *pbSuccess) |
const char * | GDALGetRasterUnitType (GDALRasterBandH) |
double | GDALGetRasterOffset (GDALRasterBandH, int *pbSuccess) |
double | GDALGetRasterScale (GDALRasterBandH, int *pbSuccess) |
void | GDALComputeRasterMinMax (GDALRasterBandH hBand, int bApproxOK, double adfMinMax[2]) |
CPLErr | GDALFlushRasterCache (GDALRasterBandH hBand) |
CPLErr | GDALGetRasterHistogram (GDALRasterBandH hBand, double dfMin, double dfMax, int nBuckets, int *panHistogram, int bIncludeOutOfRange, int bApproxOK, GDALProgressFunc pfnProgress, void *pProgressData) |
int | GDALGetRandomRasterSample (GDALRasterBandH, int, float *) |
GDALRasterBandH | GDALGetRasterSampleOverview (GDALRasterBandH, int) |
CPLErr | GDALFillRaster (GDALRasterBandH hBand, double dfRealValue, double dfImaginaryValue) |
CPLErr | GDALComputeBandStats (GDALRasterBandH hBand, int nSampleStep, double *pdfMean, double *pdfStdDev, GDALProgressFunc pfnProgress, void *pProgressData) |
CPLErr | GDALOverviewMagnitudeCorrection (GDALRasterBandH hBaseBand, int nOverviewCount, GDALRasterBandH *pahOverviews, GDALProgressFunc pfnProgress, void *pProgressData) |
int | GDALGeneralCmdLineProcessor (int nArgc, char ***ppapszArgv, int nOptions) |
void | GDALSwapWords (void *pData, int nWordSize, int nWordCount, int nWordSkip) |
void | GDALCopyWords (void *pSrcData, GDALDataType eSrcType, int nSrcPixelOffset, void *pDstData, GDALDataType eDstType, int nDstPixelOffset, int nWordCount) |
int | GDALReadWorldFile (const char *pszBaseFilename, const char *pszExtension, double *padfGeoTransform) |
int | GDALWriteWorldFile (const char *pszBaseFilename, const char *pszExtension, double *padfGeoTransform) |
int | GDALReadTabFile (const char *pszBaseFilename, double *padfGeoTransform, char **ppszWKT, int *pnGCPCount, GDAL_GCP **ppasGCPs) |
const char * | GDALDecToDMS (double, const char *, int) |
double | GDALPackedDMSToDec (double) |
double | GDALDecToPackedDMS (double) |
const char * | GDALVersionInfo (const char *) |
int | GDALExtractRPCInfo (char **, GDALRPCInfo *) |
GDALColorTableH | GDALCreateColorTable (GDALPaletteInterp) |
void | GDALDestroyColorTable (GDALColorTableH) |
GDALColorTableH | GDALCloneColorTable (GDALColorTableH) |
GDALPaletteInterp | GDALGetPaletteInterpretation (GDALColorTableH) |
int | GDALGetColorEntryCount (GDALColorTableH) |
const GDALColorEntry * | GDALGetColorEntry (GDALColorTableH, int) |
int | GDALGetColorEntryAsRGB (GDALColorTableH, int, GDALColorEntry *) |
void | GDALSetColorEntry (GDALColorTableH, int, const GDALColorEntry *) |
void | GDALSetCacheMax (int nBytes) |
int | GDALGetCacheMax () |
int | GDALGetCacheUsed () |
int | GDALFlushCacheBlock () |
|
GDALProcessFunc is a typedef defining the signature of functions to be used with GDAL as callbacks to report the progress of long running processes. Typically these are functions that would update a GUI progress bar showing how much of a process is done. A number of GDAL functions and methods accept GDALProcessFunc arguments along with an opaque application supplied data item (pProgressArg) which are then used to implement progress reporting. The GDALDataset::BuildOverviews(), and GDALDriver::CreateCopy() methods are examples of two methods that utilize the progress semantics.
int (*GDALProgressFunc)(double dfComplete, const char *pszMessage, void *pProgressArg);
int MyTextProgress( double dfComplete, const char *pszMessage, void *pData) { if( pszMessage != NULL ) printf( "%d%% complete: %s\n", (int) (dfComplete*100), pszMessage ); else if( pData != NULL ) printf( "%d%% complete:%s\n", (int) (dfComplete*100), (char) pData ); else printf( "%d%% complete.\n", (int) (dfComplete*100) ); return TRUE; } This could be utilized with the GDALDataset::BuildOverviews() method like this:
int anOverviewList[3] = {2, 4, 8}; poDataset->BuildOverviews( "NEAREST", 3, anOverviewList, 0, NULL, MyTextProgress, "building overviews" ); In addition to reporting progress to the user, the GDALProcessFunc mechanism also provides a mechanism for a user interface to return a request from the user to cancel the operation to the algorithm via the return value. If FALSE is returned, the algorithm should terminate the operation and return as quickly as possible. More often that implementing custom progress functions, applications will just use existing progress functions like GDALDummyProgress(), GDALTermProgress() and GDALScaledProgress(). Python scripts also can pass progress functions. Application code implementing GDALProgressFunc semantics should remember a few things:
|
|
Flag indicating read/write, or read-only access to data. |
|
|
Pixel data types
|
|
Types of color interpretations for a GDALColorTable.
|
|
Read/Write flag for RasterIO() method |
|
|
|
Register all known configured GDAL drivers. This function will drive any of the following that are configured into GDAL. Possible others as well that haven't been updated in this documentation:
|
|
Apply GeoTransform to x/y coordinate. Applies the following computation, converting a (pixel,line) coordinate into a georeferenced (geo_x,geo_y) location. *pdfGeoX = padfGeoTransform[0] + dfPixel * padfGeoTransform[1] + dfLine * padfGeoTransform[2]; *pdfGeoY = padfGeoTransform[3] + dfPixel * padfGeoTransform[4] + dfLine * padfGeoTransform[5];
|
|
|
|
Close GDAL dataset. For non-shared datasets (opened with GDALOpen()) the dataset is closed using the C++ "delete" operator, recovering all dataset related resources. For shared datasets (opened with GDALOpenShared()) the dataset is dereferenced, and closed only if the referenced count has dropped below 1.
|
|
Compute the min/max values for a band. If approximate is OK, then the band's GetMinimum()/GetMaximum() will be trusted. If it doesn't work, a subsample of blocks will be read to get an approximate min/max. If the band has a nodata value it will be excluded from the minimum and maximum. If bApprox is FALSE, then all pixels will be read and used to compute an exact range.
|
|
Copy pixel words from buffer to buffer. This function is used to copy pixel word values from one memory buffer to another, with support for conversion between data types, and differing step factors. The data type conversion is done using the normal GDAL rules. Values assigned to a lower range integer type are clipped. For instance assigning GDT_Int16 values to a GDT_Byte buffer will cause values less the 0 to be set to 0, and values larger than 255 to be set to 255. Assignment from floating point to integer uses default C type casting semantics. Assignment from non-complex to complex will result in the imaginary part being set to zero on output. Assigment from complex to non-complex will result in the complex portion being lost and the real component being preserved (not magnitidue!). No assumptions are made about the source or destination words occuring on word boundaries. It is assumed that all values are in native machine byte order.
|
|
|
|
|
|
Create scaled progress transformer. Sometimes when an operations wants to report progress it actually invokes several subprocesses which also take GDALProgressFunc()s, and it is desirable to map the progress of each sub operation into a portion of 0.0 to 1.0 progress of the overall process. The scaled progress function can be used for this. For each subsection a scaled progress function is created and instead of passing the overall progress func down to the sub functions, the GDALScaledProgress() function is passed instead.
int MyOperation( ..., GDALProgressFunc pfnProgress, void *pProgressData ); { void *pScaledProgress; pScaledProgress = GDALCreateScaledProgress( 0.0, 0.5, pfnProgress, pProgressData ); GDALDoLongSlowOperation( ..., GDALScaledProgressFunc, pProgressData ); GDALDestroyScaledProgress( pScaledProgress ); pScaledProgress = GDALCreateScaledProgress( 0.5, 1.0, pfnProgress, pProgressData ); GDALDoAnotherOperation( ..., GDALScaledProgressFunc, pProgressData ); GDALDestroyScaledProgress( pScaledProgress ); return ...; } |
|
|
|
Is data type complex?
|
|
Return the smallest data type that can fully express both input data types.
|
|
Convert decimal degrees into packed DMS value (DDDMMMSSS.SS). See CPLDecToPackedDMS(). |
|
|
|
|
|
|
|
Destroy the driver manager. Incidently unloads all managed drivers. |
|
Cleanup scaled progress handle. This function cleans up the data associated with a scaled progress function as returned by GADLCreateScaledProgress().
|
|
Stub progress function. This is a stub (does nothing) implementation of the GDALProgressFunc() semantics. It is primarily useful for passing to functions that take a GDALProgressFunc() argument but for which the application does not want to use one of the other progress functions that actually do something. |
|
List open datasets. Dumps a list of all open datasets (shared or not) to the indicated text file (may be stdout or stderr). This function is primariliy intended to assist in debugging "dataset leaks" and reference counting issues. The information reported includes the dataset name, referenced count, shared status, driver name, size, and band count. |
|
Fill this band with a constant value. Set dfImaginaryValue to zero non-complex rasters.
|
|
|
|
|
|
Generate Geotransform from GCPs. Given a set of GCPs perform first order fit as a geotransform.
|
|
General utility option processing. This function is intended to provide a variety of generic commandline options for all GDAL commandline utilities. It takes care of the following commandline options: --version: report version of GDAL in use. --formats: report all format drivers configured. --format [format]: report details of one format driver. --optfile filename: expand an option file into the argument list. --config key value: set system configuration option. --debug [on/off/value]: set debug level. --help-general: report detailed help on general options. The argument array is replaced "in place" and should be freed with CSLDestroy() when no longer needed. The typical usage looks something like the following. Note that the formats should be registered so that the --formats and --format options will work properly. int main( int argc, char ** argv ) { GDALAllRegister(); argc = GDALGeneralCmdLineProcessor( argc, &argv, 0 ); if( argc < 1 ) exit( -argc );
|
|
|
|
|
|
|
|
|
|
Get maximum cache memory. Gets the maximum amount of memory available to the GDALRasterBlock caching system for caching GDAL read/write imagery.
|
|
Get cache memory used.
|
|
Translate a GDALColorInterp into a user displayable string. |
|
|
|
Get data type by symbolic name. Returns a data type corresponding to the given symbolic name. This function is opposite to the GDALGetDataTypeName().
|
|
Get name of data type. Returns a symbolic name for the data type. This is essentially the the enumerated item name with the GDT_ prefix removed. So GDT_Byte returns "Byte". The returned strings are static strings and should not be modified or freed by the application. These strings are useful for reporting datatypes in debug statements, errors and other user output.
|
|
Get data type size in bits. Returns the size of a a GDT_* type in bits, not bytes!
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Translate a GDALPaletteInterp into a user displayable string. |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Fetch best sampling overview. Returns the most reduced overview of the given band that still satisfies the desired number of samples. This function can be used with zero as the number of desired samples to fetch the most reduced overview. The same band as was passed in will be returned if it has not overviews, or if none of the overviews have enough samples.
|
|
|
|
|
|
|
|
|
|
Invert Geotransform. This function will invert a standard 3x2 set of GeoTransform coefficients. This converts the equation from being pixel to geo to being geo to pixel.
|
|
Open a raster file as a GDALDataset. See Also: GDALOpenShared()
|
|
Open a raster file as a GDALDataset. This function works the same as GDALOpen(), but allows the sharing of GDALDataset handles for a dataset with other callers to GDALOpenShared(). In particular, GDALOpenShared() will first consult it's list of currently open and shared GDALDataset's, and if the GetDescription() name for one exactly matches the pszFilename passed to GDALOpenShared() it
|
|
Convert a packed DMS value (DDDMMMSSS.SS) into decimal degrees. See CPLPackedDMSToDec(). |
|
|
|
|
|
Read ESRI world file. This function reads an ESRI style world file, and formats a geotransform from it's contents. It will form the filename for the worldfile from the filename of the raster file referred and the suggested extension. If no extension is provided, the code will internally try the unix style and windows style world file extensions (eg. for .tif these would be .tfw and .tifw). The world file contains an affine transformation with the parameters in a different order than in a geotransform array. geotransform[1] - width of pixel geotransform[4] - rotational coefficient, zero for north up images. geotransform[2] - rotational coefficient, zero for north up images. geotransform[5] - height of pixel (but negative) geotransform[0] - x offset to center of top left pixel. geotrasnform[3] - y offset to center of top left pixel.
|
|
|
|
|
|
Scaled progress transformer. This is the progress function that should be passed along with the callback data returned by GDALCreateScaledProgress(). |
|
Set maximum cache memory. This function sets the maximum amount of memory that GDAL is permitted to use for GDALRasterBlock caching.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Byte swap words in-place. This function will byte swap a set of 2, 4 or 8 byte words "in place" in a memory array. No assumption is made that the words being swapped are word aligned in memory. Use the CPL_LSB and CPL_MSB macros from cpl_port.h to determine if the current platform is big endian or little endian. Use The macros like CPL_SWAP32() to byte swap single values without the overhead of a function call.
|
|
Simple progress report to terminal. This progress reporter prints simple progress report to the terminal window. The progress report generally looks something like this:
0...10...20...30...40...50...60...70...80...90...100 - done. Every 2.5% of progress another number or period is emitted. Note that GDALTermProgress() uses internal static data to keep track of the last percentage reported and will get confused if two terminal based progress reportings are active at the same time.
|
|
Get runtime version information. Available pszRequest values:
|
|
|