1.. _rfc-4: 2 3========================================================================= 4RFC 4: Geolocation Arrays 5========================================================================= 6 7Author: Frank Warmerdam 8 9Contact: warmerdam@pobox.com 10 11Status: Development 12 13Summary 14------- 15 16It is proposed that GDAL support an additional mechanism for geolocation 17of imagery based on large arrays of points associating pixels and lines 18with geolocation coordinates. These arrays would be represented as 19raster bands themselves. 20 21It is common in AVHRR, Envisat, HDF and netCDF data products to 22distribute geolocation for raw or projected data in this manner, and 23current approaches to representing this as very large numbers of GCPs, 24or greatly subsampling the geolocation information to provide more 25reasonable numbers of GCPs are inadequate for many applications. 26 27Geolocation Domain Metadata 28--------------------------- 29 30Datasets with geolocation information will include the following dataset 31level metadata items in the "GEOLOCATION" domain to identify the 32geolocation arrays, and the details of the coordinate system and 33relationship back to the original pixels and lines. 34 35- SRS: wkt encoding of spatial reference system. 36- X_DATASET: dataset name (defaults to same dataset if not specified) 37- X_BAND: band number within X_DATASET. 38- Y_DATASET: dataset name (defaults to same dataset if not specified) 39- Y_BAND: band number within Y_DATASET. 40- Z_DATASET: dataset name (defaults to same dataset if not specified) 41- Z_BAND: band number within Z_DATASET. (optional) 42- PIXEL_OFFSET: pixel offset into geo-located data of left geolocation 43 pixel 44- LINE_OFFSET: line offset into geo-located data of top geolocation 45 pixel 46- PIXEL_STEP: each geolocation pixel represents this many geolocated 47 pixels. 48- LINE_STEP: each geolocation pixel represents this many geolocated 49 lines. 50 51In the common case where two of the bands of a dataset are actually 52latitude and longitude, and so the geolocation arrays are the same size 53as the base image, the metadata might look like: 54 55:: 56 57 SRS: GEOGCS... 58 X_BAND: 2 59 Y_BAND: 3 60 PIXEL_OFFSET: 0 61 LINE_OFFSET: 0 62 PIXEL_STEP: 1 63 LINE_STEP: 1 64 65For AVHRR datasets, there are only 11 points (note, the more recent NOAA 66AVHRR datasets have 51 points), but for every line. So the result for a 67LAC dataset might look like: 68 69:: 70 71 SRS: GEOGCS... 72 X_DATASET: L1BGCPS:n12gac10bit.l1b 73 X_BAND: 1 74 Y_DATASET: L1BGCPS:n12gac10bit.l1b 75 Y_BAND: 2 76 PIXEL_OFFSET: 25 77 LINE_OFFSET: 0 78 PIXEL_STEP: 40 79 LINE_STEP: 1 80 81This assumes the L1B driver is modified to support the special access to 82GCPs as bands using the L1BGCPS: prefix. 83 84Updating Drivers 85---------------- 86 871. HDF4: Client needs mandate immediate incorporation of geolocation 88 array support in the HDF4 driver (specifically for swath products). 89 (complete) 902. HDF5: Some HDF5 products include geolocation information that should 91 be handled as arrays. No timetable for update. 923. AVHRR: Has 11/51 known locations per-scanline. These are currently 93 substantially downsampled and returned as GCPs, but this format would 94 be an excellent candidate for treating as geolocation arrays. Planned 95 in near future. 964. Envisat: Envisat raw products use geolocation information currently 97 subsampled as GCPs, good candidate for upgrade. No timetable for 98 update. 995. netCDF: NetCDF files can have differently varying maps in x and y 100 directions, which are represented as geolocation arrays when they are 101 encoded as CF conventions "two-dimensional coordinate variables". See 102 the netcdf driver page for details. 1036. OPeNDAP: Can have differently varying maps in x and y directions 104 which could be represented as geolocation arrays when they are 105 irregular. No timetable for update. 106 107Changes to Warp API and gdalwarp 108-------------------------------- 109 110Introduce a new geolocation array based transformation method, following 111the existing GDALTransformer mechanism. A geolocation array transformer 112will be created with the following function call. The "char \**" array 113is the list of metadata from the GEOLOCATION metadata domain. 114 115:: 116 117 void *GDALCreateGeoLocTransformer( GDALDatasetH hBaseDS, 118 char **papszGeolocationInfo, 119 int bReversed ); 120 121This transformer is currently partially implemented, but in a manner 122that potentially uses a great deal of memory (twice the memory needed 123for the geolocation arrays), and with still dubious correctness, but 124once approved this will be fixup up to at least be correct, though 125likely not efficient for the time being. 126 127The GDALGenImgProjTransformer will be upgraded to instantiate the GeoLoc 128transformer (instead of an affine, gcp, or rpc transformer) if only 129geolocation information is available (done). However, the current 130GDALCreateGenImgProjTransformer() function does not provide a mechanism 131to select which transformation mechanism is used. So, for instance, if 132an affine transform is available it will be used in preference to 133geolocation data. If bGCPUseOK is TRUE, gcps will be used in preference 134to geolocation data. 135 136The gdalwarp program currently always sets bGCPUseOK to TRUE so there is 137no means for gdalwarp users select use of geolocation data in preference 138to gcps. Some modification to gdalwarp may be needed in the future in 139this regard. 140 141Preserving Geolocation Through Translation 142------------------------------------------ 143 144| ''How do we preserve access to geolocation information when 145 translating a dataset? Do applications like gdal_translate need 146 special handling? 147| Placement of the geolocation data in a special metadata domain means 148 it won't be transferred in default translations.'' 149