1.. _rfc-44:
2
3=======================================================================================
4RFC 44: Add Parseable Output Formats for ogrinfo and gdalinfo
5=======================================================================================
6
7Authors: Dan "Ducky" Little, Faza Mahamood
8
9Contacts: danlittle at yahoo dot com, fazamhd at live dot com
10
11Status: Development. gdalinfo -json implemented in GDAL 2.0
12
13Summary
14-------
15
16Add XML and JSON output to the ogrinfo and gdalinfo utilities.
17
18Background
19----------
20
21ogrinfo and gdalinfo are incredibly useful metadata gathering tools.
22Their native text-based output formats, however, are not easily
23parseable by common external tools. Both XML and JSON are easily parsed
24and adding those output formats would substantially increase the utility
25for those looking to add the ogrinfo and gdalinfo utilities to a
26scripting stack.
27
28Implementation
29--------------
30
31An example implementation can be seen at the following github fork
32`https://github.com/theduckylittle/gdal/blob/trunk/gdal/apps/ogrinfo.cpp <https://github.com/theduckylittle/gdal/blob/trunk/gdal/apps/ogrinfo.cpp>`__
33
34To add the XML output to each utility will require "breaking up" the
35main loop into contingent chunks. All diagnostic messages will also need
36to be moved to STDERR to ensure that output on STDOUT is always
37parseable. The XML representation will be constructed using the MiniXML
38library built into GDAL.
39
40Proposed json format for gdalinfo
41---------------------------------
42
43::
44
45   {
46       "description": "...",
47       "driverShortName": "GTiff",
48       "driverLongName": "GeoTIFF",
49       "files": [ (if -nofl not specified)
50           "../gcore/data/byte.tif",
51           "../gcore/data/byte.tif.aux.xml"
52       ],
53       "size": [
54           20,
55           20
56       ],
57       "coordinateSystem": {
58           "proj": "+proj=.......", (if -proj4 specified)
59           "wkt": "PROJCS[....]"
60       },
61       "gcps": { (if -nogcp not specified)
62           "coordinateSystem": {
63               "proj": "+proj=.......", (if -proj4 specified)
64               "wkt": "PROJCS[....]"
65           },
66           "gcpList": [
67               {
68                   "id": "1",
69                   "info": "a",
70                   "pixel": 0.5,
71                   "line": 0.5,
72                   "X": 0.0,
73                   "Y": 0.0,
74                   "Z": 0.0
75               },
76               {
77                   "id": "2",
78                   "info": "b",
79                   .
80                   .
81                   .
82               }
83           ]
84       },
85       "geoTransform": [
86           440720.000000000000000,
87           60.000000000000000,
88           0.0,
89           3751320.000000000000000,
90           0.0,
91           -60.000000000000000
92       ],
93       "cornerCoordinates":{
94         "upperLeft":[
95           440720.0,
96           3751320.0
97         ],
98         "lowerLeft":[
99           440720.0,
100           3750120.0
101         ],
102         "upperRight":[
103           441920.0,
104           3751320.0
105         ],
106         "lowerRight":[
107           441920.0,
108           3750120.0
109         ],
110         "center":[
111           441320.0,
112           3750720.0
113         ]
114       },
115       "wgs84Extent":{
116         "type":"Polygon",
117         "coordinates":[
118         [
119           [
120             -117.642054,
121             33.9023677
122           ],
123           [
124             -117.6419729,
125             33.8915454
126           ],
127           [
128             -117.6290752,
129             33.9024346
130           ],
131           [
132             -117.6289957,
133             33.8916123
134           ],
135           [
136             -117.642054,
137             33.9023677
138           ]
139          ]
140         ]
141       },
142       "rat": { (if -norat not specified)
143           "row0Min": 40918,
144           "binSize": 1,
145           "fieldDefn": [
146               {
147                   "index": 0,
148                   "name": "Histogram",
149                   "type": "integer",
150                   "usage": "PixelCount"
151               },
152               {
153                   "index": 1,
154                   "name": "fieldName2",
155                   "type": 2,
156                   "usage": 2
157               },
158           ],
159           "rows": [
160               {
161                   "index": 0,
162                   "f": [
163                       1,
164                       4
165                   ]
166               },
167               {
168                   "index": 1,
169                   "f": [
170                       5,
171                       4
172                   ]
173               },
174               .
175               .
176               .
177           ]
178       },
179       "metadata": { (if -nomd not specified)
180           "": {
181               "key1": "value1"
182           },
183           "IMAGE_STRUCTURE": {
184               "key1": "value1"
185           },
186           "OTHER_DOMAIN": {
187               "key1": "value1"
188           },
189       },
190       "cornerCoordinates": {
191           "upperLeft": [
192               440720.000,
193               3751320.000
194           ],
195           "lowerLeft": [
196               440720.000,
197               3750120.000
198           ],
199           "upperRight": [
200               441920.000,
201               3751320.000
202           ],
203           "lowerRight": [
204               441920.000,
205               3750120.000
206           ],
207           "center": [
208               441320.000,
209               3750720.000
210           ]
211       },
212       "bands": [
213           {
214               "description": "...",
215               "band": 1,
216               "block": [
217                   20,
218                   20
219               ],
220               "type": "Byte",
221               "colorInterp": "Gray",
222               "min": 74.000,
223               "max": 255.000,
224
225               "computedMin": 74.000, (if -mm specified)
226               "computedMax": 255.000,
227
228               "minimum": 74.000, (if -stats specified)
229               "maximum": 255.000,
230               "mean": 126.765,
231               "stdDev": 22.928,
232
233               "unit": "....",
234               "offset": X,
235               "scale": X,
236               "noDataValue": X,
237               "overviews": [
238                   {
239                       "size": [
240                           400,
241                           400 ],
242                       "checksum": X (if -checksum specified)
243                   },
244                   {
245                       "size": [
246                           200,
247                           200 ],
248                       "checksum": X (if -checksum specified)
249                   }
250               ],
251               "mask": {
252                   "flags": [
253                       "PER_DATASET",
254                       "ALPHA"
255                   ],
256                   "overviews": [
257                       {
258                           "size": [
259                               400,
260                               400 ]
261                       },
262                       {
263                           "size": [
264                               200,
265                               200 ],
266                       }
267                   ]
268               },
269               "metadata": { (if -nomd not specified)
270                   "__default__": {
271                       "key1": "value1"
272                   },
273                   "IMAGE_STRUCTURE": {
274                       "key1": "value1"
275                   },
276                   "OTHER_DOMAIN": {
277                       "key1": "value1"
278                   },
279               },
280               "histogram": { (if -hist specified)
281                   "count": 25,
282                   "min": -0.5,
283                   "max": 255.5,
284                   "buckets": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
285               },
286               "checksum": 4672, (if -checksum specified)
287               "colorTable": { (if -noct not specified)
288                   "palette": "RGB",
289                   "count": 6,
290                   "entries": [
291                       [255,255,255,255],
292                       [255,255,208,255],
293                       [255,255,204,255],
294                       [153,204,255,255],
295                       [0,153,255,255],
296                       [102,102,102,255]
297                   ]
298               }
299           },
300           {
301               "band": 2,
302               "block": [
303                   20,
304                   20
305               ],
306               .
307               .
308               .
309           }
310       ]
311   }
312
313Impacted drivers
314----------------
315
316None.
317
318Impacted utilities
319------------------
320
321gdalinfo
322
323-  Adds a "-xml" output option.
324-  Adds a "-json" output option.
325
326ogrinfo
327
328-  Adds a "-xml" output option.
329-  Adds a "-json" output option.
330
331Backward Compatibility
332----------------------
333
334This change has no impact on backward compatibility at the C API/ABI and
335C++ API/ABI levels. Default output will remain the same. The new XML
336output will only effect users who specify "-xml" or "-json" on the
337command line.
338
339Testing
340-------
341
342The Python autotest suite will be extended to test the new XML/JSON
343outputs and existing tests will be modified to check STDERR for
344diagnostic messages.
345
346Ticket
347------
348
349No tickets.
350
351Voting history
352--------------
353
354Proposed.
355