/* @file pmFPARead.h
 * @brief Functions to read FPA components from a FITS file
 *
 * @author Paul Price, IfA
 *
 * @version $Revision: 1.6 $ $Name: not supported by cvs2svn $
 * @date $Date: 2007-01-24 02:54:14 $
 * Copyright 2005-2006 Institute for Astronomy, University of Hawaii
 */

#ifndef PM_FPA_READ_H
#define PM_FPA_READ_H

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

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

/// Read a readout incrementally
///
/// Multiple calls to this function moves through a readout within a cell incrementally.  It is required to
/// pass the readout previously acquired (or a newly-allocated one) in order to preserve state information
/// (where the read is at).  Only a maximum of numRows rows are read at a time.  Returns true if pixels are
/// read, and false otherwise.  To facilitate looping, no error is generated for reading a plane that doesn't
/// exist.  Note that this function doesn't put pixels in the HDU.  It is therefore NOT COMPATIBLE with
/// pmCellWrite, pmChipWrite, and pmFPAWrite (or any function that uses or creates an HDU for that matter).
/// Use pmReadoutWriteNext to write the data that's read by this function.  This function is intended for
/// reading in many readouts into memory at once (e.g., for stacking) where the input is not written out.
bool pmReadoutReadNext(pmReadout *readout, // Readout into which to read
                       psFits *fits,    // FITS file from which to read
                       int z,           // Readout number/plane; zero-offset indexing
                       int numRows      // The number of rows to read
                      );

/// Read an entire cell
///
/// Reads the appropriate HDU, ingests concepts from the header, and portions pixels into readouts.  Pixels
/// are converted to F32.
bool pmCellRead(pmCell *cell,           // Cell to read into
                psFits *fits,           // FITS file from which to read
                psDB *db                // Database handle, for "concepts" ingest
               );

/// Read a chip
///
/// Iterates over component cells, reading each with pmCellRead.
bool pmChipRead(pmChip *chip,           // Chip to read into
                psFits *fits,           // FITS file from which to read
                psDB *db                // Database handle, for "concepts" ingest
               );

/// Read an FPA
///
/// Iterates over component chips, reading each with pmChipRead.
bool pmFPARead(pmFPA *fpa,              // FPA to read into
               psFits *fits,            // FITS file from which to read
               psDB *db                 // Database handle, for "concepts" ingest
              );

/// Read an entire cell into the mask
///
/// Same as pmCellRead, but reads into the mask element of the readouts.
bool pmCellReadMask(pmCell *cell,           // Cell to read into
                    psFits *fits,           // FITS file from which to read
                    psDB *db                // Database handle, for "concepts" ingest
                   );

/// Read an entire chip into the mask
///
/// Same as pmChipRead, but reads into the mask element of the readouts.
bool pmChipReadMask(pmChip *chip,           // Chip to read into
                    psFits *fits,           // FITS file from which to read
                    psDB *db                // Database handle, for "concepts" ingest
                   );

/// Read an entire FPA into the mask
///
/// Same as pmFPARead, but reads into the mask element of the readouts.
bool pmFPAReadMask(pmFPA *fpa,              // FPA to read into
                   psFits *fits,            // FITS file from which to read
                   psDB *db                 // Database handle, for "concepts" ingest
                  );

/// Read an entire cell into the weight
///
/// Same as pmCellRead, but reads into the weight element of the readouts.
bool pmCellReadWeight(pmCell *cell,           // Cell to read into
                      psFits *fits,           // FITS file from which to read
                      psDB *db                // Database handle, for "concepts" ingest
                     );

/// Read an entire chip into the weight
///
/// Same as pmChipRead, but reads into the weight element of the readouts.
bool pmChipReadWeight(pmChip *chip,           // Chip to read into
                      psFits *fits,           // FITS file from which to read
                      psDB *db                // Database handle, for "concepts" ingest
                     );

/// Read an entire FPA into the weight
///
/// Same as pmFPARead, but reads into the weight element of the readouts.
bool pmFPAReadWeight(pmFPA *fpa,              // FPA to read into
                     psFits *fits,            // FITS file from which to read
                     psDB *db                 // Database handle, for "concepts" ingest
                    );

/// Read a FITS table into the cell
///
/// Given a name, which is combined with the chip and cell to identify the extension name ("NAME_CHIP_CELL"),
/// read the FITS table into the cell analysis metadata (with key being the provided name).  The header is
/// also read and included in the cell analysis metadata under "name.HEADER".
int pmCellReadTable(pmCell *cell,       ///< Cell for which to read table
                    psFits *fits,       ///< FITS file from which the table
                    const char *name    ///< Specifies the extension name, and target in the analysis metadata
                   );

/// Read a FITS table into the component cells
///
/// Iterates over component cells, calling pmCellReadTable.
int pmChipReadTable(pmChip *chip,       ///< Cell for which to read table
                    psFits *fits,       ///< FITS file from which the table
                    const char *name    ///< Specifies the extension name, and target in the analysis metadata
                   );

/// Read a FITS table into the component cells
///
/// Iterates over component chips, calling pmChipReadTable.
int pmFPAReadTable(pmFPA *fpa,          ///< Cell for which to read table
                   psFits *fits,        ///< FITS file from which the table
                   const char *name     ///< Specifies the extension name, and target in the analysis metadata
                  );
/// @}
#endif
