PRO create_polynomial_1dvec, xsize, fx, x0, polyterms, polycoeffs, hires, pvec, status
; Description: This module creates a one-dimensional output pixel vector "pvec" representing a polynomial
; curve over a coordinate vector of "xsize" pixels. The output pixel vector coordinate x
; is related to a transformed coordinate X as follows:
;
; X = fx*(x - x0)
;
; The polynomial curve, as a function of the coordinate X, is then defined by the polynomial
; terms "polyterms" and the corresponding polynomial coefficients "polycoeffs". The pixel
; values in the output pixel vector are calculated from a pixel grid that samples the
; polynomial curve 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.
;
; N.B: For reasons of efficiency and numerical accuracy, the method implemented in this
; module for calculating the values of the polynomial terms uses only multiplications
; and additions, avoiding the use of the exponentiation operation "^".
;
; Input Parameters:
;
; xsize - INTEGER/LONG - The length (pix) of the output pixel vector. This parameter must be positive.
; fx - FLOAT/DOUBLE - The x coordinate scale factor as defined above. This parameter must be non-zero.
; x0 - FLOAT/DOUBLE - The x coordinate offset (pix) as defined above.
; polyterms - INTEGER/LONG VECTOR - A one-dimensional vector of length "nterms" that contains the
; exponents of the x spatial variable for each polynomial term. All
; values in this vector must be non-negative.
; polycoeffs - FLOAT/DOUBLE VECTOR - A one-dimensional vector of length "nterms" that contains the
; set of polynomial coefficients corresponding to the polynomial
; terms defined by "polyterms".
; 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:
;
; pvec - DOUBLE VECTOR - A one-dimensional vector of length "xsize" pixels representing the required
; polynomial curve.
; status - INTEGER - If the module successfully created the output vector "pvec", then "status" is
; returned with a value of "1", otherwise it is returned with a value of "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:
;
; 26/11/2010 - Module created (dmb).
;Set the default output parameter values
;Check that "xsize" is a positive number of the correct type
;Check that "fx" and "x0" are numbers of the correct type, and that "fx" is non-zero
;Check that "polyterms" is a one-dimensional vector of the correct number type, and that it has no
;negative elements
;Check that "polycoeffs" is a one-dimensional vector of the correct number type with the correct number
;of elements
;Check that "hires" is a positive number of the correct type
;Determine the polynomial coefficients corresponding to a vector of polynomial terms that contains all
;of the input polynomial terms
;If the only polynomial term is a constant term
;Create the output pixel vector with the values set to the value of the constant term
;Set "status" to "1" and finish
;Generate the transformed coordinate vector for the oversampled output pixel vector
;Calculate the oversampled output pixel vector values, ignoring the contribution of the constant term
;Bin the oversampled output pixel vector by the oversampling factor "hires"
;If the constant term is non-zero, then add it to the output pixel vector
;Set "status" to "1"