= RFC 22: RPC Georeferencing =

Author: Frank Warmerdam[[BR]]
Contact: warmerdam@pobox.com[[BR]]
Status: Proposed

== Summary ==

It is proposed that GDAL support an additional mechanism for geolocation
of imagery based on rational polynomial coefficients (RPCs) represented
as metadata.

Many modern raw satellite products are distributed with RPCs, including
products from !GeoEye, and !DigitalGlobe.   RPCs provide a higher systematic
description of georeferencing over an image, and also contain information
on the viewing geometry that in theory makes orthocorrection (given 
a DEM) and some 3D operations like building height computation possible.

== RPC Domain Metadata ==

Datasets with RPCs will include the following dataset level
metadata items in the "RPC" domain to identify the rational polynomials. 

* ERR_BIAS: Error - Bias. The RMS bias error in meters per horizontal axis of all points in the image (-1.0 if unknown)
* ERR_RAND: Error - Random. RMS random error in meters per horizontal axis of each point in the image (-1.0 if unknown)
* LINE_OFF: Line Offset
* SAMP_OFF: Sample Offset
* LAT_OFF: Geodetic Latitude Offset
* LONG_OFF: Geodetic Longitude Offset
* HEIGHT_OFF: Geodetic Height Offset
* LINE_SCALE: Line Scale
* SAMP_SCALE: Sample Scale
* LAT_SCALE: Geodetic Latitude Scale
* LONG_SCALE: Geodetic Longitude Scale
* HEIGHT_SCALE: Geodetic Height Scale
* LINE_NUM_COEFF (1-20): Line Numerator Coefficients. Twenty coefficients for the polynomial in the Numerator of the rn equation. (space separated)
* LINE_DEN_COEFF (1-20): Line Denominator Coefficients. Twenty coefficients for the polynomial in the Denominator of the rn equation. (space separated)
* SAMP_NUM_COEFF (1-20): Sample Numerator Coefficients. Twenty coefficients for the polynomial in the Numerator of the cn equation. (space separated)
* SAMP_DEN_COEFF (1-20): Sample Denominator Coefficients. Twenty coefficients for the polynomial in the Denominator of the cn equation. (space separated)

These fields are directly derived from the document prospective GeoTIFF RPC document at:
  
  http://geotiff.maptools.org/rpc_prop.html

== Updating Drivers ==

# NITF: Already supports RPCs in this model, but will be modified to put them in the RPC domain instead of the primary metadata domain.  Add support for .RPB files.
# GTiff: Will be upgraded to support reading Digital Globe .RPB files, and possibly support for Space Imaging rpc.txt files. 

== Changes to !GenImgProj Transformer ==

Currently it is difficult to reliably create a warp transformer based on RPCs
using GDALGenImgProjTransformer() as it will use a geotransform in preference
to RPCs if available.  Many images with useful RPC information also include
a geotransform (approximate or accurate).  It is therefore proposed to modify
the GDALCreateGenImgProjTransformer() function to make it practical to provide
more direction in the creation of the transformer.  The proposed new function
is:

{{{
void *
GDALCreateGenImgProjTransformer2( GDALDatasetH hSrcDS, GDALDatasetH hDstDS, 
                                  char **papszOptions );
}}}

Supported Options:

 * SRC_SRS: WKT SRS to be used as an override for hSrcDS.
 * DST_SRS: WKT SRS to be used as an override for hDstDS.
 * GCPS_OK: If false, GCPs will not be used, default is TRUE. 
 * MAX_GCP_ORDER: the maximum order to use for GCP derived polynomials if possible.  The default is to autoselect based on the number of GCPs.  A value of -1 triggers use of Thin Plate Spline instead of polynomials.
 * METHOD: may have a value which is one of GEOTRANSFORM, GCP_POLYNOMIAL, GCP_TPS, GEOLOC_ARRAY, RPC to force only one geolocation method to be considered on the source dataset. 
* RPC_HEIGHT: A fixed height to be used with RPC calculations.

This replaces the older function which did not include support for
passing arbitrary options, and was thus not easily extended.  The old
function will be re-implemented with a call to the new functions.

The most important addition is the METHOD option which can be set to 
specifically use one of the image to georeferenced coordinate system 
methods instead of leaving it up to the code to pick the one it thinks
is best.

== Changes to gdalwarp and gdaltransform ==

In order to facilitate passing transformer options into the updated 
GDALCreateGenImgProjTransformer2(), the gdalwarp and gdaltransform 
programs (built on this function) will be updated to include a -to (transformer
option) switch, and to use the new function. 

== Preserving Geolocation Through Translation ==

The RPC information needs to be copied and preserved through translations
that do not alter the spatial arrangement of the data.  To that end RPC 
metadata copying will be added to:

 * VRT driver's !CreateCopy().
 * GDALDriver's default !CreateCopy().
 * GDALPamDataset::!CopyInfo()
 * gdal_translate will be updated to copy RPC metadata to the intermediate internal VRT if, and only if, no resizing or subsetting is being done.

== Backward Compatability Issues ==

Previously the NITF driver returned RPC metadata in the default domain.  With the implementation of this RFC for GDAL 1.6.0 any applications using this metadata would need to consult the RPC domain instead. 

== SWIG Bindings Issues ==

 * The raw access is by the established metadata api, so no changes are needed for this.
 * The Warp API is only bound at a high level, so there should be no changes in this regard.

== Implementation ==

This work will be implemented by Frank Warmerdam with support from the Canadian Nuclear Safety Commission.