RFC 4: Geolocation Arrays
Author: Frank Warmerdam
Contact: warmerdam@pobox.com
Status: Adopted, implemented
Summary
It is proposed that GDAL support an additional mechanism for geolocation of imagery based on large arrays of points associating pixels and lines with geolocation coordinates. These arrays would be represented as raster bands themselves.
It is common in AVHRR, Envisat, HDF and netCDF data products to distribute geolocation for raw or projected data in this manner, and current approaches to representing this as very large numbers of GCPs, or greatly subsampling the geolocation information to provide more reasonable numbers of GCPs are inadequate for many applications.
Geolocation Domain Metadata
Datasets with geolocation information will include the following dataset level metadata items in the "GEOLOCATION" domain to identify the geolocation arrays, and the details of the coordinate system and relationship back to the original pixels and lines.
SRS: wkt encoding of spatial reference system.
X_DATASET: dataset name (defaults to same dataset if not specified)
X_BAND: band number within X_DATASET.
Y_DATASET: dataset name (defaults to same dataset if not specified)
Y_BAND: band number within Y_DATASET.
Z_DATASET: dataset name (defaults to same dataset if not specified)
Z_BAND: band number within Z_DATASET. (optional)
PIXEL_OFFSET: pixel offset into geo-located data of left geolocation pixel
LINE_OFFSET: line offset into geo-located data of top geolocation pixel
PIXEL_STEP: each geolocation pixel represents this many geolocated pixels.
LINE_STEP: each geolocation pixel represents this many geolocated lines.
GEOREFERENCING_CONVENTION: (added in GDAL 3.5) either TOP_LEFT_CORNER to indicate that the X/Y values refer to the top-left corner of the pixel, or PIXEL_CENTER to indicate that they refer to the center of the pixel. The default is TOP_LEFT_CORNER.
In the common case where two of the bands of a dataset are actually latitude and longitude, and so the geolocation arrays are the same size as the base image, the metadata might look like:
SRS: GEOGCS...
X_BAND: 2
Y_BAND: 3
PIXEL_OFFSET: 0
LINE_OFFSET: 0
PIXEL_STEP: 1
LINE_STEP: 1
For AVHRR datasets, there are only 11 points (note, the more recent NOAA AVHRR datasets have 51 points), but for every line. So the result for a LAC dataset might look like:
SRS: GEOGCS...
X_DATASET: L1BGCPS:n12gac10bit.l1b
X_BAND: 1
Y_DATASET: L1BGCPS:n12gac10bit.l1b
Y_BAND: 2
PIXEL_OFFSET: 25
LINE_OFFSET: 0
PIXEL_STEP: 40
LINE_STEP: 1
This assumes the L1B driver is modified to support the special access to GCPs as bands using the L1BGCPS: prefix.
Updating Drivers
HDF4: Client needs mandate immediate incorporation of geolocation array support in the HDF4 driver (specifically for swath products). (complete)
HDF5: Some HDF5 products include geolocation information that should be handled as arrays. No timetable for update.
AVHRR: Has 11/51 known locations per-scanline. These are currently substantially downsampled and returned as GCPs, but this format would be an excellent candidate for treating as geolocation arrays. Planned in near future.
Envisat: Envisat raw products use geolocation information currently subsampled as GCPs, good candidate for upgrade. No timetable for update.
netCDF: NetCDF files can have differently varying maps in x and y directions, which are represented as geolocation arrays when they are encoded as CF conventions "two-dimensional coordinate variables". See the netcdf driver page for details.
OPeNDAP: Can have differently varying maps in x and y directions which could be represented as geolocation arrays when they are irregular. No timetable for update.
Changes to Warp API and gdalwarp
Introduce a new geolocation array based transformation method, following the existing GDALTransformer mechanism. A geolocation array transformer will be created with the following function call. The "char **" array is the list of metadata from the GEOLOCATION metadata domain.
void *GDALCreateGeoLocTransformer( GDALDatasetH hBaseDS,
char **papszGeolocationInfo,
int bReversed );
This transformer is currently partially implemented, but in a manner that potentially uses a great deal of memory (twice the memory needed for the geolocation arrays), and with still dubious correctness, but once approved this will be fixup up to at least be correct, though likely not efficient for the time being.
The GDALGenImgProjTransformer will be upgraded to instantiate the GeoLoc transformer (instead of an affine, gcp, or rpc transformer) if only geolocation information is available (done). However, the current GDALCreateGenImgProjTransformer() function does not provide a mechanism to select which transformation mechanism is used. So, for instance, if an affine transform is available it will be used in preference to geolocation data. If bGCPUseOK is TRUE, gcps will be used in preference to geolocation data.
The gdalwarp program currently always sets bGCPUseOK to TRUE so there is no means for gdalwarp users select use of geolocation data in preference to gcps. Some modification to gdalwarp may be needed in the future in this regard.