% @(#)illcorccd.hlq	19.1 (ESO-IPG) 02/25/03 14:15:01
%++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
%.COPYRIGHT  (c)  1993 European Southern Observatory
%.IDENT      illcorccd.hlq
%.AUTHOR     RHW, IPG/ESO
%.KEYWORDS   MIDAS, ccd package, ILLCOR/CCD
%.PURPOSE    On-line help file for the command: ILLCOR/CCD
%.VERSION    930827 RHW Documentation created
%---------------------------------------------------------------------
\se
SECTION./CCD
\es\co
ILLCOR/CCD                                                     25-Mar-1993 RHW
\oc\su
ILLCOR/CCD [in_spec] [out_frm] [xboxmn,xboxmx] [yboxmn,yboxmx] [clip] 
           [lowsig,higsig]
	Make flat field illumination correction frame(s)
\us\pu
Purpose: 
	Make flat field illumination correction frame(s)
\up\sy
Syntax:     
        ILLCOR/CCD [in_spec] [out_frm] [xboxmn,xboxmx] [yboxmn,yboxmx]
                   [clip] [lowsig,higsig]
\ys\pa
        in_spec = single flat frame or MIDAS CCD association table (with the 
                  extension .tbl) containing the names of the flat frame(s)
                  in the column :FF. Default input is taken from the keyword 
                  CCD_IN.
\ap\pa
        out_frm = name of the output illumination frame. Default output is the
                  name of the input table with extension "_ill". Only used in
                  case of single frame input for the first parameter. In 
                  case the input is a MIDAS table the name(s) of the 
                  output frame(s) will have the same name as the sky frame
                  field expanded with '_ill' (see below).
\ap\pa  
        xboxmn,xboxmx = minimum and maximum smoothing box size along the x 
                  axes.  The minimum box size is used at the edges and grows 
                  to the maximum size in the middle of the image.  This 
                  allows the smoothed image to better represent gradients 
                  at the edge of the image. If a size is less then 1 it is 
                  interpreted as a fraction of the image size. If a size is
                  greater than or equal to 1 then it is the box size in 
                  pixels.  A size greater than the size of image selects a 
                  box equal to the size of the image. Default values are taken
                  from the keyword IL_XBOX.
\ap\pa
        yboxmn,yboxmx = see above. Default values are taken from IL_YBOX.
\ap\pa
        clip =    Clean the input frame(s) of objects? If yes then a clipping 
                  algorithm is used to detect and exclude objects from the 
                  smoothing. Default taken from IL_CLIP.
\ap\pa
        lowsig,higgsig = sigma clipping thresholds above and below the 
                  smoothed illumination. Default values are taken from
                  the keyword IL_SIGMA. The keyword is only read in case 
                  clip=yes.
\ap\no
Note:     
        The command operates very similar to the command REDUCE/CCD, which
        the exception that the command not check for the exposure type of 
        the input frame. 

        In case the input is an association table the command will check for
        the existence of the flat frames. Flat frames that do not exit will be 
        created first, provided the association table contain the flat column. 
        Other relevant calibration frames for processing the flat frames, 
        will be taken from the corresponding calibration columns belonging to 
        the same science frame. Output illumination frame(s) will have the 
        same name as the original flat frame except for the extension `_ill'. 

        In the case of single frame input and all calibration frames input 
        will be taken from the SC_ keywords and must exist.\\

        The input flats are automatically processed up through dark current
        calibration before computing the illumination pattern. The illumination
        correction, the inverse of the illumination pattern, is applied by the 
        CCD package to remove the illumination pattern introduced by the flat 
        field. The combination of the flat field calibration and the 
        illumination correction based on the flat field is equivalent to 
        removing the illumination from the flat field (see ILLFLAT/CCD). This 
        two step calibration is generally used when the observations have been
        previously flat field calibrated.  This task is closely related to 
        SKYCOR/CCD which determines the illumination correction from a blank 
        sky frame; this is preferable to using the illumination from the flat 
        field as it corrects for the residual illumination error.\\

        The illumination frame is produced by heavily smoothing the calibrated
        flats frames using a moving "boxcar" average. The effects of objects 
        in the frames may be minimized by using a sigma clipping algorithm to 
        detect and exclude the objects from the average. The output 
        illumination frame can used by REDUCE/CCD to remove the illumination 
        pattern in the science frames.\\

        The IM_SEC keyword may be used to assign a region of interest for which
        the correction has to be done.\\

        For more information see the CCD chapter in Volume B of the User's 
        manual.
\on\see
See also:   
        SET/CCD, SHOW/CCD, HELP/CCD, REDUCE/CCD, SKYFLAT/CCD
\ees\exs
Examples:
\ex
        ILLCOR/CCD ccd_asstbl.tbl
        Reduce all flat frames in the flat field column in the ccd table 
        ccd_asstbl.tbl. Master calibration frames will be obtained from the
        same table. Do the calibration according to the keyword settings.
        After the calibrations are done create the illumination frames, using 
        the `IL_' keyword settings. Calibration frames will be taken from the 
        table redtbl.tbl
\xe\ex
        ILLCOR/CCD m100rraw m100rraw_il
        Start the ccd reduction sequence for the frame m100rraw. This input 
        frame should be present. The output frame will be m100rraw_il. In case
        only dark correction is to be applied the name of this calibration 
        frame will be obtained from the keyword SC_DKFRM.
\xe\sxe

