1.. _rfc-43:
2
3=======================================================================================
4RFC 43: GDALMajorObject::GetMetadataDomainList
5=======================================================================================
6
7Author: Even Rouault
8
9Contact: even dot rouault at spatialys.com
10
11Summary
12-------
13
14This (mini)RFC proposes a new virtual method, GetMetadataDomainList(),
15in the GDALMajorObject class (and a C API) to return the list of all
16available metadata domains.
17
18Background
19----------
20
21GDALMajorObject currently offers the GetMetadata() and GetMetadataItem()
22methods that both accept a metadata domain argument. But there is no way
23to auto-discover which metadata domains are valid for a given
24GDALMajorObject (i.e. a dataset or raster band). This make it impossible
25to have generic code that can exhaustively discover all metadata in a
26dataset/raster band.
27
28Implementation
29--------------
30
31The base implementation in GDALMajorObject just calls GetDomainList() on
32the internal oMDMD member.
33
34::
35
36   /************************************************************************/
37   /*                      GetMetadataDomainList()                         */
38   /************************************************************************/
39
40   /**
41    * \brief Fetch list of metadata domains.
42    *
43    * The returned string list is the list of (non-empty) metadata domains.
44    *
45    * This method does the same thing as the C function GDALGetMetadataDomainList().
46    *
47    * @return NULL or a string list. Must be freed with CSLDestroy()
48    *
49    * @since GDAL 1.11
50    */
51
52   char **GDALMajorObject::GetMetadataDomainList()
53   {
54       return CSLDuplicate(oMDMD.GetDomainList());
55   }
56
57This method is also available in the C API ( char \*\* CPL_STDCALL
58GDALGetMetadataDomainList( GDALMajorObjectH hObject) ) and Swig
59bindings.
60
61Impacted drivers
62----------------
63
64Drivers that have custom implementations of GetMetadata() and/or
65GetMetadataItem() will generally have to also implement
66GetMetadataDomainList(), when they don't modify the oMDMD member.
67
68To make it easy to implement the specialized GetMetadataDomainList(),
69GDALMajorObject will offer a protected BuildMetadataDomainList() method
70that can be used like the following :
71
72::
73
74   /************************************************************************/
75   /*                      GetMetadataDomainList()                         */
76   /************************************************************************/
77
78   char **NITFDataset::GetMetadataDomainList()
79   {
80       return BuildMetadataDomainList(GDALPamDataset::GetMetadataDomainList(),
81                                      TRUE,
82                                      "NITF_METADATA", "NITF_DES", "NITF_DES_METADATA",
83                                      "NITF_FILE_HEADER_TRES", "NITF_IMAGE_SEGMENT_TRES",
84                                      "CGM", "TEXT", "TRE", "xml:TRE", "OVERVIEWS", NULL);
85   }
86
87The TRUE parameter means that the list of domains that follows are
88potential domains, and thus BuildMetadataDomainList() will check for
89each one that GetMetadata() returns a non-NULL value.
90
91An exhaustive search in GDAL drivers has been made and all drivers that
92needed to be updated to implement GetMetadataDomainList() have been
93updated: ADRG, BAG, CEOS2, DIMAP, ECW, ENVISAT, ERS, GeoRaster (cannot
94check myself that it compiles), GIF, GTiff, HDF4, JPEG, MBTILES, netCDF,
95NITF, OGDI, PCIDSK, PDF, PNG, PostgisRaster, RasterLite, RS2, VRT, WCS,
96WebP, WMS.
97
98A few caveats :
99
100-  For MBTiles, WMS and VRT, GetMetadataDomainList(), at the band level,
101   will return "LocationInfo" as a valid metadata domain (used by the
102   gdallocationinfo utility), even if GetMetadata("LocationInfo") itself
103   does not return metadata : you have to call
104   GetMetadataItem("Pixel_someX_someY", "LocationInfo") or
105   GetMetadataItem("GeoPixel_someX_someY", "LocationInfo").
106-  For CEOS2 and ENVISAT, the list of metadata domains cannot be
107   established easily. GetMetadataDomainList() will return the pattern
108   of accepted domain names.
109
110Impacted utilities
111------------------
112
113The gdalinfo utility is extended to accept :
114
115-  a "-listmdd" option that will print the metadata domains available,
116
117::
118
119   $ gdalinfo ../autotest/gdrivers/data/byte_with_xmp.jpg -listmdd
120
121   Driver: JPEG/JPEG JFIF
122   Files: ../autotest/gdrivers/data/byte_with_xmp.jpg
123   Size is 20, 20
124   Coordinate System is `'
125   Metadata domains:
126     xml:XMP
127   Corner Coordinates:
128   Upper Left  (    0.0,    0.0)
129   Lower Left  (    0.0,   20.0)
130   Upper Right (   20.0,    0.0)
131   Lower Right (   20.0,   20.0)
132   Center      (   10.0,   10.0)
133   Band 1 Block=20x1 Type=Byte, ColorInterp=Gray
134     Metadata domains:
135       IMAGE_STRUCTURE
136     Image Structure Metadata:
137       COMPRESSION=JPEG
138
139-  and "-mdd all" will display the content of all metadata domains.
140
141::
142
143   $ gdalinfo ../autotest/gdrivers/data/byte_with_xmp.jpg -mdd all
144
145   Driver: JPEG/JPEG JFIF
146   Files: ../autotest/gdrivers/data/byte_with_xmp.jpg
147   Size is 20, 20
148   Coordinate System is `'
149   Metadata (xml:XMP):
150   <?xpacket begin='' id='W5M0MpCehiHzreSzNTczkc9d'?>
151   <x:xmpmeta xmlns:x='adobe:ns:meta/' x:xmptk='Image::ExifTool 7.89'>
152   <rdf:RDF xmlns:rdf='http://www.w3.org/1999/02/22-rdf-syntax-ns#'>
153
154    <rdf:Description rdf:about=''
155     xmlns:dc='http://purl.org/dc/elements/1.1/'>
156     <dc:description>
157      <rdf:Alt>
158       <rdf:li xml:lang='x-default'>Description</rdf:li>
159      </rdf:Alt>
160     </dc:description>
161     <dc:subject>
162      <rdf:Bag>
163       <rdf:li>XMP</rdf:li>
164       <rdf:li>Test</rdf:li>
165      </rdf:Bag>
166     </dc:subject>
167     <dc:title>
168      </rdf:Alt>
169     </dc:title>
170    </rdf:Description>
171
172    <rdf:Description rdf:about=''
173     xmlns:tiff='http://ns.adobe.com/tiff/1.0/'>
174     <tiff:BitsPerSample>
175      <rdf:Seq>
176       <rdf:li>8</rdf:li>
177      </rdf:Seq>
178     </tiff:BitsPerSample>
179     <tiff:Compression>1</tiff:Compression>
180     <tiff:ImageLength>20</tiff:ImageLength>
181     <tiff:ImageWidth>20</tiff:ImageWidth>
182     <tiff:PhotometricInterpretation>1</tiff:PhotometricInterpretation>
183     <tiff:PlanarConfiguration>1</tiff:PlanarConfiguration>
184     <tiff:SamplesPerPixel>1</tiff:SamplesPerPixel>
185    </rdf:Description>
186   </rdf:RDF>
187   </x:xmpmeta>
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212   <?xpacket end='w'?>
213   Corner Coordinates:
214   Upper Left  (    0.0,    0.0)
215   Lower Left  (    0.0,   20.0)
216   Upper Right (   20.0,    0.0)
217   Lower Right (   20.0,   20.0)
218   Center      (   10.0,   10.0)
219   Band 1 Block=20x1 Type=Byte, ColorInterp=Gray
220     Image Structure Metadata:
221       COMPRESSION=JPEG
222
223Backward Compatibility
224----------------------
225
226This change has no impact on backward compatibility at the C API/ABI and
227C++ API levels. But it impacts C++ ABI, so it requires a full rebuild of
228all GDAL drivers.
229
230Testing
231-------
232
233The Python autotest suite will be extended to test the new API in a few
234drivers.
235
236Ticket
237------
238
239Ticket #5275 has been opened to track the progress of this RFC.
240
241The implementation is available in `an attachment to ticket
2425275 <http://trac.osgeo.org/gdal/attachment/ticket/5275/getmetadatadomainlist.patch>`__.
243
244Voting history
245--------------
246
247+1 from EvenR, DanielM and JukkaR
248