PRO generate_polynomial_basis_2darr, xsize, ysize, fx, fy, x0, y0, polyterms, hires, polybasis, status, danidl_cppcode
; Description: This module generates a set of two-dimensional polynomial basis functions for an image
; area of "xsize" by "ysize" pixels. The two-dimensional image 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 basis functions, corresponding to the polynomial terms "polyterms",
; are calculated as a function of the transformed coordinates (X,Y), and they are stored
; in the output array "polybasis". The pixel values in the polynomial basis functions
; are calculated from a grid that samples the basis functions at "hires" times the
; resolution of the image pixels, 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 polynomial basis functions. This
; parameter must be positive.
; ysize - INTEGER/LONG - The size (pix) along the y-axis of the polynomial basis functions. 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".
; hires - INTEGER/LONG - The oversampling factor to be used to calculate the polynomial basis
; functions. 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:
;
; polybasis - DOUBLE ARRAY - A three-dimensional array of size "nterms" by "xsize" by "ysize"
; elements, where "nterms" is the number of polynomial terms in the
; input parameter "polyterms". This array contains the "nterms"
; polynomial basis functions (which are images) corresponding to
; each polynomial term. Hence the image "polybasis[i,*,*]" is the
; polynomial basis function corresponding to the ith polynomial term.
; status - INTEGER - If the module successfully generated the polynomial basis function array,
; 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:
;
; 10/12/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 "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
;Generate the output polynomial basis function array
;Set "status" to "1" and finish
;Generate the transformed coordinate vectors for the oversampled polynomial basis functions
;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 output polynomial basis function array
;For each unique polynomial term
;Extract the current unique polynomial term, and the current powers of x and y
;Determine the set of like polynomial terms
;If the current powers of x and y are both "0"
;Generate and store the polynomial basis function corresponding to the current unique polynomial term
;If at least one of the current powers of x and y is not "0"
;Extract the corresponding power of the vector of x coordinates
;Extract the corresponding power of the vector of y coordinates
;Generate the oversampled polynomial basis function corresponding to the current unique polynomial term
;Bin the oversampled polynomial basis function by the oversampling factor "hires"
;Store the polynomial basis function corresponding to the current unique polynomial term
;Set "status" to "1"