/* @file pmMaskBadPixels.h
 * @brief Mask bad pixels
 *
 * @author Ross Harman, MHPCC
 * @author Eugene Magnier, IfA
 *
 * @version $Revision: 1.12 $ $Name: not supported by cvs2svn $
 * @date $Date: 2007-01-24 02:54:15 $
 * 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
/// @{

#include <pslib.h>
#include "pmFPA.h"

/// 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.
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
                                 float frac, ///< Fraction of pixels to consider
                                 psRandom *rng ///< Random number generator
                                );

/// 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
                                 float thresh, ///< Threshold for bad pixel (standard deviations)
                                 psMaskType maskVal ///< Value to set for bad pixels
                                );
/// @}
#endif
