% @(#)filtercosm.hlq	17.1.1.1 (ESO-IPG) 01/25/02 17:43:36
%++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
%.COPYRIGHT  (c)  1990 European Southern Observatory
%.IDENT      filtercosm.hlq
%.AUTHOR     P.Magain,M.Remy Institut d'Astrophysique de Liege
%.KEYWORDS   MIDAS, help files, FILTER/COSMIC
%.PURPOSE    On-line help file for the command: FILTER/COSMIC
%.VERSION    1.0 November 1991 ,creation PM/MP 
%----------------------------------------------------------------
\se
SECTION./COSM
\es\co
FILTER/COSMIC	                                         21-NOV-1991 PM,MR 
\oc\su
FILTER/COSMIC inframe  outframe sky,gain,ron,[ns],[rc] [mask]
                                                  remove cosmic ray events.
\us\pu
Purpose: 
         Remove cosmic ray events on a single CCD image and replace
         them by a local median value.
\up\sy
Syntax:  
         FILTER/COSMIC inframe outframe sky,gain,ron,[ns,rc] [mask]
\ys\pa
         inframe = raw input frame
\ap\pa
         outframe = output frame
\ap\pa
         sky,gain,ron,ns,rc = \\ sky level (sky), inverse gain factor (e-/ADU)
              (gain), read-out-noise (in ADU) (ron), threshold for the 
              detection of cosmic rays (ns), and critical ratio for 
              discrimination of objects and cosmic rays (rc).
              The detection threshold is in units of the theoretical noise 
              sigma of each pixel; it's default value is 4. The default for 
              `rc' is 2.
\ap\pa
         mask = name of an optional frame containing the value 1 for cosmic
              rays and 0 for all other pixels.
\ap\no
Note: 
         a) The algorithm works as follows:
\\
         1. The input image is filtered in the following way:
\\
         FILTER/MEDIAN inframe middumma 1,1,0.0 NA
         For Long-Slit spectra of extended sources, the algorithm may be
         more efficient if the median filter works only along the slit.
\\ 
         2. The input image is compared with the filtered image. All pixels
         with an intensity I  greater than  Im+ns*sigma  are suspicious and
         may be cosmic rays (Im is the filtered intensity of a pixel and
         sigma is given by: sigma**2 = ron**2+I/gain).
\\
         3. All suspicious pixels are grouped into sets of contiguous points.
         In each of these sets, the pixel with the maximum intensity Imax is 
         selected. If (Imax-sky) is greater than rc*(Iaver-sky), Iaver being 
         an average of the intensities of the first eight neighbours of that
         pixel, the whole set of points is considered as a cosmic ray event.
\\
         4. The intensities of the pixels affected by cosmic rays are 
         replaced by a median value calculated over the nearest neighbours of
         the group to which they belong.  
\\     
         b) In many situations, rc is the most critical parameter and requires
         careful fine-tuning. If it is choosen too small, small sources such
         as stars may be affected. If rc is too large, the filter may not
         remove weak partical hits superimposed to reasonably well exposed
         extended sources.       
\on\see
See also:
         FILTER/MEDIAN
\ees\exs
Examples:
\ex
         FILTER/COSMIC ccd ccdclean 150,1,4,4,2.3 cosmask
           Apply cosmic filtering to image `ccd.bdf' and store result frame
           as `ccdclean.bdf';
\\
           save a 0/1 mask in `cosmask.bdf'.
\xe\sxe