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 (dan.bramich@hotmail.co.uk)
;
; History:
;
; 24/04/2009 - Further module optimisation performed (dmb).
; 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