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