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 (dmb@ing.iac.es) ; ; History: ; ; 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 pixel 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