PRO fit_plane, imdata, weights, plane, A, B, C, x0, y0, status

; Description: This module fits a 3-parameter plane model to a set of image data "imdata".
;              The plane pixel values are modelled as:
;
;              P(x,y) = A + B*(x - x0) + C*(y - y0)
;
;              where P(x,y) is the plane pixel value, x and y are image pixel coordinates,
;              and A, B, C, x0 and y0 are parameters to be fitted/chosen. Each pixel may 
;              be weighted individually via a weight array "weights", where bad pixels may 
;              be flagged using zero (or negative) values. The values of "x0" and "y0" are 
;              chosen by the alogrithm to be close to the image centre for solution 
;              stability, and the values of the parameters A, B and C are solved for 
;              analytically using weighted least squares. An image of the fitted plane is 
;              returned via "plane" along with the values of A, B, C, x0 and y0.
; 
; Input Parameters:
;   
;   imdata - FLOAT/DOUBLE ARRAY - An image array to which the plane is to be fitted.
;   weights - FLOAT/DOUBLE ARRAY - An array of the same size as "imdata", that contains the
;                                  weights to be used when fitting the plane. If this array 
;                                  does not have the same dimensions as "imdata", then all 
;                                  the image values are weighted equally. Bad data values 
;                                  may be pre-flagged by setting the corresponding values 
;                                  in this array to zero (or negative values).
;
; Output Parameters:
;
;   plane - FLOAT ARRAY - An image array representing the fitted plane, with the same 
;                         dimensions as "imdata".
;   A - DOUBLE - The value of the fitted parameter A.
;   B - DOUBLE - The value of the fitted parameter B.
;   C - DOUBLE - The value of the fitted parameter C.
;   x0 - DOUBLE - The value of the parameter x0 chosen by the module.
;   y0 - DOUBLE - The value of the parameter y0 chosen by the module.
;   status - INTEGER - If the module successfully fit a plane to the image data, then "status"
;                      is returned with a value of 1, otherwise it is returned with a value
;                      of 0.
;
; N.B: The planar model that is fitted to the data is a linear model, and hence the module 
;      "pattern_scale_2d.pro" could be used to further streamline this code. However,
;      the overheads in feeding the parameters to "pattern_scale_2d.pro" are too prohibitive 
;      given the small size of the problem solved by this module, and hence I have opted to
;      code the solution directly.
;   
; Author: Dan Bramich (dan.bramich@hotmail.co.uk)
;
; History:
;
;   02/05/2008 - Module created (dmb)  

;Check that "imdata" is an image

;If "weights" is not an image of the correct number type or the same dimensions as "imdata", then 
;weight all data points equally, otherwise set any negative weights to zero.

;Determine the centre of "imdata"

;Create two coordinate arrays

;Calculate the elements of the matrix to be inverted

;Calculate the vector on the right

;Set up and invert the matrix

;If the matrix was inverted successfully

  ;Calculate the plane parameters

  ;Create a model plane image