/* @file pmFPAHeader.h
 * @brief Functions read FITS headers for FPA components
 *
 * @author Paul Price, IfA
 * @author Eugene Magnier, IfA
 *
 * @version $Revision: 1.8 $ $Name: not supported by cvs2svn $
 * @date $Date: 2007-03-30 21:12:56 $
 * Copyright 2005-2006 Institute for Astronomy, University of Hawaii
 */

#ifndef PM_FPA_MASK_WEIGHT_H
#define PM_FPA_MASK_WEIGHT_H

/// @addtogroup Camera Camera Layout
/// @{

/// Pixel mask values
typedef enum {
    PM_MASK_CLEAR   = 0x00,   ///< The pixel is not masked
    PM_MASK_TRAP    = 0x01,   ///< The pixel is a charge trap.
    PM_MASK_BADCOL  = 0x02,   ///< The pixel is a bad column.
    PM_MASK_SAT     = 0x04,   ///< The pixel is saturated.
    PM_MASK_BAD     = 0x08,   ///< The pixel is low
    PM_MASK_FLAT    = 0x10,   ///< The pixel is non-positive in the flat-field.
    PM_MASK_MARK    = 0x20,   ///< The pixel is marked as temporarily ignored
    PM_MASK_EXT1    = 0x40,   ///< This mask value is not used
    PM_MASK_EXT2    = 0x80,   ///< This mask value is not used
} pmMaskValue;


/// Set a temporary readout mask using CELL.SATURATION and CELL.BAD
///
/// Identifies pixels that are saturated (>= CELL.SATURATION) or bad (<= CELL.BAD).  The mask that is produced
/// within the readout is temporary --- it is not added to the HDU.  This is intended for when the user is
/// iterating using pmReadoutReadNext, in which case the HDU can't be generated.
bool pmReadoutSetMask(pmReadout *readout ///< Readout for which to set mask
                     );


/// Set a temporary readout weight map using CELL.GAIN and CELL.READNOISE
///
/// Calculates weights (actually variances) for each pixel using photon statistics and the cell gain
/// (CELL.GAIN) and read noise (CELL.READNOISE).  The weight map that is produced within the readout is
/// temporary --- it is not added to the HDU.  This is intended for when the user is iterating using
/// pmReadoutReadNext, in which case the HDU can't be generated.
bool pmReadoutSetWeight(pmReadout *readout, ///< Readout for which to set weight
                        bool poisson    ///< Use poisson weights (in addition to read noise)?
                       );

/// Generate a readout mask (suitable for output) using CELL.SATURATION and CELL.BAD
///
/// Identifies pixels that are saturated (>= CELL.SATURATION) or bad (<= CELL.BAD).  The mask that is produced
/// is suitable for output (complete with HDU entry).  This is intended for most operations.
bool pmReadoutGenerateMask(pmReadout *readout ///< Readout for which to generate mask
                          );

/// Generate a weight map (suitable for output) using CELL.GAIN and CELL.READNOISE
///
/// Calculates weights (actually variances) for each pixel using photon statistics and the cell gain
/// (CELL.GAIN) and read noise (CELL.READNOISE).  The weight map that is produced within the readout is
/// suitable for output (complete with HDU entry).  This is intended for most operations.
bool pmReadoutGenerateWeight(pmReadout *readout, ///< Readout for which to generate weight
                             bool poisson    ///< Use poisson weights (in addition to read noise)?
                            );

/// Generate mask and weight map for a readout
///
/// Calls pmReadoutGenerateMask and pmReadoutGenerateWeight for the readout
bool pmReadoutGenerateMaskWeight(pmReadout *readout, ///< Readout for which to generate mask and weights
                                 bool poisson    ///< Use poisson weights (in addition to read noise)?
                                );

/// Generate mask and weight maps for all readouts within a cell
///
/// Calls pmReadoutGenerateMaskWeight for each readout within the cell.
bool pmCellGenerateMaskWeight(pmCell *cell, ///< Cell for which to generate mask and weights
                              bool poisson    ///< Use poisson weights (in addition to read noise)?
                             );
/// @}
#endif
