PRO dandia_model_image, refdata, bpmdata, ker_im, hksize, subframes_x, subframes_y, xrsize, yrsize, reg_xc, reg_yc, reg_npix_out, reg_ps, reg_back, reg_tag, $
; Description: This module constructs an image model "im_model" from the reference image "refdata" for subsequent
; use in creating a difference image. The module uses a previously determined (spatially variant or
; invariant) kernel solution "ker_im" to convolve the reference image, and then applies the relevant
; photometric scale factor and differential sky background (again both spatially variant or
; invariant) to produce the image model. The module also returns a 2-sigma clipped weighted mean
; photometric scale factor and a 2-sigma clipped weighted mean differential sky background.
; The parameter "diffpro" allows the user to control the method used to construct the image model.
; This may be done on a pixel by pixel basis, which is slow but fully accurate, or it may be done
; by assuming that the kernel solution is invariant over a subgroup of pixels equal to a size of a
; tenth of each image region, which is anywhere between 10 to 100 times faster with very little loss
; in accuracy.
; 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 ~??? times faster than the IDL code in this case.
;
; Input Parameters:
;
; refdata - FLOAT/DOUBLE ARRAY - The reference image array to be used in constructing the image model.
; bpmdata - BYTE/INTEGER/LONG ARRAY - A bad pixel mask array of the same size as "refdata" which flags bad pixels
; in the image for which the image model is to be constructed. If this array
; does not have the same dimensions as "refdata", then all image pixels will
; be considered good, and "bpmdata" will be set to an array of the same
; dimensions as "refdata" with all values equal to "1". Note that this bad
; pixel mask should include the bad pixels from the image for which the
; image model is to be constructed, and the bad pixels from "refdata" grown
; by the kernel size and shape.
; ker_im - FLOAT/DOUBLE ARRAY - An image array of dimensions "subframes_x*ksize" by "subframes_y*ksize" pixels,
; where "ksize" is given by "(2*hksize) + 1" (see subsequent parameters), that stores
; the grid of normalised kernel solutions. The layout of the grid of kernel solutions
; corresponds directly with the layout of the image regions used to solve for the
; kernels.
; hksize - INTEGER/LONG - The half kernel size (pix) such that the side of the kernel pixel array is of length
; "(2*hksize) + 1" pixels.
; subframes_x - INTEGER/LONG - The number of subdivisions of the image in the x direction used in defining the
; grid of image regions and kernel solutions.
; subframes_y - INTEGER/LONG - The number of subdivisions of the image in the y direction used in defining the
; grid of image regions and kernel solutions.
; xrsize - INTEGER/LONG - The image region size along the x-axis (pix). All image regions have the same
; dimensions.
; yrsize - INTEGER/LONG - The image region size along the y-axis (pix). All image regions have the same
; dimensions.
; reg_xc - FLOAT/DOUBLE VECTOR - A vector of length "subframes_x*subframes_y" values, where each value represents
; the mean x coordinate of the good pixels in the corresponding image region.
; reg_yc - FLOAT/DOUBLE VECTOR - A vector of length "subframes_x*subframes_y" values, where each value represents
; the mean y coordinate of the good pixels in the corresponding image region.
; reg_npix_out - INTEGER/LONG VECTOR - A vector of length "subframes_x*subframes_y" values, where each value
; represents the final number of image pixels used in the kernel and
; differential background solution.
; reg_ps - FLOAT/DOUBLE VECTOR - A vector of length "subframes_x*subframes_y" values, where each value represents
; the photometric scale factor for the corresponding image region.
; reg_back - FLOAT/DOUBLE VECTOR - A vector of length "subframes_x*subframes_y" values, where each value
; represents the differential sky background for the corresponding image region.
; reg_tag - BYTE/INTEGER/LONG VECTOR - A vector of length "subframes_x*subframes_y" values, where each value
; represents the success or failure of the kernel solution for the corresponding
; image region. A value of "1" signifies that the kernel solution for the image
; region was successful, and a value of "0" signifies that the kernel solution
; for the image region was unsuccessful.
; ps_var - INTEGER/LONG - If this parameter is set to "0", then the module assumes that the photometric scale
; factor is spatially invariant and that it is fully specified by a single value. If this
; parameter is set to "1", then the module assumes that the photometric scale factor is
; spatially variant, and the module will determine the photometric scale factor for each
; pixel in the image for which the image model is to be constructed. The photometric scale
; factor is important when producing the difference image, and unless there is variable
; extinction across the image area (or the flat fielding was not done correctly), then it
; should be spatially invariant. Hence the default value is "0".
; back_var - INTEGER/LONG - If this parameter is set to "0", then the module assumes that the differential sky
; background is spatially invariant and that it is fully specified by a single value. If
; this parameter is set to "1", then the module assumes that the differential sky
; background is spatially variant, and the module will determine the differential sky
; background for each pixel in the image for which the image model is to be constructed.
; The differential sky background is important when producing the difference image, and
; generally there is a variable sky background across the image area. Hence the default
; value is "1".
; diffpro - INTEGER/LONG - This parameter is a switch controlling the method used to produce the image model. The
; following parameter values are accepted (Default value = 0):
;
; (i) A value of "0" means that for each image pixel, the corresponding kernel is formed
; as a bilinear interpolation of the kernel solutions for the nearest image regions to
; the image pixel. If "ps_var" is set to "1", then the corresponding photometric scale
; factor is determined in the same way. If "back_var" is set to "1", then the
; corresponding differential sky background is determined in the same way.
;
; (ii) A value of "1" means that for each group of image pixels of size equal to a tenth
; of the size of an image region used for determining the kernel solution, the
; corresponding kernel is formed as a bilinear interpolation of the kernel solutions
; for the nearest image regions to the current group of image pixels. If "ps_var" is
; set to "1", then the corresponding photometric scale factor is determined in the
; same way. If "back_var" is set to "1", then the corresponding differential sky
; background is determined in the same way. This method is much faster than the one
; outlined in (ii), and it is similar in accuracy if the assumption that the kernel
; solution is approximately constant over the group of image pixels is valid.
;
; DanIDL_C_code - STRING - The full directory path indicating where the DanIDL C++ code is installed.
;
; Output Parameters:
;
; im_model - DOUBLE ARRAY - An image array of the the same dimensions as "refdata" that represents an image model
; for subsequent use in creating a difference image. The image model "im_model" is
; constructed by using the kernel solution "ker_im" to convolve the reference image,
; scaling by the photometric scale factor, and adding in the differential background.
; bpmout - INTEGER ARRAY - A bad pixel mask of the the same dimensions as "refdata" which flags bad pixels in the
; image model with a value of "0", and good pixels with a value of "1".
; ps_mean - DOUBLE - A 2-sigma clipped weighted mean photometric scale factor.
; back_mean - DOUBLE - A 2-sigma clipped weighted mean differential sky background (ADU).
; status - INTEGER - If the module successfully constructed the image model, then "status" is returned with a
; value of "1", otherwise it is returned with a value of "0".
;
; Keywords:
;
; If the keyword QUIET is set (as "/QUIET"), then the module will not print any progress messages on screen.
; This functionality is useful if the module is to be called many times within an image processing routine for
; instance.
;
; Author: Dan Bramich (dan.bramich@hotmail.co.uk)
;
; History:
;
; 20/04/2009 - Adjusted the code to be more efficient for both methods of difference image creation. A speed
; increase of ~10.6% was obtained for the option "diffpro = 0" (dmb).
; 21/10/2008 - Module created (dmb).
;
; This module does the following, treating bad pixels correctly at all stages:
;
; 1) Checks that the reference image array "refdata" is an image of the correct number type, and determines its
; dimensions. If "refdata" is not an image of the correct number type, then the module returns without doing
; anything.
;
; 2) Checks that the bad pixel mask "bpmdata" has the same dimensions as "refdata" and is of the correct number
; type. If this is not the case, then the module creates a bad pixel mask that flags every pixel in "refdata"
; as good.
;
; 3) Checks that the parameter "ker_im" is an image of the correct number type. If this is not the case, then the
; module returns without doing anything.
;
; 4) Checks the values of some of the input parameters, resetting them to default values where necessary, and
; returning without doing anything when parameter values are out of range.
;
; 5) Checks that the dimensions of "ker_im" match with the dimensions expected from the values of the parameters
; "hksize", "subframes_x" and "subframes_y".
;
; 6) Checks that "reg_xc", "reg_yc", "reg_npix_out", "reg_ps", "reg_back" and "reg_tag" are all vectors of the
; correct number type with "subframes_x*subframes_y" elements, and that "reg_tag" has at least one element
; with the value "1", indicating that the kernel solution process was successful for at least one image region.
;
; 7) Calculates the 2-sigma clipped weighted mean photometric scale factor, where each photometric scale factor
; is weighted by the final number of image pixels used in the corresponding kernel solution.
;
; 8) Calculates the 2-sigma clipped weighted mean differential sky background, where each differential sky
; background is weighted by the final number of image pixels used in the corresponding kernel solution.
;
; 9) If the number of image regions is equal to one, then the module moves on to step (10). If the number of image
; regions is greater than one, then the module moves on to step (11).
;
; 10) Constructs an image model by convolving the reference image with the constant kernel solution, multiplying
; the result by the mean photometric scale factor, and adding in the differential sky background solution. The
; module then finishes.
;
; 11) If the parameter "diffpro" is equal to "0", then the module moves on to step (12). If the parameter "diffpro"
; is equal to "1", then the module moves on to step (13).
;
; 12) For each image pixel, the module forms the corresponding kernel as a bilinear interpolation of the kernel
; solutions for the nearest image regions to the image pixel. If "ps_var" is set to "1", then the corresponding
; photometric scale factor is determined in the same way. If "back_var" is set to "1", then the corresponding
; differential sky background is determined in the same way. After forming the image model in this way, the
; module finishes.
;
; 13) For each group of image pixels of size equal to a tenth of the size of an image region used for determining
; the kernel solution, the module forms the corresponding kernel as a bilinear interpolation of the kernel
; solutions for the nearest image regions to the current group of image pixels. If "ps_var" is set to "1",
; then the corresponding photometric scale factor is determined in the same way. If "back_var" is set to "1",
; then the corresponding differential sky background is determined in the same way. After forming the image
; model in this way, the module finishes.
;If the keyword QUIET is set, then do not print progress messages
;Check that "refdata" is an image
;If "bpmdata" does not have the same dimensions as "refdata", then assume that all image pixels are good
;Check that "ker_im" is an image
;Check some of the input parameters, and reset them if necessary
;Check that the dimensions of "ker_im" make sense
;Check that "reg_xc", "reg_yc", "reg_npix_out", "reg_ps", "reg_back" and "reg_tag" are all vectors of the correct length
;Calculate the 2-sigma clipped weighted mean photometric scale factor
;Calculate the 2-sigma clipped weighted mean differential sky background
;If the number of image regions is equal to one, then construct an image model using the constant kernel and
;differential background solution
;Convolve the reference image with the constant kernel solution and add the differential background
;If the number of image regions is greater than one, then construct an image model using a spatially variable
;kernel and differential background solution
;If the parameter "diffpro" is equal to "0"
;For each column in the image model
;For each row in the image model
;If the current pixel is a good pixel in the bad pixel mask, then calculate the image model at this pixel
;Determine the distance of the centroid of each image region from the current image model pixel
;Determine the set of nearby image regions to be used in determining the kernel solution for the
;current image model pixel via interpolation
;If there is at least one appropriate nearby image region
;Determine the kernel solution for the current image model pixel by interpolating the kernel solutions
;for the nearby image regions
;Determine the photometric scale factor for the current image model pixel by interpolating the
;photometric scale factors for the nearby image regions
;Determine the differential sky background for the current image model pixel by interpolating the
;differential sky backgrounds for the nearby image regions
;Calculate the image model pixel value
;If there are no appropriate nearby image regions
;If the parameter "diffpro" is equal to "1"
;Determine the size of each group of image pixels over which the kernel and differential background solution
;will be assumed to be constant
;For each group of image pixels
;Extract the relevant image region from the reference image
;Determine the distance of the centroid of each image region from the centre of the current group of image pixels
;Determine the set of nearby image regions to be used in determining the kernel solution for the current group
;of image pixels via interpolation
;If there is at least one appropriate nearby image region
;Determine the kernel solution for the current group of image pixels by interpolating the kernel solutions
;for the nearby image regions
;Determine the photometric scale factor for the current group of image pixels by interpolating the
;photometric scale factors for the nearby image regions
;Determine the differential sky background for the current group of image pixels by interpolating the
;differential sky backgrounds for the nearby image regions
;Calculate the image model pixel values for the current group of image pixels
;If there are no appropriate nearby image regions
;Force bad pixels in the image model to have values of zero
;Finish