gdal_utils.h: GDAL Algorithms C API

Public (C callable) GDAL Utilities entry points.

Since

GDAL 2.1

Typedefs

typedef struct GDALInfoOptions GDALInfoOptions

Options for GDALInfo(). Opaque type

typedef struct GDALInfoOptionsForBinary GDALInfoOptionsForBinary

Opaque type.

typedef struct GDALTranslateOptions GDALTranslateOptions

Options for GDALTranslate(). Opaque type

typedef struct GDALTranslateOptionsForBinary GDALTranslateOptionsForBinary

Opaque type.

typedef struct GDALWarpAppOptions GDALWarpAppOptions

Options for GDALWarp(). Opaque type

typedef struct GDALWarpAppOptionsForBinary GDALWarpAppOptionsForBinary

Opaque type.

typedef struct GDALVectorTranslateOptions GDALVectorTranslateOptions

Options for GDALVectorTranslate(). Opaque type

typedef struct GDALVectorTranslateOptionsForBinary GDALVectorTranslateOptionsForBinary

Opaque type.

typedef struct GDALDEMProcessingOptions GDALDEMProcessingOptions

Options for GDALDEMProcessing(). Opaque type

typedef struct GDALDEMProcessingOptionsForBinary GDALDEMProcessingOptionsForBinary

Opaque type.

typedef struct GDALNearblackOptions GDALNearblackOptions

Options for GDALNearblack(). Opaque type

typedef struct GDALNearblackOptionsForBinary GDALNearblackOptionsForBinary

Opaque type.

typedef struct GDALGridOptions GDALGridOptions

Options for GDALGrid(). Opaque type

typedef struct GDALGridOptionsForBinary GDALGridOptionsForBinary

Opaque type.

typedef struct GDALRasterizeOptions GDALRasterizeOptions

Options for GDALRasterize(). Opaque type

typedef struct GDALRasterizeOptionsForBinary GDALRasterizeOptionsForBinary

Opaque type.

typedef struct GDALFootprintOptions GDALFootprintOptions

Options for GDALFootprint(). Opaque type

typedef struct GDALFootprintOptionsForBinary GDALFootprintOptionsForBinary

Opaque type.

typedef struct GDALBuildVRTOptions GDALBuildVRTOptions

Options for GDALBuildVRT(). Opaque type

typedef struct GDALBuildVRTOptionsForBinary GDALBuildVRTOptionsForBinary

Opaque type.

typedef struct GDALMultiDimInfoOptions GDALMultiDimInfoOptions

Options for GDALMultiDimInfo(). Opaque type

typedef struct GDALMultiDimInfoOptionsForBinary GDALMultiDimInfoOptionsForBinary

Opaque type.

typedef struct GDALMultiDimTranslateOptions GDALMultiDimTranslateOptions

Options for GDALMultiDimTranslate(). Opaque type

typedef struct GDALMultiDimTranslateOptionsForBinary GDALMultiDimTranslateOptionsForBinary

Opaque type.

typedef struct GDALVectorInfoOptions GDALVectorInfoOptions

Options for GDALVectorInfo(). Opaque type

typedef struct GDALVectorInfoOptionsForBinary GDALVectorInfoOptionsForBinary

Opaque type.

typedef struct GDALTileIndexOptions GDALTileIndexOptions

Options for GDALTileIndex(). Opaque type

typedef struct GDALTileIndexOptionsForBinary GDALTileIndexOptionsForBinary

Opaque type.

Functions

GDALInfoOptions *GDALInfoOptionsNew(char **papszArgv, GDALInfoOptionsForBinary *psOptionsForBinary)

Allocates a GDALInfoOptions struct.

Since

GDAL 2.1

Parameters:
  • papszArgv -- NULL terminated list of options (potentially including filename and open options too), or NULL. The accepted options are the ones of the gdalinfo utility.

  • psOptionsForBinary -- (output) may be NULL (and should generally be NULL), otherwise (gdalinfo_bin.cpp use case) must be allocated with GDALInfoOptionsForBinaryNew() prior to this function. Will be filled with potentially present filename, open options, subdataset number...

Returns:

pointer to the allocated GDALInfoOptions struct. Must be freed with GDALInfoOptionsFree().

void GDALInfoOptionsFree(GDALInfoOptions *psOptions)

Frees the GDALInfoOptions struct.

Since

GDAL 2.1

Parameters:

psOptions -- the options struct for GDALInfo().

char *GDALInfo(GDALDatasetH hDataset, const GDALInfoOptions *psOptions)

Lists various information about a GDAL supported raster dataset.

This is the equivalent of the gdalinfo utility.

GDALInfoOptions* must be allocated and freed with GDALInfoOptionsNew() and GDALInfoOptionsFree() respectively.

Since

GDAL 2.1

Parameters:
  • hDataset -- the dataset handle.

  • psOptions -- the options structure returned by GDALInfoOptionsNew() or NULL.

Returns:

string corresponding to the information about the raster dataset (must be freed with CPLFree()), or NULL in case of error.

GDALTranslateOptions *GDALTranslateOptionsNew(char **papszArgv, GDALTranslateOptionsForBinary *psOptionsForBinary)

Allocates a GDALTranslateOptions struct.

Since

GDAL 2.1

Parameters:
  • papszArgv -- NULL terminated list of options (potentially including filename and open options too), or NULL. The accepted options are the ones of the gdal_translate utility.

  • psOptionsForBinary -- (output) may be NULL (and should generally be NULL), otherwise (gdal_translate_bin.cpp use case) must be allocated with GDALTranslateOptionsForBinaryNew() prior to this function. Will be filled with potentially present filename, open options,...

Returns:

pointer to the allocated GDALTranslateOptions struct. Must be freed with GDALTranslateOptionsFree().

void GDALTranslateOptionsFree(GDALTranslateOptions *psOptions)

Frees the GDALTranslateOptions struct.

Since

GDAL 2.1

Parameters:

psOptions -- the options struct for GDALTranslate().

void GDALTranslateOptionsSetProgress(GDALTranslateOptions *psOptions, GDALProgressFunc pfnProgress, void *pProgressData)

Set a progress function.

Since

GDAL 2.1

Parameters:
  • psOptions -- the options struct for GDALTranslate().

  • pfnProgress -- the progress callback.

  • pProgressData -- the user data for the progress callback.

GDALDatasetH GDALTranslate(const char *pszDestFilename, GDALDatasetH hSrcDataset, const GDALTranslateOptions *psOptions, int *pbUsageError)

Converts raster data between different formats.

This is the equivalent of the gdal_translate utility.

GDALTranslateOptions* must be allocated and freed with GDALTranslateOptionsNew() and GDALTranslateOptionsFree() respectively.

Since

GDAL 2.1

Parameters:
  • pszDest -- the destination dataset path.

  • hSrcDataset -- the source dataset handle.

  • psOptionsIn -- the options struct returned by GDALTranslateOptionsNew() or NULL.

  • pbUsageError -- pointer to a integer output variable to store if any usage error has occurred or NULL.

Returns:

the output dataset (new dataset that must be closed using GDALClose()) or NULL in case of error. If the output format is a VRT dataset, then the returned VRT dataset has a reference to hSrcDataset. Hence hSrcDataset should be closed after the returned dataset if using GDALClose(). A safer alternative is to use GDALReleaseDataset() instead of using GDALClose(), in which case you can close datasets in any order.

GDALWarpAppOptions *GDALWarpAppOptionsNew(char **papszArgv, GDALWarpAppOptionsForBinary *psOptionsForBinary)

Allocates a GDALWarpAppOptions struct.

Since

GDAL 2.1

Parameters:
  • papszArgv -- NULL terminated list of options (potentially including filename and open options too), or NULL. The accepted options are the ones of the gdalwarp utility.

  • psOptionsForBinary -- (output) may be NULL (and should generally be NULL), otherwise (gdal_translate_bin.cpp use case) must be allocated with GDALWarpAppOptionsForBinaryNew() prior to this function. Will be filled with potentially present filename, open options,...

Returns:

pointer to the allocated GDALWarpAppOptions struct. Must be freed with GDALWarpAppOptionsFree().

void GDALWarpAppOptionsFree(GDALWarpAppOptions *psOptions)

Frees the GDALWarpAppOptions struct.

Since

GDAL 2.1

Parameters:

psOptions -- the options struct for GDALWarp().

void GDALWarpAppOptionsSetProgress(GDALWarpAppOptions *psOptions, GDALProgressFunc pfnProgress, void *pProgressData)

Set a progress function.

Since

GDAL 2.1

Parameters:
  • psOptions -- the options struct for GDALWarp().

  • pfnProgress -- the progress callback.

  • pProgressData -- the user data for the progress callback.

void GDALWarpAppOptionsSetQuiet(GDALWarpAppOptions *psOptions, int bQuiet)

Set a progress function.

Since

GDAL 2.3

Parameters:
  • psOptions -- the options struct for GDALWarp().

  • bQuiet -- whether GDALWarp() should emit messages on stdout.

void GDALWarpAppOptionsSetWarpOption(GDALWarpAppOptions *psOptions, const char *pszKey, const char *pszValue)

Set a warp option.

Since

GDAL 2.1

Parameters:
  • psOptions -- the options struct for GDALWarp().

  • pszKey -- key.

  • pszValue -- value.

GDALDatasetH GDALWarp(const char *pszDest, GDALDatasetH hDstDS, int nSrcCount, GDALDatasetH *pahSrcDS, const GDALWarpAppOptions *psOptions, int *pbUsageError)

Image reprojection and warping function.

This is the equivalent of the gdalwarp utility.

GDALWarpAppOptions* must be allocated and freed with GDALWarpAppOptionsNew() and GDALWarpAppOptionsFree() respectively. pszDest and hDstDS cannot be used at the same time.

Since

GDAL 2.1

Parameters:
  • pszDest -- the destination dataset path or NULL.

  • hDstDS -- the destination dataset or NULL.

  • nSrcCount -- the number of input datasets.

  • pahSrcDS -- the list of input datasets. For practical purposes, the type of this argument should be considered as "const GDALDatasetH* const*", that is neither the array nor its values are mutated by this function.

  • psOptionsIn -- the options struct returned by GDALWarpAppOptionsNew() or NULL.

  • pbUsageError -- pointer to a integer output variable to store if any usage error has occurred, or NULL.

Returns:

the output dataset (new dataset that must be closed using GDALClose(), or hDstDS if not NULL) or NULL in case of error. If the output format is a VRT dataset, then the returned VRT dataset has a reference to pahSrcDS[0]. Hence pahSrcDS[0] should be closed after the returned dataset if using GDALClose(). A safer alternative is to use GDALReleaseDataset() instead of using GDALClose(), in which case you can close datasets in any order.

GDALVectorTranslateOptions *GDALVectorTranslateOptionsNew(char **papszArgv, GDALVectorTranslateOptionsForBinary *psOptionsForBinary)

allocates a GDALVectorTranslateOptions struct.

Since

GDAL 2.1

Parameters:
  • papszArgv -- NULL terminated list of options (potentially including filename and open options too), or NULL. The accepted options are the ones of the ogr2ogr utility.

  • psOptionsForBinary -- (output) may be NULL (and should generally be NULL), otherwise (gdal_translate_bin.cpp use case) must be allocated with GDALVectorTranslateOptionsForBinaryNew() prior to this function. Will be filled with potentially present filename, open options,...

Returns:

pointer to the allocated GDALVectorTranslateOptions struct. Must be freed with GDALVectorTranslateOptionsFree().

void GDALVectorTranslateOptionsFree(GDALVectorTranslateOptions *psOptions)

Frees the GDALVectorTranslateOptions struct.

Since

GDAL 2.1

Parameters:

psOptions -- the options struct for GDALVectorTranslate().

void GDALVectorTranslateOptionsSetProgress(GDALVectorTranslateOptions *psOptions, GDALProgressFunc pfnProgress, void *pProgressData)

Set a progress function.

Since

GDAL 2.1

Parameters:
  • psOptions -- the options struct for GDALVectorTranslate().

  • pfnProgress -- the progress callback.

  • pProgressData -- the user data for the progress callback.

GDALDatasetH GDALVectorTranslate(const char *pszDest, GDALDatasetH hDstDS, int nSrcCount, GDALDatasetH *pahSrcDS, const GDALVectorTranslateOptions *psOptions, int *pbUsageError)

Converts vector data between file formats.

This is the equivalent of the ogr2ogr utility.

GDALVectorTranslateOptions* must be allocated and freed with GDALVectorTranslateOptionsNew() and GDALVectorTranslateOptionsFree() respectively. pszDest and hDstDS cannot be used at the same time.

Since

GDAL 2.1

Parameters:
  • pszDest -- the destination dataset path or NULL.

  • hDstDS -- the destination dataset or NULL.

  • nSrcCount -- the number of input datasets (only 1 supported currently)

  • pahSrcDS -- the list of input datasets.

  • psOptionsIn -- the options struct returned by GDALVectorTranslateOptionsNew() or NULL.

  • pbUsageError -- pointer to a integer output variable to store if any usage error has occurred, or NULL.

Returns:

the output dataset (new dataset that must be closed using GDALClose(), or hDstDS is not NULL) or NULL in case of error.

GDALDEMProcessingOptions *GDALDEMProcessingOptionsNew(char **papszArgv, GDALDEMProcessingOptionsForBinary *psOptionsForBinary)

Allocates a GDALDEMProcessingOptions struct.

Since

GDAL 2.1

Parameters:
  • papszArgv -- NULL terminated list of options (potentially including filename and open options too), or NULL. The accepted options are the ones of the gdaldem utility.

  • psOptionsForBinary -- (output) may be NULL (and should generally be NULL), otherwise (gdal_translate_bin.cpp use case) must be allocated with GDALDEMProcessingOptionsForBinaryNew() prior to this function. Will be filled with potentially present filename, open options,...

Returns:

pointer to the allocated GDALDEMProcessingOptions struct. Must be freed with GDALDEMProcessingOptionsFree().

void GDALDEMProcessingOptionsFree(GDALDEMProcessingOptions *psOptions)

Frees the GDALDEMProcessingOptions struct.

Since

GDAL 2.1

Parameters:

psOptions -- the options struct for GDALDEMProcessing().

void GDALDEMProcessingOptionsSetProgress(GDALDEMProcessingOptions *psOptions, GDALProgressFunc pfnProgress, void *pProgressData)

Set a progress function.

Since

GDAL 2.1

Parameters:
  • psOptions -- the options struct for GDALDEMProcessing().

  • pfnProgress -- the progress callback.

  • pProgressData -- the user data for the progress callback.

GDALDatasetH GDALDEMProcessing(const char *pszDestFilename, GDALDatasetH hSrcDataset, const char *pszProcessing, const char *pszColorFilename, const GDALDEMProcessingOptions *psOptions, int *pbUsageError)

Apply a DEM processing.

This is the equivalent of the gdaldem utility.

GDALDEMProcessingOptions* must be allocated and freed with GDALDEMProcessingOptionsNew() and GDALDEMProcessingOptionsFree() respectively.

Since

GDAL 2.1

Parameters:
  • pszDest -- the destination dataset path.

  • hSrcDataset -- the source dataset handle.

  • pszProcessing -- the processing to apply (one of "hillshade", "slope", "aspect", "color-relief", "TRI", "TPI", "Roughness")

  • pszColorFilename -- color file (mandatory for "color-relief" processing, should be NULL otherwise)

  • psOptionsIn -- the options struct returned by GDALDEMProcessingOptionsNew() or NULL.

  • pbUsageError -- pointer to a integer output variable to store if any usage error has occurred or NULL.

Returns:

the output dataset (new dataset that must be closed using GDALClose()) or NULL in case of error.

GDALNearblackOptions *GDALNearblackOptionsNew(char **papszArgv, GDALNearblackOptionsForBinary *psOptionsForBinary)

Allocates a GDALNearblackOptions struct.

Since

GDAL 2.1

Parameters:
  • papszArgv -- NULL terminated list of options (potentially including filename and open options too), or NULL. The accepted options are the ones of the nearblack utility.

  • psOptionsForBinary -- (output) may be NULL (and should generally be NULL), otherwise (gdal_translate_bin.cpp use case) must be allocated with GDALNearblackOptionsForBinaryNew() prior to this function. Will be filled with potentially present filename, open options,...

Returns:

pointer to the allocated GDALNearblackOptions struct. Must be freed with GDALNearblackOptionsFree().

void GDALNearblackOptionsFree(GDALNearblackOptions *psOptions)

Frees the GDALNearblackOptions struct.

Since

GDAL 2.1

Parameters:

psOptions -- the options struct for GDALNearblack().

void GDALNearblackOptionsSetProgress(GDALNearblackOptions *psOptions, GDALProgressFunc pfnProgress, void *pProgressData)

Set a progress function.

Since

GDAL 2.1

Parameters:
  • psOptions -- the options struct for GDALNearblack().

  • pfnProgress -- the progress callback.

  • pProgressData -- the user data for the progress callback.

GDALDatasetH GDALNearblack(const char *pszDest, GDALDatasetH hDstDS, GDALDatasetH hSrcDS, const GDALNearblackOptions *psOptions, int *pbUsageError)

Convert nearly black/white borders to exact value.

This is the equivalent of the nearblack utility.

GDALNearblackOptions* must be allocated and freed with GDALNearblackOptionsNew() and GDALNearblackOptionsFree() respectively. pszDest and hDstDS cannot be used at the same time.

In-place update (i.e. hDstDS == hSrcDataset) is possible for formats that support it, and if the dataset is opened in update mode.

Since

GDAL 2.1

Parameters:
  • pszDest -- the destination dataset path or NULL.

  • hDstDS -- the destination dataset or NULL. Might be equal to hSrcDataset.

  • hSrcDataset -- the source dataset handle.

  • psOptionsIn -- the options struct returned by GDALNearblackOptionsNew() or NULL.

  • pbUsageError -- pointer to a integer output variable to store if any usage error has occurred or NULL.

Returns:

the output dataset (new dataset that must be closed using GDALClose(), or hDstDS when it is not NULL) or NULL in case of error.

GDALGridOptions *GDALGridOptionsNew(char **papszArgv, GDALGridOptionsForBinary *psOptionsForBinary)

Allocates a GDALGridOptions struct.

Since

GDAL 2.1

Parameters:
  • papszArgv -- NULL terminated list of options (potentially including filename and open options too), or NULL. The accepted options are the ones of the gdal_translate utility.

  • psOptionsForBinary -- (output) may be NULL (and should generally be NULL), otherwise (gdal_translate_bin.cpp use case) must be allocated with GDALGridOptionsForBinaryNew() prior to this function. Will be filled with potentially present filename, open options,...

Returns:

pointer to the allocated GDALGridOptions struct. Must be freed with GDALGridOptionsFree().

void GDALGridOptionsFree(GDALGridOptions *psOptions)

Frees the GDALGridOptions struct.

Since

GDAL 2.1

Parameters:

psOptions -- the options struct for GDALGrid().

void GDALGridOptionsSetProgress(GDALGridOptions *psOptions, GDALProgressFunc pfnProgress, void *pProgressData)

Set a progress function.

Since

GDAL 2.1

Parameters:
  • psOptions -- the options struct for GDALGrid().

  • pfnProgress -- the progress callback.

  • pProgressData -- the user data for the progress callback.

GDALDatasetH GDALGrid(const char *pszDest, GDALDatasetH hSrcDS, const GDALGridOptions *psOptions, int *pbUsageError)

Create raster from the scattered data.

This is the equivalent of the gdal_grid utility.

GDALGridOptions* must be allocated and freed with GDALGridOptionsNew() and GDALGridOptionsFree() respectively.

Since

GDAL 2.1

Parameters:
  • pszDest -- the destination dataset path.

  • hSrcDataset -- the source dataset handle.

  • psOptionsIn -- the options struct returned by GDALGridOptionsNew() or NULL.

  • pbUsageError -- pointer to a integer output variable to store if any usage error has occurred or NULL.

Returns:

the output dataset (new dataset that must be closed using GDALClose()) or NULL in case of error.

GDALRasterizeOptions *GDALRasterizeOptionsNew(char **papszArgv, GDALRasterizeOptionsForBinary *psOptionsForBinary)

Allocates a GDALRasterizeOptions struct.

Since

GDAL 2.1

Parameters:
  • papszArgv -- NULL terminated list of options (potentially including filename and open options too), or NULL. The accepted options are the ones of the gdal_rasterize utility.

  • psOptionsForBinary -- (output) may be NULL (and should generally be NULL), otherwise (gdal_translate_bin.cpp use case) must be allocated with GDALRasterizeOptionsForBinaryNew() prior to this function. Will be filled with potentially present filename, open options,...

Returns:

pointer to the allocated GDALRasterizeOptions struct. Must be freed with GDALRasterizeOptionsFree().

void GDALRasterizeOptionsFree(GDALRasterizeOptions *psOptions)

Frees the GDALRasterizeOptions struct.

Since

GDAL 2.1

Parameters:

psOptions -- the options struct for GDALRasterize().

void GDALRasterizeOptionsSetProgress(GDALRasterizeOptions *psOptions, GDALProgressFunc pfnProgress, void *pProgressData)

Set a progress function.

Since

GDAL 2.1

Parameters:
  • psOptions -- the options struct for GDALRasterize().

  • pfnProgress -- the progress callback.

  • pProgressData -- the user data for the progress callback.

GDALDatasetH GDALRasterize(const char *pszDest, GDALDatasetH hDstDS, GDALDatasetH hSrcDS, const GDALRasterizeOptions *psOptions, int *pbUsageError)

Burns vector geometries into a raster.

This is the equivalent of the gdal_rasterize utility.

GDALRasterizeOptions* must be allocated and freed with GDALRasterizeOptionsNew() and GDALRasterizeOptionsFree() respectively. pszDest and hDstDS cannot be used at the same time.

Since

GDAL 2.1

Parameters:
  • pszDest -- the destination dataset path or NULL.

  • hDstDS -- the destination dataset or NULL.

  • hSrcDataset -- the source dataset handle.

  • psOptionsIn -- the options struct returned by GDALRasterizeOptionsNew() or NULL.

  • pbUsageError -- pointer to a integer output variable to store if any usage error has occurred or NULL.

Returns:

the output dataset (new dataset that must be closed using GDALClose(), or hDstDS is not NULL) or NULL in case of error.

GDALFootprintOptions *GDALFootprintOptionsNew(char **papszArgv, GDALFootprintOptionsForBinary *psOptionsForBinary)

Allocates a GDALFootprintOptions struct.

Since

GDAL 3.8

Parameters:
  • papszArgv -- NULL terminated list of options (potentially including filename and open options too), or NULL. The accepted options are the ones of the gdal_rasterize utility.

  • psOptionsForBinary -- (output) may be NULL (and should generally be NULL), otherwise (gdal_translate_bin.cpp use case) must be allocated with GDALFootprintOptionsForBinaryNew() prior to this function. Will be filled with potentially present filename, open options,...

Returns:

pointer to the allocated GDALFootprintOptions struct. Must be freed with GDALFootprintOptionsFree().

void GDALFootprintOptionsFree(GDALFootprintOptions *psOptions)

Frees the GDALFootprintOptions struct.

Since

GDAL 3.8

Parameters:

psOptions -- the options struct for GDALFootprint().

void GDALFootprintOptionsSetProgress(GDALFootprintOptions *psOptions, GDALProgressFunc pfnProgress, void *pProgressData)

Set a progress function.

Since

GDAL 3.8

Parameters:
  • psOptions -- the options struct for GDALFootprint().

  • pfnProgress -- the progress callback.

  • pProgressData -- the user data for the progress callback.

GDALDatasetH GDALFootprint(const char *pszDest, GDALDatasetH hDstDS, GDALDatasetH hSrcDS, const GDALFootprintOptions *psOptions, int *pbUsageError)

Computes the footprint of a raster.

This is the equivalent of the gdal_footprint utility.

GDALFootprintOptions* must be allocated and freed with GDALFootprintOptionsNew() and GDALFootprintOptionsFree() respectively. pszDest and hDstDS cannot be used at the same time.

Since

GDAL 3.8

Parameters:
  • pszDest -- the vector destination dataset path or NULL.

  • hDstDS -- the vector destination dataset or NULL.

  • hSrcDataset -- the raster source dataset handle.

  • psOptionsIn -- the options struct returned by GDALFootprintOptionsNew() or NULL.

  • pbUsageError -- pointer to a integer output variable to store if any usage error has occurred or NULL.

Returns:

the output dataset (new dataset that must be closed using GDALClose(), or hDstDS is not NULL) or NULL in case of error.

GDALBuildVRTOptions *GDALBuildVRTOptionsNew(char **papszArgv, GDALBuildVRTOptionsForBinary *psOptionsForBinary)

Allocates a GDALBuildVRTOptions struct.

Since

GDAL 2.1

Parameters:
  • papszArgv -- NULL terminated list of options (potentially including filename and open options too), or NULL. The accepted options are the ones of the gdalbuildvrt utility.

  • psOptionsForBinary -- (output) may be NULL (and should generally be NULL), otherwise (gdalbuildvrt_bin.cpp use case) must be allocated with GDALBuildVRTOptionsForBinaryNew() prior to this function. Will be filled with potentially present filename, open options,...

Returns:

pointer to the allocated GDALBuildVRTOptions struct. Must be freed with GDALBuildVRTOptionsFree().

void GDALBuildVRTOptionsFree(GDALBuildVRTOptions *psOptions)

Frees the GDALBuildVRTOptions struct.

Since

GDAL 2.1

Parameters:

psOptions -- the options struct for GDALBuildVRT().

void GDALBuildVRTOptionsSetProgress(GDALBuildVRTOptions *psOptions, GDALProgressFunc pfnProgress, void *pProgressData)

Set a progress function.

Since

GDAL 2.1

Parameters:
  • psOptions -- the options struct for GDALBuildVRT().

  • pfnProgress -- the progress callback.

  • pProgressData -- the user data for the progress callback.

GDALDatasetH GDALBuildVRT(const char *pszDest, int nSrcCount, GDALDatasetH *pahSrcDS, const char *const *papszSrcDSNames, const GDALBuildVRTOptions *psOptions, int *pbUsageError)

Build a VRT from a list of datasets.

This is the equivalent of the gdalbuildvrt utility.

GDALBuildVRTOptions* must be allocated and freed with GDALBuildVRTOptionsNew() and GDALBuildVRTOptionsFree() respectively. pahSrcDS and papszSrcDSNames cannot be used at the same time.

Since

GDAL 2.1

Parameters:
  • pszDest -- the destination dataset path.

  • nSrcCount -- the number of input datasets.

  • pahSrcDS -- the list of input datasets (or NULL, exclusive with papszSrcDSNames). For practical purposes, the type of this argument should be considered as "const GDALDatasetH* const*", that is neither the array nor its values are mutated by this function.

  • papszSrcDSNames -- the list of input dataset names (or NULL, exclusive with pahSrcDS)

  • psOptionsIn -- the options struct returned by GDALBuildVRTOptionsNew() or NULL.

  • pbUsageError -- pointer to a integer output variable to store if any usage error has occurred.

Returns:

the output dataset (new dataset that must be closed using GDALClose()) or NULL in case of error. If using pahSrcDS, the returned VRT dataset has a reference to each pahSrcDS[] element. Hence pahSrcDS[] elements should be closed after the returned dataset if using GDALClose(). A safer alternative is to use GDALReleaseDataset() instead of using GDALClose(), in which case you can close datasets in any order.

GDALMultiDimInfoOptions *GDALMultiDimInfoOptionsNew(char **papszArgv, GDALMultiDimInfoOptionsForBinary *psOptionsForBinary)

Allocates a GDALMultiDimInfo struct.

Since

GDAL 3.1

Parameters:
  • papszArgv -- NULL terminated list of options (potentially including filename and open options too), or NULL. The accepted options are the ones of the gdalmdiminfo utility.

  • psOptionsForBinary -- should be nullptr, unless called from gdalmultidiminfo_bin.cpp

Returns:

pointer to the allocated GDALMultiDimInfoOptions struct. Must be freed with GDALMultiDimInfoOptionsFree().

void GDALMultiDimInfoOptionsFree(GDALMultiDimInfoOptions *psOptions)

Frees the GDALMultiDimInfoOptions struct.

Since

GDAL 3.1

Parameters:

psOptions -- the options struct for GDALMultiDimInfo().

char *GDALMultiDimInfo(GDALDatasetH hDataset, const GDALMultiDimInfoOptions *psOptions)

Lists various information about a GDAL multidimensional dataset.

This is the equivalent of the gdalmdiminfoutility.

GDALMultiDimInfoOptions* must be allocated and freed with GDALMultiDimInfoOptionsNew() and GDALMultiDimInfoOptionsFree() respectively.

Since

GDAL 3.1

Parameters:
  • hDataset -- the dataset handle.

  • psOptionsIn -- the options structure returned by GDALMultiDimInfoOptionsNew() or NULL.

Returns:

string corresponding to the information about the raster dataset (must be freed with CPLFree()), or NULL in case of error.

GDALMultiDimTranslateOptions *GDALMultiDimTranslateOptionsNew(char **papszArgv, GDALMultiDimTranslateOptionsForBinary *psOptionsForBinary)

Allocates a GDALMultiDimTranslateOptions struct.

Since

GDAL 3.1

Parameters:
  • papszArgv -- NULL terminated list of options (potentially including filename and open options too), or NULL. The accepted options are the ones of the gdalmdimtranslate utility.

  • psOptionsForBinary -- should be nullptr, unless called from gdalmdimtranslate_bin.cpp

Returns:

pointer to the allocated GDALMultiDimTranslateOptions struct. Must be freed with GDALMultiDimTranslateOptionsFree().

void GDALMultiDimTranslateOptionsFree(GDALMultiDimTranslateOptions *psOptions)

Frees the GDALMultiDimTranslateOptions struct.

Since

GDAL 3.1

Parameters:

psOptions -- the options struct for GDALMultiDimTranslate().

void GDALMultiDimTranslateOptionsSetProgress(GDALMultiDimTranslateOptions *psOptions, GDALProgressFunc pfnProgress, void *pProgressData)

Set a progress function.

Since

GDAL 3.1

Parameters:
  • psOptions -- the options struct for GDALMultiDimTranslate().

  • pfnProgress -- the progress callback.

  • pProgressData -- the user data for the progress callback.

GDALDatasetH GDALMultiDimTranslate(const char *pszDest, GDALDatasetH hDstDataset, int nSrcCount, GDALDatasetH *pahSrcDS, const GDALMultiDimTranslateOptions *psOptions, int *pbUsageError)

Converts raster data between different formats.

This is the equivalent of the gdalmdimtranslate utility.

GDALMultiDimTranslateOptions* must be allocated and freed with GDALMultiDimTranslateOptionsNew() and GDALMultiDimTranslateOptionsFree() respectively. pszDest and hDstDS cannot be used at the same time.

Since

GDAL 3.1

Parameters:
  • pszDest -- the destination dataset path or NULL.

  • hDstDS -- the destination dataset or NULL.

  • nSrcCount -- the number of input datasets.

  • pahSrcDS -- the list of input datasets.

  • psOptions -- the options struct returned by GDALMultiDimTranslateOptionsNew() or NULL.

  • pbUsageError -- pointer to a integer output variable to store if any usage error has occurred or NULL.

Returns:

the output dataset (new dataset that must be closed using GDALClose(), or hDstDS is not NULL) or NULL in case of error.

GDALVectorInfoOptions *GDALVectorInfoOptionsNew(char **papszArgv, GDALVectorInfoOptionsForBinary *psOptionsForBinary)

Allocates a GDALVectorInfoOptions struct.

Note that when this function is used a library function, and not from the ogrinfo utility, a dataset name must be specified if any layer names(s) are specified (if no layer name is specific, passing a dataset name is not needed). That dataset name may be a dummy one, as the dataset taken into account is the hDS parameter passed to GDALVectorInfo(). Similarly the -oo switch in a non-ogrinfo context will be ignored, and it is the responsibility of the user to apply them when opening the hDS parameter passed to GDALVectorInfo().

Since

GDAL 3.7

Parameters:
  • papszArgv -- NULL terminated list of options (potentially including filename and open options too), or NULL. The accepted options are the ones of the ogrinfo utility.

  • psOptionsForBinary -- (output) may be NULL (and should generally be NULL), otherwise (ogrinfo_bin.cpp use case) must be allocated with GDALVectorInfoOptionsForBinaryNew() prior to this function. Will be filled with potentially present filename, open options, subdataset number...

Returns:

pointer to the allocated GDALVectorInfoOptions struct. Must be freed with GDALVectorInfoOptionsFree().

void GDALVectorInfoOptionsFree(GDALVectorInfoOptions *psOptions)

Frees the GDALVectorInfoOptions struct.

Since

GDAL 3.7

Parameters:

psOptions -- the options struct for GDALVectorInfo().

char *GDALVectorInfo(GDALDatasetH hDataset, const GDALVectorInfoOptions *psOptions)

Lists various information about a GDAL supported vector dataset.

This is the equivalent of the ogrinfo utility.

GDALVectorInfoOptions* must be allocated and freed with GDALVectorInfoOptionsNew() and GDALVectorInfoOptionsFree() respectively.

Since

GDAL 3.7

Parameters:
  • hDataset -- the dataset handle.

  • psOptions -- the options structure returned by GDALVectorInfoOptionsNew() or NULL.

Returns:

string corresponding to the information about the raster dataset (must be freed with CPLFree()), or NULL in case of error.

GDALTileIndexOptions *GDALTileIndexOptionsNew(char **papszArgv, GDALTileIndexOptionsForBinary *psOptionsForBinary)

Allocates a GDALTileIndexOptions struct.

Since

GDAL 3.9

Parameters:
  • papszArgv -- NULL terminated list of options (potentially including filename and open options too), or NULL. The accepted options are the ones of the gdaltindex utility.

  • psOptionsForBinary -- (output) may be NULL (and should generally be NULL), otherwise (gdaltindex_bin.cpp use case) must be allocated with GDALTileIndexOptionsForBinaryNew() prior to this function. Will be filled with potentially present filename, open options,...

Returns:

pointer to the allocated GDALTileIndexOptions struct. Must be freed with GDALTileIndexOptionsFree().

void GDALTileIndexOptionsFree(GDALTileIndexOptions *psOptions)

Frees the GDALTileIndexOptions struct.

Since

GDAL 3.9

Parameters:

psOptions -- the options struct for GDALTileIndex().

GDALDatasetH GDALTileIndex(const char *pszDest, int nSrcCount, const char *const *papszSrcDSNames, const GDALTileIndexOptions *psOptions, int *pbUsageError)

Build a tile index from a list of datasets.

This is the equivalent of the gdaltindex utility.

GDALTileIndexOptions* must be allocated and freed with GDALTileIndexOptionsNew() and GDALTileIndexOptionsFree() respectively.

Since

GDAL3.9

Parameters:
  • pszDest -- the destination dataset path.

  • nSrcCount -- the number of input datasets.

  • papszSrcDSNames -- the list of input dataset names

  • psOptionsIn -- the options struct returned by GDALTileIndexOptionsNew() or NULL.

  • pbUsageError -- pointer to a integer output variable to store if any usage error has occurred.

Returns:

the output dataset (new dataset that must be closed using GDALClose()) or NULL in case of error.