/* @file pmMaskBadPixels.h
 * @brief Mask bad pixels
 *
 * @author Ross Harman, MHPCC
 * @author Eugene Magnier, IfA
 *
 * @version $Revision: 1.15 $ $Name: not supported by cvs2svn $
 * @date $Date: 2007-12-24 21:10:28 $
 * Copyright 2004 Institute for Astronomy, University of Hawaii
 */

#ifndef PM_MASK_BAD_PIXELS_H
#define PM_MASK_BAD_PIXELS_H

/// @addtogroup detrend Detrend Creation and Application
/// @{

typedef enum {
  PM_MASK_ID_NONE,
  PM_MASK_ID_VALUE,
  PM_MASK_ID_FRACTION,
  PM_MASK_ID_SIGMA,
  PM_MASK_ID_POISSON,
} pmMaskIdentifyMode;

pmMaskIdentifyMode pmMaskIdentifyModeFromString (const char *string);

/// Applies the bad pixel mask to the input
///
/// Pixels marked as bad within the mask are marked as bad within the input image's mask.  If maskVal is
/// non-zero, all pixels in the mask have any of the same bits sets as maskVal shall have the corresponding
/// bits raised.  If maskVal is zero, any zero pixels in the mask are OR-ed with PM_MASK_BAD.  Position
/// offsets (such as due to trimming) between the input and mask are applied so that the same pixels are
/// referred to.  The science readout must already have a supplied mask element (use eg. pmReadoutSetMask).
/// The supplied mask image must be of MASK type
bool pmMaskBadPixels(pmReadout *input,  ///< Input science image
                     const pmReadout *mask, ///< Mask image to apply
                     psMaskType maskVal ///< Mask value to apply
                    );

/// Find pixels outlying from the background, flagging suspect pixels
///
/// Pixels more than "rej" standard deviations from the background level (in flat-fielded,
/// background-subtracted images) have the corresponding pixel in the "suspect pixels" image
/// incremented.  After accumulating over a suitable sample of images, bad pixels should have a
/// high value in the suspect pixels image, allowing them to be identified.  The suspect pixels
/// image is of type S32.  The relevant median and standard deviation must be supplied in the
/// readout->analysis metadata as READOUT.MEDIAN, READOUT.STDEVe
psImage *pmMaskFlagSuspectPixels(psImage *out, ///< Suspected bad pixels image, or NULL
                                 const pmReadout *readout, ///< Readout to inspect
                                 float rej, ///< Rejection threshold (standard deviations)
                                 psMaskType maskVal ///< Mask value for statistics
                                );

/// Identify bad pixels from the suspect pixels image
///
/// Bad pixels are identified from the suspect pixels image (accumulated over a large number of images).
/// Pixels marked as suspect in more than "thresh" standard deviations from the mean are identified as bad
/// pixels (output image).  If "thresh" is negative, a Poisson is assumed.
psImage *pmMaskIdentifyBadPixels(const psImage *suspects, ///< Accumulated suspect pixels image
                                 psMaskType maskVal, ///< Value to set for bad pixels
				 int nTotal,
                                 float thresh, ///< Threshold for bad pixel (standard deviations)
				 pmMaskIdentifyMode mode
                                );
/// @}
#endif
