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