Calibration in GDAL

[Frank Warmerdam]

Andrey Kiselev wrote:
> Hi, Frank,
> 
> I'm thinking about adding calibration feature to the GDAL and I need your
> opinion. I'm suggest follows:
> 
> 1. Add a helper class for storing polinomial coefficients on per pixel
> basis. It may be something like
> 
> -----------
> class Calibration
> {
> int iOrder;
> double *padfCoefficients;
> 
> public:
> 
> Calibration( int, double * );
> ~Calibartion( );
> double CalibrateValue( double );
> 
> }
> 
> /* padfInputArray --- Array of polinomial coefficients */
> 
> Calibration::Calibration( int iOrder, double *padfInputArray )
> {
> if ( iOrder == 0 )
> return NULL;
> iOrder = ABS( iOrder );
> padfCoefficients = CPLMalloc( iOrder * sizeof(double) );
> 
> for ( int i = 0; i< iOrder; i++ )
> padfCoefficients[i] = padfInputArray[i];
> 
> }
> 
> double Calibration::CalibrateValue( double dfValue )
> {
> double dfCalibratedValue = 0;
> 
> for ( int i = iOrder; i > 0; i-- )
> dfCalibratedValue =
> (dfCalibratedValue + padfCoefficients[i]) * dfValue;
> 
> return dfCalibratedValue;
> }
> -----------
> 
> 2. Each driver which supports calibartion should define method
> 
> virtual double GDALRasterBand::GetCalibratedValue( int iXPos, int iYPos,
> double dfValue );
> 
> in the GDALRasterBand class. This method will return calibrated value for
> the specified pixel (value of pixel passed through dfValue parameter). In
> the Open() method for the dataset calibration array will be created and
> filled. In case of the same function for all pixels it will be something
> like (schematically)
> 
> Calibration *paCal = new Calibration[nBands];
> 
> If we have different functions for different rows it will be
> 
> Calibration **papCal = new Calibration[nBands][nYSize];
> 
> And if we have the same function for all rows
> 
> Calibration **papCal = new Calibration[nBands][nXSize];
> 
> 3. GDALRasterBand::RasterIO() method should take a flag indicating that we
> want to get calibrated values. Maybe something like GF_ReadCalibrated as the
> first parameter? Actually they will be calculated using
> GetCalibratedValue().
> 
> 
> What do you think about all of these?

Andrey,

I have included all of your original text above so others on the gdal list
can follow the discussion.

I think that:
o The calibration information has to be transportable from one driver to
another, so we should not entirely hide it within the driver.

o We should support a calibration scheme that can potentially support multiple
calibration model types without having to alter the public API.

Inorder to accomplish this I suggest that we implement a GDALCalibrationModel
class that initially:

o Can be initialized from a string list representation of a calibration model.
o Has a method to calibrate a single value given the value as a double and
the location as an integer pixel,line location from within the source image.
o Supports whatever polynomial scheme you initially need.
o Implement a convenience mechanism for storing calibration models in an
external text file. This mechanism could be easily plugged into formats
that don't currently support calibration in much the way we support world files
or external overview files for many formats now. Ensure this convenience
mechanism is utilized for GeoTIFF format.

and that would eventually offer methods for;
o Converting back to a string list model format.
o Altering the calibration model (if needed) to account for subsetting of an image.
o Support additional calibration models as we need them.
o Include a method on the GDALRasterBand() for reading calibrated data that
would internally take care of instantiating the GDALCalibrationModel ...
perhaps called CalibratedRasterIO() (read-only though).

I think that calibration models should be fetched, and set on the GDALRasterBand
via the metadata mechanism, using a special domain (perhaps "BMD_CALIBRATION_MODEL").
Within this special domain there would be standard keys for the calibration model
type, and perhaps a description field. The rest of the key/value pairs would be
model type specific. The whole stringlist of metadata from this domain is the
serialized format of the calibration model.

The one concern about my suggested approach is that for formats for which the
calibration model for the whole file would be very big it will be necessary to
convert it to the string list format, and back into a GDALCalibrationModel all
in memory. If we forsee this being a big problem we should rethink things a
bit.

Best regards,

-- 
---------------------------------------+--------------------------------------
I set the clouds in motion - turn up | Frank Warmerdam, warmerdam at p...
light and sound - activate the windows | http://pobox.com/~warmerdam
and watch the world go round - Rush | Geospatial Programmer for Rent