1.. _rfc-14: 2 3================================================================================ 4RFC 14: Image Structure Metadata 5================================================================================ 6 7Author: Frank Warmerdam 8 9Contact: warmerdam@pobox.com 10 11Status: Adopted 12 13Summary 14------- 15 16This RFC attempts to formalize the semantics of the "IMAGE_STRUCTURE" 17domain of metadata. This metadata domain is used to hold structural 18information about image organization that would not normally be carried 19with an image when translated into another format. The IMAGE_STRUCTURE 20metadata may occur on the GDALDataset or on individual bands, and most 21items are meaningful in both contexts. When items like NBITS are found 22on the dataset it is assumed they apply to all bands of that dataset. 23 24IMAGE_STRUCTURE items 25--------------------- 26 27COMPRESSION:: The compression type used for this dataset or band. There 28is no fixed catalog of compression type names, but where a given format 29includes a COMPRESSION creation option, the same list of values should 30be used here as there. 31 32NBITS:: The actual number of bits used for this band, or the bands of 33this dataset. Normally only present when the number of bits is 34non-standard for the datatype, such as when a 1 bit TIFF is represented 35through GDAL as GDT_Byte. 36 37INTERLEAVE:: This only applies on datasets, and the value should be one 38of PIXEL, LINE or BAND. It can be used as a data access hint. 39 40PIXELTYPE:: This may appear on a GDT_Byte band (or the corresponding 41dataset) and have the value SIGNEDBYTE to indicate the unsigned byte 42values between 128 and 255 should be interpreted as being values between 43-128 and -1 for applications that recognise the SIGNEDBYTE type. 44 45Compatibility Issues 46-------------------- 47 48This RFC has two changes from existing practise that may cause 49compatibility issues: 50 511. Traditionally the NBITS metadata appeared in the default metadata 52 domain on datasets, instead of in the IMAGE_STRUCTURE domain. 532. Traditionally the COMPRESSION metadata appeared only on the dataset, 54 never one the band. 55 56I am only aware of one application previously making systematic use of 57these items, and it will be updated to reflect the new usage as GDAL 581.5.0 is adopted. 59 60Development 61----------- 62 63Beyond adopting the definition for the semantics of the IMAGE_STRUCTURE 64metadata, the following development steps will be taken: 65 661. The PNG, GTiff, NITF and EHdr drivers will be updated to place NBITS 67 in the IMAGE_STRUCTURE metadata domain. 682. The HFA driver will be updated to return NBITS metadata. 693. The HFA, GTiff, JP2KAK, ECW, JPEG, and PNG drivers will be updated to 70 return INTERLEAVE metadata. 714. The HFA and GTiff drivers will be updated to return PIXELTYPE 72 metadata. 73 74The development will be done by Frank Warmerdam in trunk in time for 75GDAL/OGR 1.5.0 release. Changes to other drivers that these definitions 76might be useful for while be done as time permits by interested 77developers - not necessarily in time for GDAL/OGR 1.5.0. 78 79Notes 80----- 81 82- The gdalinfo utility already reports IMAGE_STRUCTURE metadata when it 83 is available. 84- The GTiff, and HFA drivers CreateCopy() methods check the source for 85 NBITS, and PIXELTYPE metadata to create specialized output files 86 types. 87- The GTiff, HFA and default CreateCopy() implementations have been 88 reworked to use the new GDALDatasetCopyWholeRaster() function which 89 uses the INTERLEAVE metadata as a clue whether to do interleaved 90 copies if the source dataset is interleaved. 91