PRO image_median_smooth, imdata, mask, width, DanIDL_C_code, status

; Description: This module smooths an image "imdata" using a median filter employing a box 
;              of width "width" pixels centred at each pixel. Image data values flagged by 
;              the mask image "mask" are not filtered and they are ignored in the calculation 
;              of the median within the box filter. This function will use C++ code if
;              possible to achieve a faster execution than the default IDL code. The C++ 
;              code is a factor of ~9.2 times faster than the IDL code in this case.
; 
; Input Parameters:
;   
;   imdata - FLOAT/DOUBLE ARRAY - An image array to be median filtered.
;   mask - BYTE/INTEGER/LONG ARRAY - A two dimensional array of the same size as "imdata" 
;                                    that contains the mask of image pixels not to be filtered 
;                                    and to be ignored in the median calculation. Pixels to be
;                                    filtered should have a mask value of "1", while pixels to
;                                    be left unfiltered should have a mask value of "0". If 
;                                    this array does not have the same dimensions as "imdata", 
;                                    then all image pixels will be filtered, and "mask" will be
;                                    set to an array of the same dimensions as "imdata" with all
;                                    values equal to "1".
;   width - INTEGER/LONG - The width of the median filter box (pix). If this parameter is 
;                          less than "1", then the module will do no filtering. If this 
;                          parameter is an even number, then it will be incremented by one 
;                          to force an odd value.
;   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 "<DanIDL_C_code>/dist/libDanIDL.so" within the 
;                            installation.
;
; Output parameters:
;
;   imdata - DOUBLE ARRAY - The input image array with the relevant pixels median filtered.
;   status - INTEGER - If the module was successful in completing the pixel filtering
;                      operation, the "status" is set to "1". Otherwise, if the module was 
;                      not successful in completing the pixel filtering operation, then 
;                      "status" is set to "0".
;
;   N.B: If the mask image "mask" flags the set of bad pixels in the input image "imdata", 
;        then the mask image is also valid for the output median filtered image, since the 
;        bad pixels are ignored.
;
; Author: Dan Bramich (dan.bramich@hotmail.co.uk)
;
; History:
;
;   20/06/2008 - Module created (dmb)  

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

;If "mask" is not an image of the correct number type and dimensions, then assume that all
;image pixels are to be filtered

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

;If the parameter "width" has a value of "1", then the input image will be unchanged by the
;median filter. Hence return a value for "status" of "1".

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

;Determine the total number of pixels in the image to be median filtered

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

;Determine if the shared library of DanIDL C++ routines is installed

;Pad the input image and the image pixel mask

;If the shared library of DanIDL C++ routines is installed, then use the C++ code
;to speed up the median filtering algorithm

  ;Median filter the input image, ignoring masked pixels

;If the shared library of DanIDL C++ routines is not installed, then use the default IDL code

  ;Median filter the input image, ignoring masked pixels

      ;If the current pixel is unmasked in the input image, then set its value to the 
      ;median of the unmasked pixels within the filter box

;Set the "status" parameter to "1"