PRO image_median_replace, imdata, bpmdata, mask, width, status

; Description: This module replaces pixels in an image "imdata" with the median of surrounding 
;              good pixels in a box of width "width" pixels centred at each pixel, where the 
;              set of pixels to be replaced are identified using a pixel replacement mask 
;              "mask". Bad pixels are flagged via a bad pixel mask "bpmdata". Pixel values 
;              that are to be replaced are not used in the median calculations. 
; 
; Input Parameters:
;   
;   imdata - FLOAT/DOUBLE ARRAY - The image array for which pixels are to be replaced. 
;   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".
;   mask - BYTE/INTEGER/LONG ARRAY - A two dimensional array of the same size as "imdata" that 
;                                    contains the mask of image pixels to be replaced. Pixels
;                                    to be replaced should have a mask value of "1", while
;                                    pixels to be left unmodified should have a mask value of 
;                                    "0". If this array does not have the same dimensions as 
;                                    "imdata", then the module will do nothing.
;   width - INTEGER/LONG - The width of the box to be used to calculate the median replacement 
;                          pixel values (pix). If this parameter is less than "3", then the 
;                          module will do nothing. If this parameter is an even number, then it 
;                          will be incremented by one to force an odd value.
;
; Output Parameters:
;
;   imdata - DOUBLE ARRAY - The input image array with the relevant pixels replaced.
;   bpmdata - INTEGER ARRAY - The bad pixel mask corresponding to the modified image data "imdata".
;   status - INTEGER - If the module was successful in completing the pixel replacement
;                      operations, the "status" is set to "1". Otherwise, if the module was not
;                      successful in completing the pixel replacement operations, then "status"
;                      is set to "0".
;
; Author: Dan Bramich (dmb@ing.iac.es)
;
; History:
;
;   26/06/2008 - Module created (dmb)  

;Check that "imdata" is an image of the correct number type

;If "bpmdata" is not an image of the correct number type and dimensions, then assume that all 
;image pixels are good

;Check that "mask" is an image of the correct number type and dimensions

;Check that "width" is a number of the correct type and that it has a value of at least "3"

;If the parameter "width" is even, then add 1

;Determine the total number of good pixels in the image

;If there are no good pixels in the image, then return with the parameter "status" equal to "0",
;and without doing anything

;Determine the total number of pixels in the image to be replaced

;If all pixels in the image "imdata" are to be replaced, then this is impossible, and hence 
;return with the parameter "status" equal to "0"

;If no pixels in the image "imdata" are to be replaced, then return with the parameter "status"
;equal to "1"

;Pad the input image and the input bad pixel mask

;Create the output image and output bad pixel mask

    ;If the current pixel needs to be replaced, then determine what to replace it with

      ;Create some image cut outs

      ;Identify the good pixels that are not to be replaced in the input image cut out

      ;If there is at least one good pixel that is not to be replaced in the input image 
      ;cut out, then set the current pixel in the output image to the median of these 
      ;good pixels, and record the current pixel as good in the output bad pixel mask

      ;If all pixels in the input image cut out are bad or to be replaced, then set the   
      ;current pixel in the output image to zero, and record the current pixel as bad
      ;in the output bad pixel mask

;Set the "status" parameter to "1"