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