FUNCTION fwhm_g2dfit, cutout, x0, y0, sky, a, model, NOCENTRE = nocentre

; Description: This function is designed for use by the function "fwhm.pro" and it fits a 
;              two-dimensional elliptical Gaussian function to input image data. The model that 
;              is fitted is:
;
;              g(x,y) = A + B*exp(-0.5*U(x,y))
;              U(x,y) = (X/C)^2 + (Y/D)^2
;              X(x,y) = (x - F)*cos(E) + (y - G)*sin(E)
;              Y(x,y) = (y - G)*cos(E) - (x - F)*sin(E)
;
;              The parameter A corresponds to the sky background (ADU).
;              The parameter B corresponds to the Gaussian peak value (ADU).
;              The parameters C and D are the sigmas (pix) of the elliptical Gaussian axes.
;              The parameter E is the angle (radians) as measured anti-clockwise from the x-axis 
;              to the elliptical Gaussian axis with sigma C.
;              The parameters F and G are the x and y coordinates of the centre of the Gaussian.
;                It is assumed that the parameters A and B will be positive since "fwhm.pro" is
;              designed to measure the full-width half-maximum (FWHM) of the point-spread
;              function (PSF) of an image containing sky background and stars. If the image sky
;              background is negative, then the fit may not converge properly, and if the fitted
;              value of B is negative, then the function reports that the fit has failed.
;                It is also assumed that the fitted Gaussian sigmas C and D will both be less 
;              than 20 pix (corresponding to FWHMs less than ~47.1 pix), since it is very rare in 
;              astronomical imaging to encounter better sampled PSFs than this. If either of the 
;              fitted Gaussian sigmas C or D are greater than 20, then the function reports that 
;              the fit has failed.
;
; Input Parameters:
;
;   cutout - FLOAT/DOUBLE ARRAY - A two-dimensional array of image data values.
;   x0 - FLOAT/DOUBLE - An initial estimate of the x pixel coordinate F of the centre of the 
;                       Gaussian to be fitted (pix). If the NOCENTRE keyword is set, then the 
;                       value of "x0" is used for the value of F and no adjustment of F takes
;                       place during the fitting process.
;   y0 - FLOAT/DOUBLE - An initial estimate of the y pixel coordinate G of the centre of the 
;                       Gaussian to be fitted (pix). If the NOCENTRE keyword is set, then the 
;                       value of "y0" is used for the value of G and no adjustment of G takes
;                       place during the fitting process.
;   sky - FLOAT/DOUBLE - An initial and reliable estimate of the value of parameter A (ADU).
;
; Output Parameters:
;
;   a - DOUBLE ARRAY - This parameter is returned as a seven-element vector of DOUBLES with the
;                      fitted values of A, B, C, D, E, F and G in order. If the NOCENTRE
;                      keyword is set, then the values of F and G are returned as "x0" and "y0"
;                      respectively via the last two elements of "a".
;   model - DOUBLE ARRAY - This input variable is returned as a two-dimensional array of DOUBLES
;                          representing model image values. 
;
; Return value:
;
;   The function returns a status value as an INTEGER. If the status value is "0", then the fit
;   has failed. If the status value is "1", then the fit was successful.
;
; Keywords:
;
;   If the keyword NOCENTRE is set (as "/NOCENTRE"), then the coordinates of the centre of the
;   fitted Gaussian are fixed at "(x0,y0)". In other words, no fitting for F and G is done in
;   this case. 
;
; Author: Dan Bramich (dmb@ing.iac.es)
;
; History:
;
;   28/07/2008 - Updated fitting to include optional fitting of the centre (dmb).
;   06/05/2008 - Module created (dmb)

;Check that "cutout" is an image of the correct number type

;Check that "cutout" contains enough pixels to perform the fit

;Check that "x0", "y0" and "sky" are numbers of the correct type

;Generate the coordinate arrays for the image data "cutout"

;Fit a one-dimensional Gaussian to the data to get an initial estimate of the parameters for the 
;two-dimensional elliptical Gaussian fit

;If the fit of the one-dimensional Gaussian to the image data was successful, then proceed with 
;the full two-dimensional fit

  ;Assign a common data block

  ;If the NOCENTRE keyword is set, then force the coordinates of the centre of the fitted 
  ;two-dimensional Gaussian to be fixed at "(x0,y0)"

  ;If the NOCENTRE keyword is not set, then limit the search for the coordinates of the centre 
  ;of the fitted two-dimensional Gaussian to be within the image data array

  ;Fit a two-dimensional elliptical Gaussian with a rotation parameter

  ;Check that the two-dimensional elliptical Gaussian fit was successful

    ;Force the sigmas of the fitted two-dimensional elliptical Gaussian to be positive

    ;Reduce the angle parameter to the range [0,pi]

    ;Update the fitted centre of the elliptical Gaussian

    ;If the height of the two-dimensional elliptical Gaussian is negative or either of the sigmas 
    ;is equal to zero or either of the sigmas is greater than 20, then record that there was a 
    ;problem with the fit

    ;If the fitted centre of the two-dimensional elliptical Gaussian is outside or on the edge of 
    ;the image data array, then record that there was a problem

  ;If the 2D elliptical Gaussian fit was unsuccessful, then record this

;Create a model image

;Return the status of the fit