1.. _rfc-59.1: 2 3======================================================================================= 4RFC 59.1 : GDAL/OGR utilities as a library 5======================================================================================= 6 7Authors: Faza Mahamood, Even Rouault 8 9Contact: fazamhd at gmail dot com, even.rouault at spatialys.com 10 11Status: Adopted, implemented 12 13Implementation version: 2.1 14 15Summary 16------- 17 18This RFC defines how to expose GDAL/OGR C/C++ utilities as C callable 19functions. The utility code is modified to call the new function. This 20RFC gives a general frame and principles, demonstrated with a few 21utilities, but aimed at being extended with other utilities. 22 23Rationale 24--------- 25 26There is a need for calling GDAL utilities from code without involving 27system calls, to be able to work on in-memory datasets and use 28progress/cancellation callback functions. 29 30Changes 31------- 32 33A public header file gdal_utils.h is created which contains the public 34declarations of GDAL utilities. The current header(still in progress) 35can be found 36`here <https://github.com/rouault/gdal2/blob/rfc59.1/gdal/apps/gdal_utils.h>`__. 37 38Each utility has a function (XXXXOptionsNew) to create an option 39structure from arguments specified as an array of strings. This function 40also accepts as argument an extra semi-private structure used to 41cooperate with the code of the command line utility itself. 42 43For GDALInfo(): 44 45:: 46 47 /*! Options for GDALInfo(). Opaque type */ 48 typedef struct GDALInfoOptions GDALInfoOptions; 49 typedef struct GDALInfoOptionsForBinary GDALInfoOptionsForBinary; 50 51 /** 52 * Allocates a GDALInfoOptions struct. 53 * 54 * @param papszArgv NULL terminated list of options (potentially including filename and open options too) 55 * The accepted options are the one of the gdalinfo utility. 56 * @param psOptionsForBinary (output) may be NULL (and should generally be NULL), 57 * otherwise (gdalinfo_bin.cpp use case) must be allocated with 58 * GDALInfoOptionsForBinaryNew() prior to this function. Will be 59 * filled with potentially present filename, open options, subdataset number... 60 * @return pointer to the allocated GDALInfoOptions struct. 61 * 62 * @since GDAL 2.1 63 */ 64 GDALInfoOptions CPL_DLL *GDALInfoOptionsNew(char** papszArgv, GDALInfoOptionsForBinary* psOptionsForBinary); 65 66 void CPL_DLL GDALInfoOptionsFree( GDALInfoOptions *psOptions ); 67 68 /** 69 * Lists various information about a GDAL supported raster dataset. 70 * 71 * GDALInfoOptions* must be allocated and freed with GDALInfoOptionsNew() 72 * and GDALInfoOptionsFree() respectively. 73 * 74 * @param hDataset the dataset handle. 75 * @param psOptions the options structure returned by GDALInfoOptionsNew() or NULL. 76 * @return string corresponding to the information about the raster dataset. 77 * It must be freed using CPLFree(). 78 * 79 * @since GDAL 2.1 80 */ 81 char CPL_DLL *GDALInfo( GDALDatasetH hDataset, const GDALInfoOptions *psOptions ); 82 83Similarly for GDALTranslate(): 84 85:: 86 87 /*! Options for GDALTranslate(). Opaque type */ 88 typedef struct GDALTranslateOptions GDALTranslateOptions; 89 typedef struct GDALTranslateOptionsForBinary GDALTranslateOptionsForBinary; 90 91 GDALTranslateOptions CPL_DLL *GDALTranslateOptionsNew(char** papszArgv, 92 GDALTranslateOptionsForBinary* psOptionsForBinary); 93 94 void CPL_DLL GDALTranslateOptionsFree( GDALTranslateOptions *psOptions ); 95 96 void CPL_DLL GDALTranslateOptionsSetProgress( GDALTranslateOptions *psOptions, 97 GDALProgressFunc pfnProgress, 98 void *pProgressData ); 99 100 GDALDatasetH CPL_DLL GDALTranslate(const char *pszDestFilename, 101 GDALDatasetH hSrcDataset, 102 const GDALTranslateOptions *psOptions, 103 int *pbUsageError); 104 105Similarly for GDALWarp(): 106 107:: 108 109 /*! Options for GDALWarp(). Opaque type */ 110 typedef struct GDALWarpAppOptions GDALWarpAppOptions; 111 112 typedef struct GDALWarpAppOptionsForBinary GDALWarpAppOptionsForBinary; 113 114 GDALWarpAppOptions CPL_DLL *GDALWarpAppOptionsNew(char** papszArgv, 115 GDALWarpAppOptionsForBinary* psOptionsForBinary); 116 117 void CPL_DLL GDALWarpAppOptionsFree( GDALWarpAppOptions *psOptions ); 118 119 void CPL_DLL GDALWarpAppOptionsSetProgress( GDALWarpAppOptions *psOptions, 120 GDALProgressFunc pfnProgress, 121 void *pProgressData ); 122 void CPL_DLL GDALWarpAppOptionsSetWarpOption( GDALWarpAppOptions *psOptions, 123 const char* pszKey, 124 const char* pszValue ); 125 126 GDALDatasetH CPL_DLL GDALWarp( const char *pszDest, GDALDatasetH hDstDS, int nSrcCount, 127 GDALDatasetH *pahSrcDS, 128 const GDALWarpAppOptions *psOptions, int *pbUsageError ); 129 130Similarly for GDALVectorTranslate() (equivalent of ogr2ogr): 131 132:: 133 134 /*! Options for GDALVectorTranslate(). Opaque type */ 135 typedef struct GDALVectorTranslateOptions GDALVectorTranslateOptions; 136 137 typedef struct GDALVectorTranslateOptionsForBinary GDALVectorTranslateOptionsForBinary; 138 139 GDALVectorTranslateOptions CPL_DLL *GDALVectorTranslateOptionsNew(char** papszArgv, 140 GDALVectorTranslateOptionsForBinary* psOptionsForBinary); 141 142 void CPL_DLL GDALVectorTranslateOptionsFree( GDALVectorTranslateOptions *psOptions ); 143 144 void CPL_DLL GDALVectorTranslateOptionsSetProgress( GDALVectorTranslateOptions *psOptions, 145 GDALProgressFunc pfnProgress, 146 void *pProgressData ); 147 148 GDALDatasetH CPL_DLL GDALVectorTranslate( const char *pszDest, GDALDatasetH hDstDS, int nSrcCount, 149 GDALDatasetH *pahSrcDS, 150 const GDALVectorTranslateOptions *psOptions, int *pbUsageError ); 151 152For other utilities, see 153`gdal_utils.h <http://svn.osgeo.org/gdal/trunk/gdal/apps/gdal_utils.h>`__ 154 155SWIG bindings (Python / Java / C# / Perl) changes 156------------------------------------------------- 157 158All bindings 159~~~~~~~~~~~~ 160 161For all bindings, the above functions are mapped to SWIG with : 162 163:: 164 165 166 struct GDALInfoOptions { 167 %extend { 168 GDALInfoOptions(char** options) { 169 return GDALInfoOptionsNew(options, NULL); 170 } 171 172 ~GDALInfoOptions() { 173 GDALInfoOptionsFree( self ); 174 } 175 } 176 }; 177 178 %rename (InfoInternal) GDALInfo; 179 char *GDALInfo( GDALDatasetShadow *hDataset, GDALInfoOptions *infoOptions ); 180 181:: 182 183 struct GDALTranslateOptions { 184 %extend { 185 GDALTranslateOptions(char** options) { 186 return GDALTranslateOptionsNew(options, NULL); 187 } 188 189 ~GDALTranslateOptions() { 190 GDALTranslateOptionsFree( self ); 191 } 192 } 193 }; 194 195 %rename (TranslateInternal) wrapper_GDALTranslate; 196 %newobject wrapper_GDALTranslate; 197 198 %inline %{ 199 GDALDatasetShadow* wrapper_GDALTranslate( const char* dest, 200 GDALDatasetShadow* dataset, 201 GDALTranslateOptions* translateOptions, 202 GDALProgressFunc callback=NULL, 203 void* callback_data=NULL); 204 205:: 206 207 struct GDALWarpAppOptions { 208 %extend { 209 GDALWarpAppOptions(char** options) { 210 return GDALWarpAppOptionsNew(options, NULL); 211 } 212 213 ~GDALWarpAppOptions() { 214 GDALWarpAppOptionsFree( self ); 215 } 216 } 217 }; 218 219 /* Note: we must use 2 distinct names since there's a bug/feature in swig */ 220 /* that doesn't play nicely with the (int object_list_count, GDALDatasetShadow** poObjects) input typemap */ 221 222 %inline %{ 223 int wrapper_GDALWarpDestDS( GDALDatasetShadow* dstDS, 224 int object_list_count, GDALDatasetShadow** poObjects, 225 GDALWarpAppOptions* warpAppOptions, 226 GDALProgressFunc callback=NULL, 227 void* callback_data=NULL), 228 %} 229 230 %newobject wrapper_GDALWarpDestName; 231 232 %inline %{ 233 GDALDatasetShadow* wrapper_GDALWarpDestName( const char* dest, 234 int object_list_count, GDALDatasetShadow** poObjects, 235 GDALWarpAppOptions* warpAppOptions, 236 GDALProgressFunc callback=NULL, 237 void* callback_data=NULL), 238 %} 239 240:: 241 242 243 struct GDALVectorTranslateOptions { 244 %extend { 245 GDALVectorTranslateOptions(char** options) { 246 return GDALVectorTranslateOptionsNew(options, NULL); 247 } 248 249 ~GDALVectorTranslateOptions() { 250 GDALVectorTranslateOptionsFree( self ); 251 } 252 } 253 }; 254 255 /* Note: we must use 2 distinct names since there's a bug/feature in swig */ 256 /* that doesn't play nicely with the (int object_list_count, GDALDatasetShadow** poObjects) input typemap */ 257 258 %inline %{ 259 int wrapper_GDALVectorTranslateDestDS( GDALDatasetShadow* dstDS, 260 GDALDatasetShadow* srcDS, 261 GDALVectorTranslateOptions* options, 262 GDALProgressFunc callback=NULL, 263 void* callback_data=NULL); 264 %} 265 266 %newobject wrapper_GDALVectorTranslateDestName; 267 268 %inline %{ 269 GDALDatasetShadow* wrapper_GDALVectorTranslateDestName( const char* dest, 270 GDALDatasetShadow* srcDS, 271 GDALVectorTranslateOptions* options, 272 GDALProgressFunc callback=NULL, 273 void* callback_data=NULL); 274 %} 275 276For other utilities, see 277`gdal.i <http://svn.osgeo.org/gdal/trunk/gdal/swig/python/gdal.i>`__ 278 279Python bindings 280~~~~~~~~~~~~~~~ 281 282For Python bindings, convenience wrappers are created to allow 283specifying options in a more user friendly way. 284 285:: 286 287 def InfoOptions(options = [], format = 'text', deserialize = True, 288 computeMinMax = False, reportHistograms = False, reportProj4 = False, 289 stats = False, approxStats = False, computeChecksum = False, 290 showGCPs = True, showMetadata = True, showRAT = True, showColorTable = True, 291 listMDD = False, showFileList = True, allMetadata = False, 292 extraMDDomains = None): 293 """ Create a InfoOptions() object that can be passed to gdal.Info() 294 options can be be an array of strings, a string or let empty and filled from other keywords.""" 295 296 297 def Info(ds, **kwargs): 298 """ Return information on a dataset. 299 Arguments are : 300 ds --- a Dataset object or a filename 301 Keyword arguments are : 302 options --- return of gdal.InfoOptions(), string or array of strings 303 other keywords arguments of gdal.InfoOptions() 304 If options is provided as a gdal.InfoOptions() object, other keywords are ignored. """ 305 306gdal.Info() can be used either with setting the attributes of 307gdal.InfoOptions() or inlined arguments of gdal.Info(). Arguments can be 308specified as array of strings, command line syntax or dedeicated 309keywords. So various combinations are possible : 310 311:: 312 313 options = gdal.InfoOptions(format = 'json', computeChecksum = True) 314 gdal.Info(ds, options) 315 316:: 317 318 options = gdal.InfoOptions(options = ['-json', '-checksum']) 319 gdal.Info(ds, options) 320 321:: 322 323 options = gdal.InfoOptions(options = '-json -checksum') 324 gdal.Info(ds, options) 325 326:: 327 328 gdal.Info(ds, format = 'json', computeChecksum = True) 329 330:: 331 332 gdal.Info(ds, options = ['-json', '-checksum']) 333 334:: 335 336 gdal.Info(ds, options = '-json -checksum') 337 338:: 339 340 def TranslateOptions(options = [], format = 'GTiff', 341 outputType = GDT_Unknown, bandList = None, maskBand = None, 342 width = 0, height = 0, widthPct = 0.0, heightPct = 0.0, 343 xRes = 0.0, yRes = 0.0, 344 creationOptions = None, srcWin = None, projWin = None, projWinSRS = None, strict = False, 345 unscale = False, scaleParams = None, exponents = None, 346 outputBounds = None, metadataOptions = None, 347 outputSRS = None, GCPs = None, 348 noData = None, rgbExpand = None, 349 stats = False, rat = True, resampleAlg = None, 350 callback = None, callback_data = None): 351 """ Create a TranslateOptions() object that can be passed to gdal.Translate() 352 Keyword arguments are : 353 options --- can be be an array of strings, a string or let empty and filled from other keywords. 354 format --- output format ("GTiff", etc...) 355 outputType --- output type (gdal.GDT_Byte, etc...) 356 bandList --- array of band numbers (index start at 1) 357 maskBand --- mask band to generate or not ("none", "auto", "mask", 1, ...) 358 width --- width of the output raster in pixel 359 height --- height of the output raster in pixel 360 widthPct --- width of the output raster in percentage (100 = original width) 361 heightPct --- height of the output raster in percentage (100 = original height) 362 xRes --- output horizontal resolution 363 yRes --- output vertical resolution 364 creationOptions --- list of creation options 365 srcWin --- subwindow in pixels to extract: [left_x, top_y, width, height] 366 projWin --- subwindow in projected coordinates to extract: [ulx, uly, lrx, lry] 367 projWinSRS --- SRS in which projWin is expressed 368 strict --- strict mode 369 unscale --- unscale values with scale and offset metadata 370 scaleParams --- list of scale parameters, each of the form [src_min,src_max] or [src_min,src_max,dst_min,dst_max] 371 exponents --- list of exponentiation parameters 372 outputBounds --- assigned output bounds: [ulx, uly, lrx, lry] 373 metadataOptions --- list of metadata options 374 outputSRS --- assigned output SRS 375 GCPs --- list of GCPs 376 noData --- nodata value (or "none" to unset it) 377 rgbExpand --- Color palette expansion mode: "gray", "rgb", "rgba" 378 stats --- whether to calcule statistics 379 rat --- whether to write source RAT 380 resampleAlg --- resampling mode 381 callback --- callback method 382 callback_data --- user data for callback 383 """ 384 385 def Translate(destName, srcDS, **kwargs): 386 """ Convert a dataset. 387 Arguments are : 388 destName --- Output dataset name 389 srcDS --- a Dataset object or a filename 390 Keyword arguments are : 391 options --- return of gdal.InfoOptions(), string or array of strings 392 other keywords arguments of gdal.TranslateOptions() 393 If options is provided as a gdal.TranslateOptions() object, other keywords are ignored. """ 394 395:: 396 397 398 def WarpOptions(options = [], format = 'GTiff', 399 outputBounds = None, 400 outputBoundsSRS = None, 401 xRes = None, yRes = None, targetAlignedPixels = False, 402 width = 0, height = 0, 403 srcSRS = None, dstSRS = None, 404 srcAlpha = False, dstAlpha = False, 405 warpOptions = None, errorThreshold = None, 406 warpMemoryLimit = None, creationOptions = None, outputType = GDT_Unknown, 407 workingType = GDT_Unknown, resampleAlg = None, 408 srcNodata = None, dstNodata = None, multithread = False, 409 tps = False, rpc = False, geoloc = False, polynomialOrder = None, 410 transformerOptions = None, cutlineDSName = None, 411 cutlineLayer = None, cutlineWhere = None, cutlineSQL = None, cutlineBlend = None, cropToCutline = False, 412 copyMetadata = True, metadataConflictValue = None, 413 setColorInterpretation = False, 414 callback = None, callback_data = None): 415 """ Create a WarpOptions() object that can be passed to gdal.Warp() 416 Keyword arguments are : 417 options --- can be be an array of strings, a string or let empty and filled from other keywords. 418 format --- output format ("GTiff", etc...) 419 outputBounds --- output bounds as (minX, minY, maxX, maxY) in target SRS 420 outputBoundsSRS --- SRS in which output bounds are expressed, in the case they are not expressed in dstSRS 421 xRes, yRes --- output resolution in target SRS 422 targetAlignedPixels --- whether to force output bounds to be multiple of output resolution 423 width --- width of the output raster in pixel 424 height --- height of the output raster in pixel 425 srcSRS --- source SRS 426 dstSRS --- output SRS 427 srcAlpha --- whether to force the last band of the input dataset to be considered as an alpha band 428 dstAlpha --- whether to force the creation of an output alpha band 429 outputType --- output type (gdal.GDT_Byte, etc...) 430 workingType --- working type (gdal.GDT_Byte, etc...) 431 warpOptions --- list of warping options 432 errorThreshold --- error threshold for approximation transformer (in pixels) 433 warpMemoryLimit --- size of working buffer in bytes 434 resampleAlg --- resampling mode 435 creationOptions --- list of creation options 436 srcNodata --- source nodata value(s) 437 dstNodata --- output nodata value(s) 438 multithread --- whether to multithread computation and I/O operations 439 tps --- whether to use Thin Plate Spline GCP transformer 440 rpc --- whether to use RPC transformer 441 geoloc --- whether to use GeoLocation array transformer 442 polynomialOrder --- order of polynomial GCP interpolation 443 transformerOptions --- list of transformer options 444 cutlineDSName --- cutline dataset name 445 cutlineLayer --- cutline layer name 446 cutlineWhere --- cutline WHERE clause 447 cutlineSQL --- cutline SQL statement 448 cutlineBlend --- cutline blend distance in pixels 449 cropToCutline --- whether to use cutline extent for output bounds 450 copyMetadata --- whether to copy source metadata 451 metadataConflictValue --- metadata data conflict value 452 setColorInterpretation --- whether to force color interpretation of input bands to output bands 453 callback --- callback method 454 callback_data --- user data for callback 455 """ 456 457 def Warp(destNameOrDestDS, srcDSOrSrcDSTab, **kwargs): 458 """ Warp one or several datasets. 459 Arguments are : 460 destNameOrDestDS --- Output dataset name or object 461 srcDSOrSrcDSTab --- an array of Dataset objects or filenames, or a Dataset object or a filename 462 Keyword arguments are : 463 options --- return of gdal.InfoOptions(), string or array of strings 464 other keywords arguments of gdal.WarpOptions() 465 If options is provided as a gdal.WarpOptions() object, other keywords are ignored. """ 466 467:: 468 469 470 def VectorTranslateOptions(options = [], format = 'ESRI Shapefile', 471 accessMode = None, 472 srcSRS = None, dstSRS = None, reproject = True, 473 SQLStatement = None, SQLDialect = None, where = None, selectFields = None, spatFilter = None, 474 datasetCreationOptions = None, 475 layerCreationOptions = None, 476 layers = None, 477 layerName = None, 478 geometryType = None, 479 segmentizeMaxDist= None, 480 callback = None, callback_data = None): 481 """ Create a VectorTranslateOptions() object that can be passed to gdal.VectorTranslate() 482 Keyword arguments are : 483 options --- can be be an array of strings, a string or let empty and filled from other keywords. 484 format --- output format ("ESRI Shapefile", etc...) 485 accessMode --- None for creation, 'update', 'append', 'overwrite' 486 srcSRS --- source SRS 487 dstSRS --- output SRS (with reprojection if reproject = True) 488 reproject --- whether to do reprojection 489 SQLStatement --- SQL statement to apply to the source dataset 490 SQLDialect --- SQL dialect ('OGRSQL', 'SQLITE', ...) 491 where --- WHERE clause to apply to source layer(s) 492 selectFields --- list of fields to select 493 spatFilter --- spatial filter as (minX, minY, maxX, maxY) bounding box 494 datasetCreationOptions --- list of dataset creation options 495 layerCreationOptions --- list of layer creation options 496 layers --- list of layers to convert 497 layerName --- output layer name 498 geometryType --- output layer geometry type ('POINT', ....) 499 segmentizeMaxDist --- maximum distance between consecutive nodes of a line geometry 500 callback --- callback method 501 callback_data --- user data for callback 502 """ 503 504 def VectorTranslate(destNameOrDestDS, srcDS, **kwargs): 505 """ Convert one vector dataset 506 Arguments are : 507 destNameOrDestDS --- Output dataset name or object 508 srcDS --- a Dataset object or a filename 509 Keyword arguments are : 510 options --- return of gdal.InfoOptions(), string or array of strings 511 other keywords arguments of gdal.VectorTranslateOptions() 512 If options is provided as a gdal.VectorTranslateOptions() object, other keywords are ignored. """ 513 514:: 515 516 517 def DEMProcessingOptions(options = [], colorFilename = None, format = 'GTiff', 518 creationOptions = None, computeEdges = False, alg = 'Horn', band = 1, 519 zFactor = None, scale = None, azimuth = None, altitude = None, combined = False, 520 slopeFormat = None, trigonometric = False, zeroForFlat = False, 521 callback = None, callback_data = None): 522 """ Create a DEMProcessingOptions() object that can be passed to gdal.DEMProcessing() 523 Keyword arguments are : 524 options --- can be be an array of strings, a string or let empty and filled from other keywords. 525 colorFilename --- (mandatory for "color-relief") name of file that contains palette definition for the "color-relief" processing. 526 format --- output format ("GTiff", etc...) 527 creationOptions --- list of creation options 528 computeEdges --- whether to compute values at raster edges. 529 alg --- 'ZevenbergenThorne' or 'Horn' 530 band --- source band number to use 531 zFactor --- (hillshade only) vertical exaggeration used to pre-multiply the elevations. 532 scale --- ratio of vertical units to horizontal. 533 azimuth --- (hillshade only) azimuth of the light, in degrees. 0 if it comes from the top of the raster, 90 from the east, ... The default value, 315, should rarely be changed as it is the value generally used to generate shaded maps. 534 altitude ---(hillshade only) altitude of the light, in degrees. 90 if the light comes from above the DEM, 0 if it is raking light. 535 combined --- (hillshade only) whether to compute combined shading, a combination of slope and oblique shading. 536 slopeformat --- (slope only) "degree" or "percent". 537 trigonometric --- (aspect only) whether to return trigonometric angle instead of azimuth. Thus 0deg means East, 90deg North, 180deg West, 270deg South. 538 zeroForFlat --- (aspect only) whether to return 0 for flat areas with slope=0, instead of -9999. 539 callback --- callback method 540 callback_data --- user data for callback 541 """ 542 543 def DEMProcessing(destName, srcDS, processing, **kwargs): 544 """ Apply a DEM processing. 545 Arguments are : 546 destName --- Output dataset name 547 srcDS --- a Dataset object or a filename 548 processing --- one of "hillshade", "slope", "aspect", "color-relief", "TRI", "TPI", "Roughness" 549 Keyword arguments are : 550 options --- return of gdal.InfoOptions(), string or array of strings 551 other keywords arguments of gdal.DEMProcessingOptions() 552 If options is provided as a gdal.DEMProcessingOptions() object, other keywords are ignored. """ 553 554:: 555 556 def NearblackOptions(options = [], format = 'GTiff', 557 creationOptions = None, white = False, colors = None, 558 maxNonBlack = None, nearDist = None, setAlpha = False, setMask = False, 559 callback = None, callback_data = None): 560 """ Create a NearblackOptions() object that can be passed to gdal.Nearblack() 561 Keyword arguments are : 562 options --- can be be an array of strings, a string or let empty and filled from other keywords. 563 format --- output format ("GTiff", etc...) 564 creationOptions --- list of creation options 565 white --- whether to search for nearly white (255) pixels instead of nearly black pixels. 566 colors --- list of colors to search for, e.g. ((0,0,0),(255,255,255)). The pixels that are considered as the collar are set to 0 567 maxNonBlack --- number of non-black (or other searched colors specified with white / colors) pixels that can be encountered before the giving up search inwards. Defaults to 2. 568 nearDist --- select how far from black, white or custom colors the pixel values can be and still considered near black, white or custom color. Defaults to 15. 569 setAlpha --- adds an alpha band if the output file. 570 setMask --- adds a mask band to the output file. 571 callback --- callback method 572 callback_data --- user data for callback 573 """ 574 575 def Nearblack(destNameOrDestDS, srcDS, **kwargs): 576 """ Convert nearly black/white borders to exact value. 577 Arguments are : 578 destNameOrDestDS --- Output dataset name or object 579 srcDS --- a Dataset object or a filename 580 Keyword arguments are : 581 options --- return of gdal.InfoOptions(), string or array of strings 582 other keywords arguments of gdal.NearblackOptions() 583 If options is provided as a gdal.NearblackOptions() object, other keywords are ignored. """ 584 585:: 586 587 def GridOptions(options = [], format = 'GTiff', 588 outputType = GDT_Unknown, 589 width = 0, height = 0, 590 creationOptions = None, 591 outputBounds = None, 592 outputSRS = None, 593 noData = None, 594 algorithm = None, 595 layers = None, 596 SQLStatement = None, 597 where = None, 598 spatFilter = None, 599 zfield = None, 600 z_increase = None, 601 z_multiply = None, 602 callback = None, callback_data = None): 603 """ Create a GridOptions() object that can be passed to gdal.Grid() 604 Keyword arguments are : 605 options --- can be be an array of strings, a string or let empty and filled from other keywords. 606 format --- output format ("GTiff", etc...) 607 outputType --- output type (gdal.GDT_Byte, etc...) 608 width --- width of the output raster in pixel 609 height --- height of the output raster in pixel 610 creationOptions --- list of creation options 611 outputBounds --- assigned output bounds: [ulx, uly, lrx, lry] 612 outputSRS --- assigned output SRS 613 noData --- nodata value 614 algorithm --- e.g "invdist:power=2.0:smoothing=0.0:radius1=0.0:radius2=0.0:angle=0.0:max_points=0:min_points=0:nodata=0.0" 615 layers --- list of layers to convert 616 SQLStatement --- SQL statement to apply to the source dataset 617 where --- WHERE clause to apply to source layer(s) 618 spatFilter --- spatial filter as (minX, minY, maxX, maxY) bounding box 619 zfield --- Identifies an attribute field on the features to be used to get a Z value from. This value overrides Z value read from feature geometry record. 620 z_increase --- Addition to the attribute field on the features to be used to get a Z value from. The addition should be the same unit as Z value. The result value will be Z value + Z increase value. The default value is 0. 621 z_multiply - Multiplication ratio for Z field. This can be used for shift from e.g. foot to meters or from elevation to deep. The result value will be (Z value + Z increase value) * Z multiply value. The default value is 1. 622 callback --- callback method 623 callback_data --- user data for callback 624 """ 625 626 def Grid(destName, srcDS, **kwargs): 627 """ Create raster from the scattered data. 628 Arguments are : 629 destName --- Output dataset name 630 srcDS --- a Dataset object or a filename 631 Keyword arguments are : 632 options --- return of gdal.InfoOptions(), string or array of strings 633 other keywords arguments of gdal.GridOptions() 634 If options is provided as a gdal.GridOptions() object, other keywords are ignored. """ 635 636:: 637 638 def RasterizeOptions(options = [], format = None, 639 creationOptions = None, noData = None, initValues = None, 640 outputBounds = None, outputSRS = None, 641 width = None, height = None, 642 xRes = None, yRes = None, targetAlignedPixels = False, 643 bands = None, inverse = False, allTouched = False, 644 burnValues = None, attribute = None, useZ = False, layers = None, 645 SQLStatement = None, SQLDialect = None, where = None, 646 callback = None, callback_data = None): 647 """ Create a RasterizeOptions() object that can be passed to gdal.Rasterize() 648 Keyword arguments are : 649 options --- can be be an array of strings, a string or let empty and filled from other keywords. 650 format --- output format ("GTiff", etc...) 651 creationOptions --- list of creation options 652 outputBounds --- assigned output bounds: [minx, miny, maxx, maxy] 653 outputSRS --- assigned output SRS 654 width --- width of the output raster in pixel 655 height --- height of the output raster in pixel 656 xRes, yRes --- output resolution in target SRS 657 targetAlignedPixels --- whether to force output bounds to be multiple of output resolution 658 noData --- nodata value 659 initValues --- Value or list of values to pre-initialize the output image bands with. However, it is not marked as the nodata value in the output file. If only one value is given, the same value is used in all the bands. 660 bands --- list of output bands to burn values into 661 inverse --- whether to invert rasterization, ie burn the fixed burn value, or the burn value associated with the first feature into all parts of the image not inside the provided a polygon. 662 allTouched -- whether to enable the ALL_TOUCHED rasterization option so that all pixels touched by lines or polygons will be updated, not just those on the line render path, or whose center point is within the polygon. 663 burnValues -- list of fixed values to burn into each band for all objects. Excusive with attribute. 664 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. Excusive with burnValues. 665 useZ --- whether to indicate that a burn value should be extracted from the "Z" values of the feature. These values are added to the burn value given by burnValues or attribute if provided. As of now, only points and lines are drawn in 3D. 666 layers --- list of layers from the datasource that will be used for input features. 667 SQLStatement --- SQL statement to apply to the source dataset 668 SQLDialect --- SQL dialect ('OGRSQL', 'SQLITE', ...) 669 where --- WHERE clause to apply to source layer(s) 670 callback --- callback method 671 callback_data --- user data for callback 672 """ 673 674 def Rasterize(destNameOrDestDS, srcDS, **kwargs): 675 """ Burns vector geometries into a raster 676 Arguments are : 677 destNameOrDestDS --- Output dataset name or object 678 srcDS --- a Dataset object or a filename 679 Keyword arguments are : 680 options --- return of gdal.InfoOptions(), string or array of strings 681 other keywords arguments of gdal.RasterizeOptions() 682 If options is provided as a gdal.RasterizeOptions() object, other keywords are ignored. """ 683 684:: 685 686 def BuildVRTOptions(options = [], 687 resolution = None, 688 outputBounds = None, 689 xRes = None, yRes = None, 690 targetAlignedPixels = None, 691 separate = None, 692 bandList = None, 693 addAlpha = None, 694 resampleAlg = None, 695 outputSRS = None, 696 allowProjectionDifference = None, 697 srcNodata = None, 698 VRTNodata = None, 699 hideNodata = None, 700 callback = None, callback_data = None): 701 """ Create a BuildVRTOptions() object that can be passed to gdal.BuildVRT() 702 Keyword arguments are : 703 options --- can be be an array of strings, a string or let empty and filled from other keywords.. 704 resolution --- 'highest', 'lowest', 'average', 'user'. 705 outputBounds --- output bounds as (minX, minY, maxX, maxY) in target SRS. 706 xRes, yRes --- output resolution in target SRS. 707 targetAlignedPixels --- whether to force output bounds to be multiple of output resolution. 708 separate --- whether each source file goes into a separate stacked band in the VRT band. 709 bandList --- array of band numbers (index start at 1). 710 addAlpha --- whether to add an alpha mask band to the VRT when the source raster have none. 711 resampleAlg --- resampling mode. 712 outputSRS --- assigned output SRS. 713 allowProjectionDifference --- whether to accept input datasets have not the same projection. Note: they will *not* be reprojected. 714 srcNodata --- source nodata value(s). 715 VRTNodata --- nodata values at the VRT band level. 716 hideNodata --- whether to make the VRT band not report the NoData value. 717 callback --- callback method. 718 callback_data --- user data for callback. 719 """ 720 721 def BuildVRT(destName, srcDSOrSrcDSTab, **kwargs): 722 """ Build a VRT from a list of datasets. 723 Arguments are : 724 destName --- Output dataset name 725 srcDSOrSrcDSTab --- an array of Dataset objects or filenames, or a Dataset object or a filename 726 Keyword arguments are : 727 options --- return of gdal.InfoOptions(), string or array of strings 728 other keywords arguments of gdal.BuildVRTOptions() 729 If options is provided as a gdal.BuildVRTOptions() object, other keywords are ignored. """ 730 731Utilities 732--------- 733 734Utilities are modified to call the respective function. 735 736Documentation 737------------- 738 739All new methods/functions are documented. 740 741Test Suite 742---------- 743 744gdal.Info method is tested in 745`test_gdalinfo_lib.py <http://svn.osgeo.org/gdal/trunk/autotest/utilities/test_gdalinfo_lib.py>`__. 746 747gdal.Translate method is tested in 748`test_gdal_translate_lib.py <http://svn.osgeo.org/gdal/trunk/autotest/utilities/test_gdal_translate_lib.py>`__ 749 750gdal.Warp method is tested in 751`test_gdalwarp_lib.py <http://svn.osgeo.org/gdal/trunk/autotest/utilities/test_gdalwarp_lib.py>`__ 752 753gdal.VectorTranslate method is tested in 754`test_ogr2ogr_lib.py <http://svn.osgeo.org/gdal/trunk/autotest/utilities/test_ogr2ogr_lib.py>`__ 755 756gdal.DEMProcessing method is tested in 757`test_gdaldem_lib.py <http://svn.osgeo.org/gdal/trunk/autotest/utilities/test_gdaldem_lib.py>`__ 758 759gdal.Nearblack method is tested in 760`test_nearblack_lib.py <http://svn.osgeo.org/gdal/trunk/autotest/utilities/test_nearblack_lib.py>`__ 761 762gdal.Grid method is tested in 763`test_gdal_grid_lib.py <http://svn.osgeo.org/gdal/trunk/autotest/utilities/test_gdal_grid_lib.py>`__ 764 765gdal.Rasterize method is tested in 766`test_gdal_rasterize_lib.py <http://svn.osgeo.org/gdal/trunk/autotest/utilities/test_gdal_rasterize_lib.py>`__. 767 768gdal.BuildVRT method is tested in 769`test_gdalbuildvrt_lib.py <http://svn.osgeo.org/gdal/trunk/autotest/utilities/test_gdalbuildvrt_lib.py>`__. 770 771Compatibility Issues 772-------------------- 773 774None expected. Command line utilities will keep the same interface. It 775will be checked by ensuring their tests in autotest/utilities still 776pass. 777 778Related ticket 779-------------- 780 781Implementation 782-------------- 783 784Implementation will be done by Faza Mahamood and Even Rouault 785 786The proposed implementation for gdalinfo and gdal_translate lies in the 787"rfc59.1" branch of the 788`https://github.com/rouault/gdal2/tree/rfc59.1 <https://github.com/rouault/gdal2/tree/rfc59.1>`__. 789 790Voting history 791-------------- 792 793+1 from DanielM and EvenR 794