PRO eis_cr_checker, input

;+
; NAME:
;     EIS_CR_CHECKER
;
; PURPOSE:
;     Identifies the locations of cosmic rays in a 2D image.
;
; CATEGORY:
;     Hinode/EIS; cosmic rays.
;
; CALLING SEQUENCE:
;     EIS_CR_CHECKER, Input
;
; INPUTS:
;     Input:  A structure with the following tags.
;              .img    2D image in DN units
;              .med3   3x7 median of IMG (2D array)
;              .med1   1x7 median of IMG (2D array)
;              .npix   No. of pixels used in 3x7 median (2D array)
;              .nabove No. of good above pixels in 1x7 median (2D array)
;              .nbelow No. of good below pixels in 1x7 median (2D array)
;              .limit  Cutoff DN value between weak/strong pixels
;              .max_var_low  Cutoff for weak/strong background.
;              .sigma  1-sigma for DN of background.
;              .missing Value used for missing data.
;              .swtch_hi  2D byte array giving strong CR locations.
;              .swtch_lo  2D byte array giving weak CR locations.
;
; OUTPUTS:
;     The SWTCH_HI and SWTCH_LO tags are modified to contain the
;     locations of flagged pixels. All other tags remain unchanged. 
;
; PROGRAMMING NOTES:
;     Pixels with signals below/above LIMIT DN are considered
;     weak/strong cosmic rays. For strong CRs the four neighboring
;     pixels in the image will also get flagged (in
;     EIS_PREP_CLEAN_CRS) hence their locations are stored separately
;     in SWTCH_HI. (Weak CRs are flagged in SWTCH_LO.)
;
;     Checks are made on the 3x7 median for a pixel. If it is below
;     MAX_VAR_LOW it means the pixel does not lie within an emission
;     line profile, in which case the 1x7 median does not need to be
;     checked.
;
;     It is recommended that EIS_CR_CHECKER is run twice to flag any
;     residual CRs.
;
;     A CR must be at least MAX_VAR_LOW DN above the
;     background. Typically this is about 20 DN.
;
; RESTRICTIONS:
;     Some examples of CRs that are not removed:
;     - in high-signal areas an obvious CR that is only, say, 30% above
;       the median will not be flagged
;     - complex CRs may not have all pixels flagged; particularly for
;       SAA data.
;     - if there are so many missing pixels that the medians
;       can't be reliably formed (particularly 1x7 median).
;
; EXAMPLE:
;     This routine is intended to be called from
;     EIS_PREP_CLEAN_CRS. Please check this routine for how to use
;     EIS_CR_CHECKER.
;
; MODIFICATION HISTORY:
;     Ver.1, 13-Nov-2019, Peter Young
;-


img=input.img
med3=input.med3
med1=input.med1
npix=input.npix
nabove=input.nabove
nbelow=input.nbelow
limit=input.limit
max_var_low=input.max_var_low
s=input.sigma
missing=input.missing
swtch_hi=input.swtch_hi
swtch_lo=input.swtch_lo


;
; CHECK WEAK-1
; ------------
; - this is the only check for "weak" pixels.
; - median-3 is weak (<max_var_low), and pixel is weak (<limit)
;
k=where( (med3 LE max_var_low) AND (img LE limit) AND (npix GE 7) AND (med3 NE missing) AND ((img-med3) GT max_var_low), nk)
IF nk NE 0 THEN swtch_lo[k]=1b
    
;
; CHECK STRONG-1
; --------------
; - median-3 is weak, so no need to check median-1
;
k=where( (med3 LE max_var_low) AND (img GT limit) AND (npix GE 7) AND (med3 NE missing) AND (img/(med3>1.)) GE 1.7, nk)
IF nk NE 0 THEN swtch_hi[k]=1b
    
;
; CHECK STRONG-2
; --------------
; - medians are above max_var_low => pixel is within line profile
; - check if median-1 is much bigger than median-3 => we're in
;      steep part of line profile
; - require there to be at least one pixel above (in Y-direction) and
;      below in order to trust the median-1 value.
;
k=where( (med1 GT max_var_low) AND (med1 GT med3+2.*s) AND ((img/(med1>1.)) GE 1.7) AND (nbelow GE 1) AND (nabove GE 1) AND (med1 NE missing) AND (img GT limit), nk)
IF nk NE 0 THEN swtch_hi[k]=1b

;
; CHECK STRONG-3
; --------------
; - here median-1 is not much different from median-3, so use median-3
;   to check pixel
;
k=where( (med3 GT max_var_low) AND (med1 LE med3+2.*s) AND ((img/(med3>1.)) GE 1.7) AND (npix GE 7) AND (med3 NE missing) AND (img GT limit), nk)
IF nk NE 0 THEN swtch_hi[k]=1b

;
; CHECK STRONG-4
; --------------
; - this deals with the rare case of a strong CR that is missed by the
;   other checks.
;
k=where( ((img/(med3>1.)) GE 3.0) AND (npix GE 7) AND (med3 NE missing) AND (img GT limit) AND (npix GE 7), nk)
IF nk NE 0 THEN swtch_hi[k]=1b

    
input.swtch_lo=swtch_lo
input.swtch_hi=swtch_hi

END