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