PRO create_polynomial_2darr, xsize, ysize, fx, fy, x0, y0, polyterms, polycoeffs, hires, parr, status, danidl_cppcode
; Description: This module creates a two-dimensional output pixel array "parr" representing a polynomial
; surface over an image area of "xsize" by "ysize" pixels. The output pixel array coordinates
; (x,y) are related to a transformed set of coordinates (X,Y) as follows:
;
; X = fx*(x - x0)
; Y = fy*(y - y0)
;
; The polynomial surface, as a function of the coordinates (X,Y), is then defined by the
; polynomial terms "polyterms" and the corresponding polynomial coefficients "polycoeffs".
; The pixel values in the output pixel array are calculated from a pixel grid that samples
; the polynomial surface 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.
; 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.5 times faster than the IDL
; code in this case.
;
; Input Parameters:
;
; xsize - INTEGER/LONG - The size (pix) along the x-axis of the output pixel array. This parameter
; must be positive.
; ysize - INTEGER/LONG - The size (pix) along the y-axis of the output pixel array. This parameter
; must be positive.
; fx - FLOAT/DOUBLE - The x coordinate scale factor as defined above. This parameter must be non-zero.
; fy - FLOAT/DOUBLE - The y coordinate scale factor as defined above. This parameter must be non-zero.
; x0 - FLOAT/DOUBLE - The x coordinate offset (pix) as defined above.
; y0 - FLOAT/DOUBLE - The y coordinate offset (pix) as defined above.
; polyterms - INTEGER/LONG ARRAY - A 2 by "nterms" array of values where each pair of numbers
; represents the exponents of the x and y spatial variables for
; each polynomial term. All values in this array must be
; non-negative. Note that since IDL treats a 2 by 1 array as a
; two-element one-dimensional vector, this module accepts such a
; two-element one-dimensional vector to represent the case when
; "nterms" is equal to "1".
; 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 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:
;
; parr - DOUBLE ARRAY - A two-dimensional rectangular array of size "xsize" by "ysize" pixels
; representing the required polynomial surface.
; status - INTEGER - If the module successfully created the output array "parr", 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 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:
;
; 13/11/2010 - Module created (dmb).
;Set the default output parameter values
;Check that "xsize" and "ysize" are positive numbers of the correct type
;Check that "fx", "fy", "x0" and "y0" are numbers of the correct type, and that "fx" and "fy" are non-zero
;Check that "polyterms" is a number array of the correct number type, dimensions and size, 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
;Extract the list of powers of x and the list of powers of y from the parameter "polyterms"
;Determine the unique set of polynomial terms
;If the only unique polynomial term is a constant term
;Create the output pixel array with the values set to the value of the constant term
;Set "status" to "1" and finish
;Generate the transformed coordinate vectors for the oversampled output pixel array
;Determine the unique set of powers of x and the unique set of powers of y
;Calculate the unique set of powers of the vectors of x and y coordinates
;Set up the oversampled output pixel array
;For each unique polynomial term
;Extract the current unique polynomial term
;If the current unique polynomial term is a constant, then move on to the next unique polynomial term
;Extract the current powers of x and y
;Collect the like polynomial terms and calculate a single polynomial coefficient
;If the single polynomial coefficient is zero, then move on to the next unique polynomial term
;Extract the corresponding power of the vector of x coordinates
;Extract the corresponding power of the vector of y coordinates
;Calculate the current polynomial term and add it to the oversampled output pixel array
;Bin the oversampled output pixel array by the oversampling factor "hires"
;Set "status" to "1"