FUNCTION gaussian_2d_arr, hsize, fwhm_a, fwhm_b, x0, y0, theta, hires
; Description: This function creates a two-dimensional output pixel array representing an (elliptical)
; Gaussian profile with a major axis of FWHM "fwhm_a" pixels, a minor axis of FWHM "fwhm_b"
; pixels, an angle "theta" in degrees as measured anti-clockwise from the x-axis to the
; major axis, and its centre at pixel coordinates "(hsize + 0.5 + x0, hsize + 0.5 + y0)".
; The output pixel array is returned as a square array of side "(2*hsize) + 1" pixels. The
; pixel values are calculated from a pixel grid that samples the Gaussian profile at "hires"
; times the resolution of the output pixel array, which gives the user the option of
; accurately calculating the integrals over the discrete pixels. Finally, the output pixel
; array is normalised to a peak value of 1.
;
; Input Parameters:
;
; hsize - INTEGER/LONG - The output array is returned as a square array of side "(2*hsize) + 1" pixels.
; If this parameter is negative, then it will be reset to "0".
; fwhm_a - FLOAT/DOUBLE - The Gaussian major axis FWHM (pix). This parameter must be positive, or the
; function will fail and return a value of "0.0".
; fwhm_b - FLOAT/DOUBLE - The Gaussian minor axis FWHM (pix). This parameter must be positive, or the
; function will fail and return a value of "0.0".
; x0 - FLOAT/DOUBLE - The offset along the x-axis of the Gaussian centre from the centre of the output
; pixel array (pix).
; y0 - FLOAT/DOUBLE - The offset along the y-axis of the Gaussian centre from the centre of the output
; pixel array (pix).
; theta - FLOAT/DOUBLE - The angle as measured anti-clockwise from the x-axis to the Gaussian major
; axis (deg).
; hires - INTEGER/LONG - The oversampling factor to be used to calculate the output pixel array. This
; parameter has a minimum allowed value of "1", corresponding to no oversampling,
; and a maximum allowed value of "10", to protect against unnecessary oversampling
; using too much memory allocation.
;
; Return Value:
;
; The function returns a square pixel array of DOUBLE precision values and of side "(2*hsize) + 1"
; pixels representing the required Gaussian profile. If the function fails, then it returns a value
; of "0.0".
;
; Author: Dan Bramich (dan.bramich@hotmail.co.uk)
;
; History:
;
; 24/04/2009 - Further module optimisation performed resulting in a ~59.1% speed increase (dmb).
; 16/07/2008 - Module created (dmb)
;Force the half size of the output pixel vector to be at least zero
;Check the parameters "fwhm_a", "fwhm_b", "x0", "y0" and "theta"
;Force the oversampling factor to be at least 1, and limit its maximum value to 10
;Convert the Gaussian FWHMs to Gaussian sigmas
;Generate the coordinate arrays for the oversampled pixel array
;Calculate the values of the Gaussian profile for the oversampled pixel array
;Bin the oversampled pixel array by the oversampling factor "hires"
;Normalise the output pixel array to a peak value of 1
;Return the output pixel array representing the Gaussian profile