PRO create_gaussian_1dvec, hsize, fwhm, x0, hires, gvec, status, NORMALISE_BY_MAX = normalise_by_max, NORMALISE_BY_SUM = normalise_by_sum
; Description: This module creates a one-dimensional output pixel vector "gvec" representing a
; Gaussian profile with a FWHM of "fwhm" pixels, and its centre at the pixel coordinates
; "hsize + 0.5 + x0". The output pixel vector is returned as a vector of length
; "(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 vector, 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.
;
; Input Parameters:
;
; hsize - INTEGER/LONG - The output pixel vector is returned as a vector of length "(2*hsize) + 1"
; pixels. This parameter must be non-negative.
; fwhm - FLOAT/DOUBLE - The Gaussian FWHM (pix). This parameter must be positive.
; x0 - FLOAT/DOUBLE - The offset of the Gaussian centre from the centre of the output pixel vector
; (pix).
; hires - INTEGER/LONG - The oversampling factor to be used to calculate the output pixel vector.
; This parameter must be positive. The minimum allowed value of "1"
; corresponds to no oversampling.
;
; Output Parameters:
;
; gvec - DOUBLE VECTOR - A one-dimensional vector of length "(2*hsize) + 1" pixels representing the
; required Gaussian profile.
; status - INTEGER - If the module successfully creates the output vector "gvec", 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
; "gvec" 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
; "gvec" 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 left hand side of the left hand pixel in a vector. Therefore, the centre of the left
; hand pixel in a vector has an x coordinate of 0.5 in this coordinate system. For each full
; pixel moved to the right in the vector, the x 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).
; 24/01/2010 - Further module optimisation performed resulting in a ~1.22 times speed increase (dmb).
; 17/01/2010 - Module created (dmb).
;Set the default output parameter values
;Check that "hsize" is a non-negative number of the correct type
;Check that "fwhm" and "x0" are numbers of the correct type, and that "fwhm" is positive
;Check that "hires" is a positive number of the correct type
;Convert the Gaussian FWHM to a Gaussian sigma
;Generate the coordinate vector for the oversampled pixel vector
;Calculate the values of the Gaussian profile for the oversampled pixel vector
;Bin the oversampled pixel vector by the oversampling factor "hires"
;If required, normalise the output Gaussian profile appropriately
;Set "status" to "1"