PRO create_gaussian_2darr, hxsize, hysize, fwhm_a, fwhm_b, x0, y0, theta, hires, garr, status, danidl_cppcode, $
; Description: This module creates a two-dimensional output pixel array "garr" 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
; "(hxsize + 0.5 + x0, hysize + 0.5 + y0)". The output pixel array is returned as a
; rectangular array of size "(2*hxsize) + 1" by "(2*hysize) + 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. The user also has the option of
; normalising the Gaussian profile by its maximum value or by its sum.
; This module will use C++ code if possible to achieve a faster execution than the
; default IDL code. The C++ code can be up to a factor of ~1.7 times faster than the IDL
; code in this case.
;
; Input Parameters:
;
; hxsize - INTEGER/LONG - The half-size (pix) along the x-axis of the output pixel array such that
; the corresponding size is "(2*hxsize) + 1" pixels. This parameter must be
; non-negative.
; hysize - INTEGER/LONG - The half-size (pix) along the y-axis of the output pixel array such that
; the corresponding size is "(2*hysize) + 1" pixels. This parameter must be
; non-negative.
; fwhm_a - FLOAT/DOUBLE - The Gaussian major axis FWHM (pix). This parameter must be positive.
; fwhm_b - FLOAT/DOUBLE - The Gaussian minor axis FWHM (pix). This parameter must be positive.
; 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 must be positive. The minimum allowed value of "1" corresponds to
; no oversampling. Care should be taken with setting "hires" to large values
; due to the risk of running out of memory.
; danidl_cppcode - STRING - The full directory path indicating where the DanIDL C++ code is installed.
; The shared library of DanIDL C++ routines should exist as
; "/dist/libDanIDL.so" within the installation.
;
; Output Parameters:
;
; garr - DOUBLE ARRAY - A two-dimensional rectangular array of size "(2*hxsize) + 1" by "(2*hysize) + 1"
; pixels representing the required Gaussian profile.
; status - INTEGER - If the module successfully created the output array "garr", then "status" is
; returned with a value of "1", otherwise it is returned with a value of "0".
;
; Keywords:
;
; If the keyword NORMALISE_BY_MAX is set (as "/NORMALISE_BY_MAX"), then the output Gaussian profile
; "garr" is normalised to a peak value of "1.0".
;
; If the keyword NORMALISE_BY_SUM is set (as "/NORMALISE_BY_SUM"), then the output Gaussian profile
; "garr" is normalised to a sum of "1.0".
;
; N.B: In DanIDL, I adopt a pixel coordinate system such that the origin of the coordinate system is
; at the bottom left hand corner of the bottom left hand pixel in an image. Therefore, the centre
; of the bottom left hand pixel in an image has coordinates (0.5,0.5) in this coordinate system.
; For each full pixel moved to the right in the image, the x pixel coordinate increments by 1,
; and similarly for each full pixel moved up in the image, the y pixel coordinate increments by 1.
;
; Author: Dan Bramich (dan.bramich@hotmail.co.uk)
;
; History:
;
; 17/11/2010 - Added keywords NORMALISE_BY_MAX and NORMALISE_BY_SUM (dmb).
; 12/02/2010 - Module rewritten (dmb).
; 24/01/2010 - Further module optimisation performed resulting in a ~1.59 times speed increase (dmb).
; 16/01/2010 - Module created (dmb).
;Set the default output parameter values
;Check that "hxsize" and "hysize" are non-negative numbers of the correct type
;Check that "fwhm_a", "fwhm_b", "x0", "y0" and "theta" are numbers of the correct type, and that
;"fwhm_a" and "fwhm_b" are positive
;Check that "hires" is a positive number of the correct type
;Convert the Gaussian FWHMs to Gaussian sigmas
;Generate the coordinate vectors 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"
;If required, normalise the output Gaussian profile appropriately
;Set "status" to "1"