PRO rmcosmic, imdata, bpmdata, masterflat, ron, gain, sigclip, sigfrac, flim, niter, cosmic_mask, ncosmicrays, DanIDL_C_code, QUIET = quiet ; Description: This module is designed to remove cosmic rays from reduced/calibrated images. ; The program is based on an algorithm employing Laplacian edge detection, which ; is fully described in the paper by Pieter G. van Dokkum (van Dokkum P.G., 2001, ; PASP, 113, 1420). This program uses a modified algorithm that takes into account ; bad pixels defined in a bad pixel mask. Since this algorithm uses a noise model, ; it is only appropriate to apply it to images that have been properly bias level ; subtracted. For the same reason, the CCD readout noise and gain should be well ; determined for accurate identification of cosmic ray pixels. ; This module will use C++ code if possible to achieve a faster execution than ; the default IDL code (within the DanIDL module "image_median_smooth.pro"). The ; C++ code is a factor of ~3.5 times faster than the IDL code in this case. ; ; Input Parameters: ; ; imdata - FLOAT/DOUBLE ARRAY - An image array for which cosmic rays are to be identified and ; removed. ; bpmdata - BYTE/INTEGER/LONG ARRAY - A bad pixel mask array of the same size as "imdata" ; which flags bad pixels with a value of "0" and good ; pixels with a value of "1". If this array does not have ; the same dimensions as "imdata", then all image pixels ; will be considered good, and "bpmdata" will be set to ; an array of the same dimensions as "imdata" with all ; values equal to "1". ; masterflat - FLOAT/DOUBLE ARRAY - An image array of the same size as "imdata" representing ; the normalised master flat field used to calibrate the ; image data. If this array does not have the same ; dimensions as "imdata", then all image pixels will be ; considered to be of equal sensitivity, and "masterflat" ; will be set to an array of the same dimensions as ; "imdata" with all values equal to "1.0". ; ron - FLOAT/DOUBLE - The CCD readout noise (ADU). A negative value of "ron" will be reset ; to "0.0". ; gain - FLOAT/DOUBLE - The CCD gain (e-/ADU). A zero or negative value of "gain" will be ; reset to "1.0". ; sigclip - FLOAT/DOUBLE - Threshold in sigma for cosmic ray detection on the Laplacian image ; (Recommended value = 4.5). A zero or negative value of "sigclip" ; will be reset to "4.5". ; sigfrac - FLOAT/DOUBLE - Fraction of "sigclip" to be used as a threshold for cosmic ray ; growth (Recommended value = 0.5). A zero or negative value of ; "sigfrac" will be reset to "0.5". ; flim - FLOAT/DOUBLE - Minimum contrast between the Laplacian image and the fine structure ; image (Recommended value = 2.0). A zero or negative value of "flim" ; will be reset to "2.0". ; niter - INTEGER/LONG - Maximum number of iterations to perform (Recommended value = 4). A ; zero or negative value of "niter" will be reset to "4". ; DanIDL_C_code - 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: ; ; imdata - DOUBLE ARRAY - The image array with the identified cosmic rays replaced by the ; median of the surrounding pixels. ; bpmdata - INTEGER ARRAY - An updated version of the image bad pixel mask that corresponds ; to the image array "imdata". ; cosmic_mask - INTEGER ARRAY - A mask array of the same size as "imdata" which identifies ; the pixels in "imdata" that have been replaced using the ; mask value "1", and those that have not been replaced using ; the mask value "0". ; ncosmicrays - LONG - The number of pixels in "imdata" that were identified as cosmic rays, ; and were consequently replaced by the median of the surrounding pixels. ; If this module fails, then this parameter is returned with a value of ; "-1". ; ; Keywords: ; ; If the keyword QUIET is set (as "/QUIET"), then the program 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. ; ; N.B: (i) Usually it is not necessary to modify the parameters "sigclip", "sigfrac", "flim" ; and "niter" from their default values. However, if the FWHM of the image is below ; critical sampling (~2.4 pix), then "flim" should be set to 5.0. ; ; (ii) If the directory specified by the parameter "DanIDL_C_code" does not contain the ; correct shared library of DanIDL C++ routines, then the program will automatically ; default to using the slower IDL code. ; ; Author: Dan Bramich (dmb@ing.iac.es) ; Note: The algorithms in this program were written based on an IDL program written by Pieter G. ; van Dokkum & Joshua Bloom. ; ; History: ; ; 30/06/2008 - Module created (dmb) ; ; This module does the following, treating bad pixels correctly at all stages: ; ; 1) Checks that the input image array "imdata" is an image of the correct number type, and ; determines its dimensions. If "imdata" is not an image of the correct number type, then ; the module returns without doing anything. ; ; 2) Checks that "bpmdata" has the same dimensions as "imdata" 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 ; "imdata" as good, using this new bad pixel mask to replace the values stored in "bpmdata". ; ; 3) Checks that "masterflat" has the same dimensions as "imdata" and is of the correct number ; type. If this is not the case, then the module creates a master flat field that represents ; every pixel in "imdata" as having equal sensitivities, using this new master flat field to ; replace the values stored in "masterflat". ; ; 4) Checks the values of some of the input parameters, resetting them to default values where ; necessary. ; ; 5) Grows the bad pixels in the bad pixel mask by 2 pixels. ; ; 6) Repeats steps (7)-(16) until either "niter" iterations have been carried out or no new cosmic ; rays are found on the current iteration. The program will then move onto step (17). ; ; 7) Creates the Laplacian image from the current image. ; ; 8) Creates a median smoothed version of the current image. ; ; 9) Constructs a noise model for the Laplacian image based on the median smoothed image. ; ; 10) Selects an initial set of pixels associated with cosmic rays based on the Laplacian image, ; its noise model and the detection threshold "sigclip". ; ; 11) Creates a fine structure image from various median smoothed versions of the current image. ; ; 12) Rejects cosmic ray pixels if they are also associated with real structure in the current ; image, as derived from the fine structure image and using the threshold parameter "flim". ; ; 13) Rejects cosmic ray pixels that are next to bad pixels. ; ; 14) Attempts to grow the cosmic ray pixels by up to 2 pixels using a lower noise threshold ; (the parameter "sigfrac" determines the factor by which the detection threshold is ; reduced). ; ; 15) Counts and reports the number of new cosmic ray pixels found. ; ; 16) Interpolates over the cosmic ray pixels using the median of surrounding good pixels in a ; 5x5 pixel box. ; ; 17) Reports the total number of cosmic ray pixels found and removed by the algorithm. ;If the keyword QUIET is set, then do not print progress messages ;Check that "imdata" is an image of the correct number type ;If "bpmdata" does not have the same dimensions as "imdata", then assume that all image pixels ;are good ;If "masterflat" does not have the same dimensions as "imdata", then assume that all image pixels ;are of equal sensitivity ;Check some of the input parameters, and reset them if necessary ;Determine if the shared library of DanIDL C++ routines is installed ;Set up the necessary kernels ;Create a bad pixel mask from the image bad pixel mask by growing bad pixels by 2 pixels ;Square the readout noise, and include the master flat field ;Iterate the cosmic ray removal ;Set bad pixels to zero ;Subsample the image by a factor of 2 ;Convolve the image with the Laplacian kernel ;Set negative values in the convolved image to zero ;Resample the convolved image to its original resolution ;Create a median smoothed version of the original image ;Create a noise model based on the median smoothed image ;Free up some memory ;Set all pixels in the sigma image above "sigclip" to 1, and all other pixels to 0 ;Create a fine structure image ;Free up some memory ;Reject tentative cosmic rays associated with real objects ;Free up some memory ;Reject tentative cosmic rays neighbouring bad pixels ;Grow the final selection of cosmic rays by up to 2 pixels ;Free up some memory ;Add the final selection of cosmic rays to the cosmic ray mask ;Interpolate over the new cosmic rays using the median of surrounding good pixels ;Free up some memory ;Increment the iteration number ;Report the total number of cosmic rays found