% @(#)ifiltemedi.hlq	17.1.1.1 (ESO-DMD) 01/25/02 17:11:28 
%++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
%.COPYRIGHT  (c)  1997 European Southern Observatory
%.IDENT      ifiltemedi.hlq
%.AUTHOR     T.B.Gerogiev, IA, Sofia, tsgeorg@phys.acad.bg
%.KEYWORDS   MIDAS, help files, IFILTER/MEDIAN
%.PURPOSE    On-line help file for the command: IFILTER/MEDIAN
%.VERSION    1.0  NOV-1997 : Creation, TG, KB
%----------------------------------------------------------------
\se
SECTION./MEDI
\es\co
IFILTER/MEDIAN                                   29-NOV-1997  TG,KB   	
\oc\su
IFILTER/MEDIAN inp_fr out_fr windim coef [rsd_fr]
\us\pu
Purpose: 
            Apply median filter to an integer frame using approx. circular
            window around pixels.
\up\sub
Subject:  
            Image smoothing, image defects, nonlinear filtering.
\bus\sy
Syntax:  
            IFILTER/MEDIAN inp_fr out_fr windim coef [rsd_fr]
\ys\pa
            inp_fr = input frame 
\\
                should hold short signed integer data (16 bit integers)
\ap\pa
            out_fr = optional result frame
\\
                defaulted to no output frame
\ap\pa
            windim = window diameter in pixels, 1 < wd < 100 pixels,
\\
                the area "around" the central pixels which defines the
                neighbourhood (NBH) of that pixel is an approximation of 
                a circle with `windim' as its diameter; 
\\
                if wd=2 the window consists of 5 pixels,
                the current pixel plus its 4 axial neibours;
\\  
                if wd=3 the window consists of 9 pixels,
                a 3x3 square, centered on the current pixel;
\\
                if wd=4 we have the previous case with addition of
                4 axial pixels and the number of all pixels is 13;
\\
                if wd=5 the window consists of 21 pixels, 
                a 5x5 square with the 4 corner pixels removed;
\\
                if wd=6 we have a 5x5 square of 25 pixels;
\\  
                if wd=7 we have 37 pixels, this is a 7x7 square
                but 3 pixels in each corner (12 pixels) are removed; 
\\
                wd=8,9,10,11,12 (49,69,81,97,113 pixels in NBH), etc...
\\
                defaulted to 25 (489 pixels in NBH)
\ap\pa
             coef = coefficient for threshold (real value >= 0.0)
\\
                if `coef' = 0.0 the program will execute usual median
                smoothing;
\\
                If `coef' > 0 a pixel is only replaced by the median in
                its NBH, if the deviation of the current pixel value 
                from the median value is larger than the threshold T = coef*S ,
                with S the estimation of the standard deviation   
                of the pixel values in the NBH (S is calculated as half
                of the histogram interval containing 66% of the pixels in NBH)
\\
                defaulted to 0.0
\ap\pa
            rsd_fr = optional residual frame,
\\
                rsd_fr = inp_fr - out_fr
\\
                defaulted to no residual frame
\ap\see
See also:
              IFILTER/SMOOTH, FILTER/MEDIAN
\ees\no
Note:
              The image is smoothed by:
\\ 
              1) calculating M(x,y), the median of all points in
                 the neighbourhood of the current pixel (x,y)
\\
              2) calculating S(x,y), a simple  estimate of the 
                 standard deviation of the pixel values in the NBH,
                 that is the half of the interval containing
                 66% of the pixel values in the NBH
\\
              3) replacing always the original value I(x,y) by M(x,y)
                 if `thresh' = 0.0, or
                 replacing I(x,y) by M(x,y) only if
                 abs(M(x,y)-I(x,y)) > `thresh'*S,
                 for `thresh' > 0.0
\on\exs
Examples:
\ex
           IFILTER/MEDIAN f1 f1s 33
             Smooth the frame `f1.bdf' using circular NBH with diameter
             of 33 pixels and produce the smoothed frame `f1s.bdf'.
\xe\ex
           IFILTER/MEDIAN f1 ? 9 ? f1r 
             Smooth the frame `f1.bdf' using NBH with 69 pixels
             and produce the residual image `f1r.bdf' 
\xe\ex           
           IFILTER/MEDIAN f1 f1c 3 3.5  
             Clean frame `f1.bdf' and produce `f1c.bdf'. Use the median in
             a 3x3 pixels square NBH and the threshold T=3.5*S, where
             S is the estimate of the standard deviation in the NBH.
             If the current pixel value difers more than T from the median,
             it is replaced by the median.
\\
             Note, that in the regions of the frame filled with stellar
             images the local value of S will be larger then in the 
             background regions. Thus, if the threshold value is suitable
             (usually 3.5) the program may remove strong cosmics or defects 
             without changing the central peaks of the stellar images. 
\xe\ex
           IFILTER/MEDIAN gala gala_s 15 0.0 gala_r 
             Divide the frame `gala.bdf' into two components, a smoothed
             frame, `galas.bdf' and a residual frame, `galar.bdf'
             using window size of 177 pixels. The residual frame may be cleaned
             and than added to the smoothed frame for restoring the original 
             frame.
\xe \sxe