Index: trunk/psModules/src/camera/pmFPA.h =================================================================== --- trunk/psModules/src/camera/pmFPA.h (revision 8047) +++ trunk/psModules/src/camera/pmFPA.h (revision 9584) @@ -1,101 +1,93 @@ -/** @file pmFPA.h -* -* @brief This file defines the basic types the focal plane hierarchy. -* -* @ingroup AstroImage -* -* @author GLG, MHPCC -* -* @version $Revision: 1.6 $ $Name: not supported by cvs2svn $ -* @date $Date: 2006-08-02 02:17:11 $ -* -* Copyright 2004-2005 Maui High Performance Computing Center, University of Hawaii -*/ +/// @file pmFPA.h +/// +/// @brief Defines the focal plane hierarchy, along with functions for interacting with it +/// +/// @ingroup Camera +/// +/// @author George Gusciora, MHPCC +/// @author Paul Price, IfA +/// @author Eugene Magnier, IfA +/// +/// @version $Revision: 1.7 $ $Name: not supported by cvs2svn $ +/// @date $Date: 2006-10-17 00:33:56 $ +/// +/// Copyright 2005-2006 Institute for Astronomy, University of Hawaii +/// #ifndef PM_FPA_H #define PM_FPA_H + #if HAVE_CONFIG_H #include #endif -#include "pslib.h" +#include #include "pmHDU.h" -# define FPA_ASTROM 1 +#define FPA_ASTROM 1 ///< Include astrometry information in the structures? -/// @addtogroup AstroImage -/// @{ - -/** Focal plane data structure - * - * A focal plane consists of one or more chips (according to the number of - * pieces of contiguous silicon). It contains metadata containers for the - * concepts and analysis, a link to the parent, and pointers to the FITS header, - * if that corresponds to this level (the FPA may be the PHU, but will not ever - * contain pixels). For astrometry, it contains a transformation from the focal - * plane to the tangent plane and the fixed pattern residuals. It is expected - * that the transformation will consist of two 4D polynomials (i.e. a function - * of two coordinates in position, the magnitude of the object, and the color of - * the object) in order to correct for optical distortions and the effects of - * the atmosphere; hence we think that it is prudent to include a reverse - * transformation which will be derived from numerically inverting the forward - * transformation. - * - */ +/// Focal plane array (the entirety of the camera) +/// +/// The FPA is the top-level camera structure, and consists of one or more chips. It also contains the +/// concepts metadata appropriate to this level, a summary of analysis tasks that have been performed, the +/// camera configuration information, any HDU that corresponds to this level for the file of interest, and +/// astrometric transformations. The astrometric transformations encode how to transform from the tangent +/// plane to the sky, and back. typedef struct { - # if FPA_ASTROM + #if FPA_ASTROM // Astrometric transformations - psPlaneDistort* fromTangentPlane; ///< Transformation from tangent plane to focal plane -psPlaneDistort* toTangentPlane; ///< Transformation from focal plane to tangent plane -psProjection *projection; ///< Projection from tangent plane to sky -# endif -// Information -psMetadata *concepts; ///< Cache for PS concepts -unsigned int conceptsRead; ///< Which concepts have been read -psMetadata *analysis; ///< FPA-level analysis metadata -const psMetadata *camera; ///< Camera configuration -psArray *chips; ///< The chips -pmHDU *hdu; ///< FITS data + psPlaneDistort *fromTangentPlane; ///< Transformation from tangent plane to focal plane, or NULL + psPlaneDistort *toTangentPlane; ///< Transformation from focal plane to tangent plane, or NULL + psProjection *projection; ///< Projection from tangent plane to sky, or NULL + #endif + // Information + psMetadata *concepts; ///< FPA-level concepts + unsigned int conceptsRead; ///< Which concepts have been read; see pmConceptsSource + psMetadata *analysis; ///< FPA-level analysis metadata + const psMetadata *camera; ///< Camera configuration + psArray *chips; ///< The component chips + pmHDU *hdu; ///< FITS header data unit of interest, or NULL } pmFPA; -/** Chip data structure - * - * A chip consists of one or more cells (according to the number of amplifiers - * on the device). The chip contains metadata containers for the concepts and - * analysis, a link to the parent, and pointers to the pointers to the various - * FITS data, if that corresponds to this level. For astrometry, in addition to - * the rough positioning information, it contains a coordinate transform from - * the chip to the focal plane. It is expected that this transform will consist - * of two second-order 2D polynomials; hence we think that it is prudent to - * include a reverse transformation which will be derived from numerically - * inverting the forward transformation. A boolean indicates whether the chip is - * of interest, allowing it to be excluded from analysis. - * - */ +/// A chip (contiguous detector element) +/// +/// The chip is the mid-level camera structure, being part of an FPA, and consisting of one or more cells +/// (e.g., a CCD). It also contains the concepts metadata appropriate to this level, a summary of analysis +/// tasks that have been performed, status flags, any HDU that corresponds to this level for the file of +/// interest, and astrometric transformations. The astrometric transformations are of two types: rough +/// (indicating an offset from the origin of the FPA) and precise (transformations between the chip and FPA +/// coordinates). typedef struct { -# if FPA_ASTROM + #if FPA_ASTROM // Offset specifying position on focal plane int col0; ///< Offset from the left of FPA. -int row0; ///< Offset from the bottom of FPA. -// Astrometric transformations -psPlaneTransform* toFPA; ///< Transformation from chip to FPA coordinates -psPlaneTransform* fromFPA; ///< Transformation from FPA to chip coordinates -# endif -// Information -psMetadata *concepts; ///< Cache for PS concepts -unsigned int conceptsRead; ///< Which concepts have been read -psMetadata *analysis; ///< Chip-level analysis metadata -psArray *cells; ///< The cells (referred to by name) -pmFPA *parent; ///< Parent FPA -bool process; ///< Do we bother about reading and working with this chip? -bool file_exists; ///< Does the file for this chip exist (read case only)? -bool data_exists; ///< Does the data for this chip exist (read case only)? -pmHDU *hdu; ///< FITS data -struct pmCell *mosaic; ///< A mosaic cell + int row0; ///< Offset from the bottom of FPA. + // Astrometric transformations + psPlaneTransform *toFPA; ///< Transformation from chip to FPA coordinates, or NULL + psPlaneTransform *fromFPA; ///< Transformation from FPA to chip coordinates, or NULL + #endif + // Information + psMetadata *concepts; ///< Chip-level concepts + unsigned int conceptsRead; ///< Which concepts have been read; see pmConceptsSource + psMetadata *analysis; ///< Chip-level analysis metadata + psArray *cells; ///< The component cells + pmFPA *parent; ///< Parent FPA + bool process; ///< Do we bother about reading and working with this chip? + bool file_exists; ///< Does the file for this chip exist (read case only)? + bool data_exists; ///< Does the data for this chip exist (read case only)? + pmHDU *hdu; ///< FITS header data unit of interest, } pmChip; + +/// A cell (smallest logical unit) +/// +/// A cell is the lowest-level camera structure, being part of a chip (e.g., an amplifier). It may consist of +/// one or more readouts, which are individual reads of the cell. It also contains the concepts metadata +/// appropriate to this level, the cell configuration information (for convenience) from the camera +/// configuration, a summary of analysis tasks that have been performed, status flags, and any HDU that +/// corresponds to this level for the file of interest /** Cell data structure @@ -110,189 +102,95 @@ typedef struct { -psMetadata *concepts; ///< Cache for PS concepts -unsigned int conceptsRead; ///< Which concepts have been read -psMetadata *config; ///< Cell configuration info -psMetadata *analysis; ///< Cell-level analysis metadata -psArray *readouts; ///< The readouts (referred to by number) -pmChip *parent; ///< Parent chip -bool process; ///< Do we bother about reading and working with this cell? -bool file_exists; ///< Does the file for this cell exist (read case only)? -bool data_exists; ///< Does the data for this cell exist (read case only)? -pmHDU *hdu; ///< FITS data + psMetadata *concepts; ///< Cell-level concepts + unsigned int conceptsRead; ///< Which concepts have been read; see pmConceptsSource + psMetadata *config; ///< Cell configuration information (from CELLS in the camera config) + psMetadata *analysis; ///< Cell-level analysis metadata + psArray *readouts; ///< The component readouts + pmChip *parent; ///< Parent chip + bool process; ///< Do we bother about reading and working with this cell? + bool file_exists; ///< Does the file for this cell exist (read case only)? + bool data_exists; ///< Does the data for this cell exist (read case only)? + pmHDU *hdu; ///< FITS header data unit of interest } pmCell; -/** Readout data structure. - * - * A readout is the result of a single read of a cell (or a portion thereof). - * It contains the offset from the lower-left corner of the chip, in the case - * that the CCD was windowed, as well as the binning factors and parity (if the - * binning value is negative, then the parity is reversed). It also contains the - * pixel data, metadata containers for the concepts and analysis, and a link to - * the parent. - * - */ +/// A readout (individual read of a cell) +/// +/// A readout corresponds to an individual read of a cell (e.g., a single image as part of a video sequence, +/// or one of multiple coadds). It contains the actual pixels used in analysis (along with mask and weight +/// maps). When reading from a FITS file, the images are subimages (from CELL.TRIMSEC) of the pixels read +/// from the appropriate HDU (at the FPA, chip or cell level). The readout also contains a list of bias +/// sections (prescans or overscans, or otherwise), a summary of analysis tasks that have been performed, +/// status flags, and the offsets used for reading a FITS file incrementally. typedef struct { -int col0; ///< Column offset; non-zero if reading in columns bit by bit -int row0; ///< Row offset; non-zero if reading in rows bit by bit -psImage *image; ///< Imaging area of readout -psImage *mask; ///< Mask of input image -psImage *weight; ///< Weight of input image -psList *bias; ///< Overscan images -psMetadata *analysis; ///< Readout-level analysis metadata -pmCell *parent; ///< Parent cell -bool process; ///< Do we bother about reading and working with this readout? -bool file_exists; ///< Does the file for this readout exist (read case only)? -bool data_exists; ///< Does the data for this readout exist (read case only)? + int col0; ///< Column offset; non-zero if reading in columns incrementally + int row0; ///< Row offset; non-zero if reading in rows incrementally + psImage *image; ///< Imaging area of readout (corresponds to CELL.TRIMSEC region) + psImage *mask; ///< Mask of input image (corresponds to CELL.TRIMSEC region) + psImage *weight; ///< Weight of input image (corresponds to CELL.TRIMSEC region) + psList *bias; ///< List of bias (prescan/overscan) images + psMetadata *analysis; ///< Readout-level analysis metadata + pmCell *parent; ///< Parent cell + bool process; ///< Do we bother about reading and working with this readout? + bool file_exists; ///< Does the file for this readout exist (read case only)? + bool data_exists; ///< Does the data for this readout exist (read case only)? } pmReadout; -void pmCellFreeReadouts(pmCell *cell); -void pmChipFreeCells(pmChip *chip); +/// Free all readouts within a cell +void pmCellFreeReadouts(pmCell *cell ///< Cell for which to free readouts + ); -void pmReadoutFreeData (pmReadout *readout); -void pmCellFreeData(pmCell *cell); -void pmChipFreeData(pmChip *chip); -void pmFPAFreeData(pmFPA *fpa); +/// Free all cells within a chip +void pmChipFreeCells(pmChip *chip ///< Chip for which to free cells + ); -/** Allocates a pmReadout - * - * The constructor shall make an empty pmReadout. If the parent cell is not - * NULL, the parent link is made and the readout shall be placed in the - * parents array of readouts. The metadata containers shall be allocated. All - * other pointers in the structure shall be initialized to NULL. - * - * @return pmReadout* newly allocated pmReadout with all internal pointers set to NULL - */ -pmReadout *pmReadoutAlloc( - pmCell *cell ///< Parent cell -); +/// Free all data within a readout +void pmReadoutFreeData(pmReadout *readout ///< Readout for which to free data + ); -/** Allocates a pmCell - * - * The constructor shall make an empty pmCell. If the parent chip is not NULL, - * the parent link is made and the cell shall be placed in the parents array of - * cells. The readouts array shall be allocated with a zero size, and the - * metadata containers constructed. All other pointers in the structure shall be - * initialized to NULL. - * - * @return pmCell* newly allocated pmCell - */ -pmCell *pmCellAlloc( - pmChip *chip, ///< Parent chip - const char *name ///< Name of cell -); +/// Free all data within a cell (all readouts as well as metadata) +void pmCellFreeData(pmCell *cell ///< Cell for which to free data + ); -/** Allocates a pmChip - * - * The constructor shall make an empty pmChip. If the parent fpa is not NULL, - * the parent link is made and the chip shall be placed in the parent's array - * of chips. The cells array shall be allocated with a zero size, and the - * metadata containers constructed. All other pointers in the structure shall be - * initialized to NULL. - * - * @return pmChip* newly allocated pmChip - */ -pmChip *pmChipAlloc( - pmFPA *fpa, ///< FPA to which the chip belongs - const char *name ///< Name of chip -); +/// Free all data within a chip (all cells as well as metadata) +void pmChipFreeData(pmChip *chip ///< Chip for which to free data + ); -/** Allocates a pmFPA - * - * The constructor shall make an empty pmFPA. The chips array shall be - * allocated with a zero size, the camera and db pointers set to the values - * provided, and the concepts metadata constructed. All other pointers in the - * structure shall be initialized to NULL. - * - */ -pmFPA *pmFPAAlloc( - const psMetadata *camera ///< Camera configuration -); +/// Free all data within an FPA (all chips as well as metadata) +void pmFPAFreeData(pmFPA *fpa ///< FPA for which to free data + ); + +/// Allocate a readout associated with a cell +pmReadout *pmReadoutAlloc(pmCell *cell ///< Parent cell, or NULL + ); + +/// Allocate a cell associated with a chip +/// +/// The name is used to set CELL.NAME within the concepts. +pmCell *pmCellAlloc(pmChip *chip, ///< Parent chip, or NULL + const char *name ///< Name of cell, for CELL.NAME + ); + +/// Allocate a chip associated with an FPA +/// +/// The name is used to set CHIP.NAME within the concepts +pmChip *pmChipAlloc(pmFPA *fpa, ///< Parent FPA, or NULL + const char *name ///< Name of chip, for CHIP.NAME + ); + +/// Allocate an FPA +pmFPA *pmFPAAlloc(const psMetadata *camera ///< Camera configuration (to store in FPA) + ); -/** Verify parent links. - * - * This function checks the validity of the parent links in the FPA hierarchy. - * If a parent link is not set (or not set correctly), it is corrected, and the - * function shall return false. If all the parent pointers were correct, the - * function shall return true. - * - */ -bool pmFPACheckParents( - pmFPA *fpa -); - -/* functions to turn on/off the file_exists flags */ -bool pmFPASetFileStatus (pmFPA *fpa, bool status); -bool pmChipSetFileStatus (pmChip *chip, bool status); -bool pmCellSetFileStatus (pmCell *cell, bool status); - -/* Functions to check the file_exists flags */ -bool pmFPACheckFileStatus(const pmFPA *fpa); -bool pmChipCheckFileStatus(const pmChip *chip); -bool pmCellCheckFileStatus(const pmCell *cell); - -/* functions to turn on/off the data_exists flags */ -bool pmFPASetDataStatus (pmFPA *fpa, bool status); -bool pmChipSetDataStatus (pmChip *chip, bool status); -bool pmCellSetDataStatus (pmCell *cell, bool status); - -/** Specify the level for an operation. - */ -typedef enum { - PM_FPA_LEVEL_NONE, ///< No particular level specified - PM_FPA_LEVEL_FPA, ///< Level corresponds to an FPA - PM_FPA_LEVEL_CHIP, ///< Level corresponds to a Chip - PM_FPA_LEVEL_CELL, ///< Level corresponds to a Cell - PM_FPA_LEVEL_READOUT ///< Level corresponds to a Readout -} pmFPALevel; +/// Check parent links within an FPA +/// +/// Iterates through the FPA to verify that the "parent" links in the chip, cell and readout are set +/// correctly. If there are any incorrect links, they are fixed, and the function returns false. +bool pmFPACheckParents(pmFPA *fpa ///< FPA to check + ); -/** - * - * pmFPASelectChip shall set valid to true for the specified chip number - * (chipNum), and all other chips shall have valid set to false. In the event - * that the specified chip number does not exist within the fpa, the function - * shall return false. - * - */ -bool pmFPASelectChip( - pmFPA *fpa, - int chipNum, - bool exclusive -); - -bool pmChipSelectCell(pmChip *chip, - int cellNum, - bool exclusive - ); - -/** - * - * pmFPAExcludeChip shall set valid to false only for the specified chip - * number (chipNum). In the event that the specified chip number does not exist - * within the fpa, the function shall generate a warning, and perform no action. - * The function shall return the number of chips within the fpa that have valid - * set to true. - * - */ -int pmFPAExcludeChip( - pmFPA *fpa, - int chipNum -); - -int pmChipExcludeCell(pmChip *chip, - int cellNum - ); - -// Set the weights and masks within a cell, based on the gain and RN -bool pmCellSetWeights(pmCell *cell // Cell for which to set weights - ); - - -char *pmFPALevelToName(pmFPALevel level); -pmFPALevel pmFPALevelFromName(const char *name); - #endif // #ifndef PM_FPA_H