1.. _rfc-59: 2 3======================================================================================= 4RFC 59 : GDAL/OGR utilities as a library 5======================================================================================= 6 7Authors: Faza Mahamood 8 9Contact: fazamhd at gmail dot com 10 11Status: Retracted in favor of :ref:`rfc-59.1` 12 13Summary 14------- 15 16This RFC defines new function for each GDAL utility. The new utility 17functions can be used to work on in-memory datasets. The utility code is 18modified to call the new function. This RFC gives a general frame and 19principles, demonstrated with gdalinfo, but aimed at being extended with 20other utilities. 21 22Rationale 23--------- 24 25There is need for calling GDAL utilities from the code. But this 26involves using system calls and cannot work on in-memory datasets. 27 28Changes 29------- 30 31New library libgdalutils is created. Both Unix and Windows build have 32been modified to take into account the new lib. The GDAL utilities are 33modified to use the new functions. New header file gdal_utils.h is 34created which contains the public declarations of GDAL utilities. The 35current header(still in progress) can be found 36`here <https://github.com/fazam/gdal/blob/gdalinfo/gdal/apps/gdal_utils.h>`__. 37 38:: 39 40 41 char CPL_DLL *GDALInfo( GDALDatasetH hDataset, GDALInfoOptions *psOptions ); 42 43 GDALInfoOptions CPL_DLL *GDALInfoOptionsNew( void ); 44 45 void CPL_DLL GDALInfoOptionsAddExtraMDDomains( GDALInfoOptions *psOptions, 46 const char *pszDomain ); 47 48 void CPL_DLL GDALInfoOptionsSetExtraMDDomains( GDALInfoOptions *psOptions, 49 char **papszExtraMDDomains ); 50 51 void CPL_DLL GDALInfoOptionsFree( GDALInfoOptions *psOptions ); 52 53:: 54 55 GDALDatasetH CPL_DLL GDALTranslate(const char *pszDest, GDALDatasetH hSrcDataset, GDALTranslateOptions *psOptions, int *pbUsageError) 56 57 GDALDatasetH CPL_DLL GDALWarp( const char *pszDest, GDALDatasetH hDstDS, int nSrcCount, 58 GDALDatasetH *pahSrcDS, GDALWarpAppOptions *psOptions, int *pbUsageError ) 59 60 GDALDatasetH CPL_DLL OGR2OGR( const char *pszDest, GDALDatasetH hDstDS, GDALDatasetH hSrcDS, 61 OGR2OGROptions *psOptions, int *pbUsageError ) 62 63SWIG bindings (Python / Java / C# / Perl) changes 64------------------------------------------------- 65 66For Python bindings only, new functions Info(), Translate() and Warp() 67are added in the gdal module which uses the new GDALInfo(), 68GDALTranslate() and GDALWarp() function respectively. Translate() is 69added in the ogr module which uses the new OGR2OGR() function. 70 71gdal.Info() can be used either with setting the attributes of 72gdal.InfoOptions() or inlined arguments of gdal.Info(). 73 74:: 75 76 77 options = gdal.InfoOptions() 78 79 options.format = gdal.INFO_FORMAT_TEXT 80 options.deserialize = True 81 options.computeMinMax = False 82 options.reportHistograms = False 83 options.reportProj4 = True 84 options.stats = False 85 options.approxStats = True 86 options.sample = False 87 options.computeChecksum = False 88 options.showGCPs = True 89 options.showMetadata = True 90 options.showRAT = False 91 options.showColorTable = True 92 options.listMDD = False 93 options.showFileList = True 94 options.allMetadata = TRUE 95 options.extraMDDomains = ['TRE'] 96 97 gdal.Info(ds, options, deserialize = True) 98 99:: 100 101 102 gdal.Info(ds, options = None, format = _gdal.INFO_FORMAT_TEXT, deserialize = True, 103 computeMinMax = False, reportHistograms = False, reportProj4 = False, 104 stats = False, approxStats = True, sample = False, computeChecksum = False, 105 showGCPs = True, showMetadata = True, showRAT = True, showColorTable = True, 106 listMDD = False, showFileList = True, allMetadata = False, 107 extraMDDomains = None) 108 109 gdal.Translate(destName, srcDS, options = None, format = 'GTiff', quiet = True, 110 outputType = GDT_Unknown, maskMode = _gdal.MASK_AUTO, bandList = None, 111 oXSizePixel = 0, oYSizePixel = 0, oXSizePct = 0.0, oYSizePct = 0.0, 112 createOptions = None, srcWin = [0,0,0,0],strict = False, 113 unscale = False, scaleParams = None, exponent = None, 114 uLX = 0.0, uLY = 0.0, lRX = 0.0, lRY = 0.0, metadataOptions = None, 115 outputSRS = None, GCPs = None, ULLR = [0,0,0,0], setNoData = False, 116 unsetNoData = False, noDataReal = 0.0, rgbExpand = 0, maskBand = 0, 117 stats = False, approxStats = False, errorOnPartiallyOutside = False, 118 errorOnCompletelyOutside = False, noRAT = False, resampling = None, 119 xRes = 0.0, yRes = 0.0, projSRS = None) 120 121 gdal.Warp(destNameOrDestDS, srcDSOrSrcDSTab, options = None, minX = 0.0, minY = 0.0, maxX = 0.0, 122 maxY = 0.0, xRes = 0.0, yRes = 0.0, targetAlignedPixels = False, forcePixels = 0, 123 forceLines = 0, quiet = True, enableDstAlpha = False, enableSrcAlpha = False, 124 format = 'GTiff', createOutput = False, warpOptions = None, errorThreshold = -1, 125 warpMemoryLimit = 0.0, createOptions = None, outputType = GDT_Unknown, 126 workingType = GDT_Unknown, resampleAlg = GRA_NearestNeighbour, 127 srcNodata = None, dstNodata = None, multi = False, TO = None, cutlineDSName = None, 128 cLayer = None, cWHERE = None, cSQL = None, cropToCutline = False, overwrite = False, 129 copyMetadata = True, copyBandInfo = True, MDConflictValue = '*', 130 setColorInterpretation = False, destOpenOptions = None, OvLevel = -2) 131 132 ogr.Translate(destNameOrDestDS, srcDS, options = None, accessMode = _ogr.ACCESS_CREATION, 133 skipFailures = False, layerTransaction = -1, forceTransaction = False, 134 groupTransactions = 20000, FIDToFetch = -1, quiet = False, 135 format = 'ESRI Shapefile', layers = None, DSCO = None, LCO = None, transform = False, 136 addMissingFields = False, outputSRSDef = None, sourceSRSDef = None, 137 nullifyOutputSRS = False, exactFieldNameMatch = True, newLayerName = None, 138 WHERE = None, geomField = None, selFields = None, SQLStatement = None, 139 dialect = None, gType = -2, geomConversion = _ogr.GEOMTYPE_DEFAULT, geomOp = _ogr.GEOMOP_NONE, 140 geomOpParam = 0, fieldTypesToString = None, mapFieldType = None, unsetFieldWidth = False, 141 displayProgress = False, wrapDateline = False, dateLineOffset = 10, clipSrc = None, clipSrcDS = None, 142 clipSrcSQL = None, clipSrcLayer = None, clipSrcWhere = None, clipDst = None, 143 clipDstDS = None, clipDstSQL = None, clipDstLayer = None, clipDstWhere = None, 144 splitListFields = False, maxSplitListSubFields = -1, explodeCollections = False, 145 zField = None, fieldMap = None, coordDim = -1, destOpenOptions = None, 146 forceNullable = False, unsetDefault = False, unsetFid = False, preserveFID = False, 147 copyMD = True, metadataOptions = None, spatSRSDef = None, transformOrder = 0, 148 spatialFilter = None) 149 150Utilities 151--------- 152 153Utilities are modified to call the respective function. 154 155Documentation 156------------- 157 158All new methods/functions are documented. 159 160Test Suite 161---------- 162 163gdal.Info method is tested in test_gdalinfo_lib.py. gdal.Translate 164method is tested in test_gdal_translate_lib.py. gdal.Warp method is 165tested in test_gdalwarp_lib.py. ogr.Translate method is tested in 166test_ogr2ogr_lib.py. 167 168Compatibility Issues 169-------------------- 170 171None expected. Command line utilities will keep the same interface. It 172will be checked by ensuring their tests in autotest/utilities still 173pass. 174 175Open question 176------------- 177 178What name should be given for librarified ogr2ogr? OGR2OGR() or 179OGRTranslate() ? 180 181The order of arguments in GDALTranslate(), GDALWarp() and OGR2OGR() is 182currently dest then source(s). 183 184:: 185 186 GDALDatasetH CPL_DLL GDALTranslate(const char *pszDest, GDALDatasetH hSrcDataset, GDALTranslateOptions *psOptions, int *pbUsageError) 187 188 GDALDatasetH CPL_DLL GDALWarp( const char *pszDest, GDALDatasetH hDstDS, int nSrcCount, 189 GDALDatasetH *pahSrcDS, GDALWarpAppOptions *psOptions, int *pbUsageError ) 190 191 GDALDatasetH CPL_DLL OGR2OGR( const char *pszDest, GDALDatasetH hDstDS, GDALDatasetH hSrcDS, 192 OGR2OGROptions *psOptions, int *pbUsageError ) 193 194It is similar to GDALCreateCopy(const char\* pszDestFilename, 195GDALDatasetH hSrcDS, ....), so at least there's a form of consistency at 196the API level. Any comments? 197 198Related ticket 199-------------- 200 201Implementation 202-------------- 203 204Implementation will be done by Faza Mahamood. 205 206The proposed implementation lies in the "gdalinfo" branch of the 207`https://github.com/fazam/gdal/tree/gdalinfo <https://github.com/fazam/gdal/tree/gdalinfo>`__. 208 209The list of changes : 210`https://github.com/fazam/gdal/compare/gdalinfo <https://github.com/fazam/gdal/compare/gdalinfo>`__ 211 212Voting history 213-------------- 214 215