IPP Software Navigation Tools IPP Links Communication Pan-STARRS Links

Ignore:
Timestamp:
Oct 16, 2006, 2:33:57 PM (20 years ago)
Author:
Paul Price
Message:

Creating pmFPALevel.[ch] to hold pmFPALevel stuff. Creating pmFPAFlags.[ch] to hold status flag setting and checking functions. Both of these were pulled out of pmFPA.[ch]. Documenting pmFPA.h, pmFPALevel.h, pmFPAFlags.h. Adding additional includes of the new header files to files that needed them.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/psModules/src/camera/pmFPA.h

    r8047 r9584  
    1 /** @file  pmFPA.h
    2 *
    3 *  @brief This file defines the basic types the focal plane hierarchy.
    4 *
    5 *  @ingroup AstroImage
    6 *
    7 *  @author GLG, MHPCC
    8 *
    9 *  @version $Revision: 1.6 $ $Name: not supported by cvs2svn $
    10 *  @date $Date: 2006-08-02 02:17:11 $
    11 *
    12 *  Copyright 2004-2005 Maui High Performance Computing Center, University of Hawaii
    13 */
     1/// @file pmFPA.h
     2///
     3/// @brief Defines the focal plane hierarchy, along with functions for interacting with it
     4///
     5/// @ingroup Camera
     6///
     7/// @author George Gusciora, MHPCC
     8/// @author Paul Price, IfA
     9/// @author Eugene Magnier, IfA
     10///
     11/// @version $Revision: 1.7 $ $Name: not supported by cvs2svn $
     12/// @date $Date: 2006-10-17 00:33:56 $
     13///
     14/// Copyright 2005-2006 Institute for Astronomy, University of Hawaii
     15///
    1416
    1517#ifndef PM_FPA_H
    1618#define PM_FPA_H
     19
    1720#if HAVE_CONFIG_H
    1821#include <config.h>
    1922#endif
    2023
    21 #include "pslib.h"
     24#include <pslib.h>
    2225#include "pmHDU.h"
    2326
    24 # define FPA_ASTROM 1
     27#define FPA_ASTROM 1                    ///< Include astrometry information in the structures?
    2528
    26 /// @addtogroup AstroImage
    27 /// @{
    28 
    29 /** Focal plane data structure
    30  *
    31  *  A focal plane consists of one or more chips (according to the number of
    32  *  pieces of contiguous silicon). It contains metadata containers for the
    33  *  concepts and analysis, a link to the parent, and pointers to the FITS header,
    34  *  if that corresponds to this level (the FPA may be the PHU, but will not ever
    35  *  contain pixels). For astrometry, it contains a transformation from the focal
    36  *  plane to the tangent plane and the fixed pattern residuals. It is expected
    37  *  that the transformation will consist of two 4D polynomials (i.e. a function
    38  *  of two coordinates in position, the magnitude of the object, and the color of
    39  *  the object) in order to correct for optical distortions and the effects of
    40  *  the atmosphere; hence we think that it is prudent to include a reverse
    41  *  transformation which will be derived from numerically inverting the forward
    42  *  transformation.
    43  *
    44  */
     29/// Focal plane array (the entirety of the camera)
     30///
     31/// The FPA is the top-level camera structure, and consists of one or more chips.  It also contains the
     32/// concepts metadata appropriate to this level, a summary of analysis tasks that have been performed, the
     33/// camera configuration information, any HDU that corresponds to this level for the file of interest, and
     34/// astrometric transformations.  The astrometric transformations encode how to transform from the tangent
     35/// plane to the sky, and back.
    4536typedef struct
    4637{
    47     # if FPA_ASTROM
     38    #if FPA_ASTROM
    4839    // Astrometric transformations
    49     psPlaneDistort* fromTangentPlane;   ///< Transformation from tangent plane to focal plane
    50 psPlaneDistort* toTangentPlane;     ///< Transformation from focal plane to tangent plane
    51 psProjection *projection;           ///< Projection from tangent plane to sky
    52 # endif
    53 // Information
    54 psMetadata *concepts;               ///< Cache for PS concepts
    55 unsigned int conceptsRead;          ///< Which concepts have been read
    56 psMetadata *analysis;               ///< FPA-level analysis metadata
    57 const psMetadata *camera;           ///< Camera configuration
    58 psArray *chips;                     ///< The chips
    59 pmHDU *hdu;                         ///< FITS data
     40    psPlaneDistort *fromTangentPlane;   ///< Transformation from tangent plane to focal plane, or NULL
     41    psPlaneDistort *toTangentPlane;     ///< Transformation from focal plane to tangent plane, or NULL
     42    psProjection *projection;           ///< Projection from tangent plane to sky, or NULL
     43    #endif
     44    // Information
     45    psMetadata *concepts;               ///< FPA-level concepts
     46    unsigned int conceptsRead;          ///< Which concepts have been read; see pmConceptsSource
     47    psMetadata *analysis;               ///< FPA-level analysis metadata
     48    const psMetadata *camera;           ///< Camera configuration
     49    psArray *chips;                     ///< The component chips
     50    pmHDU *hdu;                         ///< FITS header data unit of interest, or NULL
    6051}
    6152pmFPA;
    6253
    63 /** Chip data structure
    64  *
    65  *  A chip consists of one or more cells (according to the number of amplifiers
    66  *  on the device). The chip contains metadata containers for the concepts and
    67  *  analysis, a link to the parent, and pointers to the pointers to the various
    68  *  FITS data, if that corresponds to this level. For astrometry, in addition to
    69  *  the rough positioning information, it contains a coordinate transform from
    70  *  the chip to the focal plane. It is expected that this transform will consist
    71  *  of two second-order 2D polynomials; hence we think that it is prudent to
    72  *  include a reverse transformation which will be derived from numerically
    73  *  inverting the forward transformation. A boolean indicates whether the chip is
    74  *  of interest, allowing it to be excluded from analysis.
    75  *
    76  */
     54/// A chip (contiguous detector element)
     55///
     56/// The chip is the mid-level camera structure, being part of an FPA, and consisting of one or more cells
     57/// (e.g., a CCD).  It also contains the concepts metadata appropriate to this level, a summary of analysis
     58/// tasks that have been performed, status flags, any HDU that corresponds to this level for the file of
     59/// interest, and astrometric transformations.  The astrometric transformations are of two types: rough
     60/// (indicating an offset from the origin of the FPA) and precise (transformations between the chip and FPA
     61/// coordinates).
    7762typedef struct
    7863{
    79 # if FPA_ASTROM
     64    #if FPA_ASTROM
    8065    // Offset specifying position on focal plane
    8166    int col0;                           ///< Offset from the left of FPA.
    82 int row0;                           ///< Offset from the bottom of FPA.
    83 // Astrometric transformations
    84 psPlaneTransform* toFPA;            ///< Transformation from chip to FPA coordinates
    85 psPlaneTransform* fromFPA;          ///< Transformation from FPA to chip coordinates
    86 # endif
    87 // Information
    88 psMetadata *concepts;               ///< Cache for PS concepts
    89 unsigned int conceptsRead;          ///< Which concepts have been read
    90 psMetadata *analysis;               ///< Chip-level analysis metadata
    91 psArray *cells;                     ///< The cells (referred to by name)
    92 pmFPA *parent;                      ///< Parent FPA
    93 bool process;                       ///< Do we bother about reading and working with this chip?
    94 bool file_exists;                   ///< Does the file for this chip exist (read case only)?
    95 bool data_exists;                   ///< Does the data for this chip exist (read case only)?
    96 pmHDU *hdu;                         ///< FITS data
    97 struct pmCell *mosaic;              ///< A mosaic cell
     67    int row0;                           ///< Offset from the bottom of FPA.
     68    // Astrometric transformations
     69    psPlaneTransform *toFPA;            ///< Transformation from chip to FPA coordinates, or NULL
     70    psPlaneTransform *fromFPA;          ///< Transformation from FPA to chip coordinates, or NULL
     71    #endif
     72    // Information
     73    psMetadata *concepts;               ///< Chip-level concepts
     74    unsigned int conceptsRead;          ///< Which concepts have been read; see pmConceptsSource
     75    psMetadata *analysis;               ///< Chip-level analysis metadata
     76    psArray *cells;                     ///< The component cells
     77    pmFPA *parent;                      ///< Parent FPA
     78    bool process;                       ///< Do we bother about reading and working with this chip?
     79    bool file_exists;                   ///< Does the file for this chip exist (read case only)?
     80    bool data_exists;                   ///< Does the data for this chip exist (read case only)?
     81    pmHDU *hdu;                         ///< FITS header data unit of interest,
    9882}
    9983pmChip;
     84
     85/// A cell (smallest logical unit)
     86///
     87/// A cell is the lowest-level camera structure, being part of a chip (e.g., an amplifier).  It may consist of
     88/// one or more readouts, which are individual reads of the cell.  It also contains the concepts metadata
     89/// appropriate to this level, the cell configuration information (for convenience) from the camera
     90/// configuration, a summary of analysis tasks that have been performed, status flags, and any HDU that
     91/// corresponds to this level for the file of interest
    10092
    10193/** Cell data structure
    … …  
    110102typedef struct
    111103{
    112 psMetadata *concepts;               ///< Cache for PS concepts
    113 unsigned int conceptsRead;          ///< Which concepts have been read
    114 psMetadata *config;                 ///< Cell configuration info
    115 psMetadata *analysis;               ///< Cell-level analysis metadata
    116 psArray *readouts;                  ///< The readouts (referred to by number)
    117 pmChip *parent;                     ///< Parent chip
    118 bool process;                       ///< Do we bother about reading and working with this cell?
    119 bool file_exists;                   ///< Does the file for this cell exist (read case only)?
    120 bool data_exists;                   ///< Does the data for this cell exist (read case only)?
    121 pmHDU *hdu;                         ///< FITS data
     104    psMetadata *concepts;               ///< Cell-level concepts
     105    unsigned int conceptsRead;          ///< Which concepts have been read; see pmConceptsSource
     106    psMetadata *config;                 ///< Cell configuration information (from CELLS in the camera config)
     107    psMetadata *analysis;               ///< Cell-level analysis metadata
     108    psArray *readouts;                  ///< The component readouts
     109    pmChip *parent;                     ///< Parent chip
     110    bool process;                       ///< Do we bother about reading and working with this cell?
     111    bool file_exists;                   ///< Does the file for this cell exist (read case only)?
     112    bool data_exists;                   ///< Does the data for this cell exist (read case only)?
     113    pmHDU *hdu;                         ///< FITS header data unit of interest
    122114}
    123115pmCell;
    124116
    125 /** Readout data structure.
    126  *
    127  *  A readout is the result of a single read of a cell (or a portion thereof).
    128  *  It contains the offset from the lower-left corner of the chip, in the case
    129  *  that the CCD was windowed, as well as the binning factors and parity (if the
    130  *  binning value is negative, then the parity is reversed). It also contains the
    131  *  pixel data, metadata containers for the concepts and analysis, and a link to
    132  *  the parent.
    133  *
    134  */
     117/// A readout (individual read of a cell)
     118///
     119/// A readout corresponds to an individual read of a cell (e.g., a single image as part of a video sequence,
     120/// or one of multiple coadds).  It contains the actual pixels used in analysis (along with mask and weight
     121/// maps).  When reading from a FITS file, the images are subimages (from CELL.TRIMSEC) of the pixels read
     122/// from the appropriate HDU (at the FPA, chip or cell level).  The readout also contains a list of bias
     123/// sections (prescans or overscans, or otherwise), a summary of analysis tasks that have been performed,
     124/// status flags, and the offsets used for reading a FITS file incrementally.
    135125typedef struct
    136126{
    137 int col0;                           ///< Column offset; non-zero if reading in columns bit by bit
    138 int row0;                           ///< Row offset; non-zero if reading in rows bit by bit
    139 psImage *image;                     ///< Imaging area of readout
    140 psImage *mask;                      ///< Mask of input image
    141 psImage *weight;                    ///< Weight of input image
    142 psList *bias;                       ///< Overscan images
    143 psMetadata *analysis;               ///< Readout-level analysis metadata
    144 pmCell *parent;                     ///< Parent cell
    145 bool process;                       ///< Do we bother about reading and working with this readout?
    146 bool file_exists;                   ///< Does the file for this readout exist (read case only)?
    147 bool data_exists;                   ///< Does the data for this readout exist (read case only)?
     127    int col0;                           ///< Column offset; non-zero if reading in columns incrementally
     128    int row0;                           ///< Row offset; non-zero if reading in rows incrementally
     129    psImage *image;                     ///< Imaging area of readout (corresponds to CELL.TRIMSEC region)
     130    psImage *mask;                      ///< Mask of input image (corresponds to CELL.TRIMSEC region)
     131    psImage *weight;                    ///< Weight of input image (corresponds to CELL.TRIMSEC region)
     132    psList *bias;                       ///< List of bias (prescan/overscan) images
     133    psMetadata *analysis;               ///< Readout-level analysis metadata
     134    pmCell *parent;                     ///< Parent cell
     135    bool process;                       ///< Do we bother about reading and working with this readout?
     136    bool file_exists;                   ///< Does the file for this readout exist (read case only)?
     137    bool data_exists;                   ///< Does the data for this readout exist (read case only)?
    148138}
    149139pmReadout;
    150140
    151 void pmCellFreeReadouts(pmCell *cell);
    152 void pmChipFreeCells(pmChip *chip);
     141/// Free all readouts within a cell
     142void pmCellFreeReadouts(pmCell *cell    ///< Cell for which to free readouts
     143                       );
    153144
    154 void pmReadoutFreeData (pmReadout *readout);
    155 void pmCellFreeData(pmCell *cell);
    156 void pmChipFreeData(pmChip *chip);
    157 void pmFPAFreeData(pmFPA *fpa);
     145/// Free all cells within a chip
     146void pmChipFreeCells(pmChip *chip       ///< Chip for which to free cells
     147                    );
    158148
    159 /** Allocates a pmReadout
    160  *
    161  *  The constructor shall make an empty pmReadout. If the parent cell is not
    162  *  NULL, the parent link is made and the readout shall be placed in the
    163  *  parents array of readouts. The metadata containers shall be allocated. All
    164  *  other pointers in the structure shall be initialized to NULL.
    165  *
    166  *  @return pmReadout*    newly allocated pmReadout with all internal pointers set to NULL
    167  */
    168 pmReadout *pmReadoutAlloc(
    169     pmCell *cell                        ///< Parent cell
    170 );
     149/// Free all data within a readout
     150void pmReadoutFreeData(pmReadout *readout ///< Readout for which to free data
     151                      );
    171152
    172 /** Allocates a pmCell
    173  *
    174  *  The constructor shall make an empty pmCell. If the parent chip is not NULL,
    175  *  the parent link is made and the cell shall be placed in the parents array of
    176  *  cells. The readouts array shall be allocated with a zero size, and the
    177  *  metadata containers constructed. All other pointers in the structure shall be
    178  *  initialized to NULL.
    179  *
    180  *  @return pmCell*    newly allocated pmCell
    181  */
    182 pmCell *pmCellAlloc(
    183     pmChip *chip,       ///< Parent chip
    184     const char *name    ///< Name of cell
    185 );
     153/// Free all data within a cell (all readouts as well as metadata)
     154void pmCellFreeData(pmCell *cell        ///< Cell for which to free data
     155                   );
    186156
    187 /** Allocates a pmChip
    188  *
    189  *  The constructor shall make an empty pmChip. If the parent fpa is not NULL,
    190  *  the parent link is made and the chip shall be placed in the parent's array
    191  *  of chips. The cells array shall be allocated with a zero size, and the
    192  *  metadata containers constructed. All other pointers in the structure shall be
    193  *  initialized to NULL.
    194  *
    195  *  @return pmChip*    newly allocated pmChip
    196  */
    197 pmChip *pmChipAlloc(
    198     pmFPA *fpa,                         ///< FPA to which the chip belongs
    199     const char *name                    ///< Name of chip
    200 );
     157/// Free all data within a chip (all cells as well as metadata)
     158void pmChipFreeData(pmChip *chip        ///< Chip for which to free data
     159                   );
    201160
    202 /** Allocates a pmFPA
    203  *
    204  *  The constructor shall make an empty pmFPA. The chips array shall be
    205  *  allocated with a zero size, the camera and db pointers set to the values
    206  *  provided, and the concepts metadata constructed. All other pointers in the
    207  *  structure shall be initialized to NULL.
    208  *
    209  */
    210 pmFPA *pmFPAAlloc(
    211     const psMetadata *camera            ///< Camera configuration
    212 );
     161/// Free all data within an FPA (all chips as well as metadata)
     162void pmFPAFreeData(pmFPA *fpa           ///< FPA for which to free data
     163                  );
     164
     165/// Allocate a readout associated with a cell
     166pmReadout *pmReadoutAlloc(pmCell *cell  ///< Parent cell, or NULL
     167                         );
     168
     169/// Allocate a cell associated with a chip
     170///
     171/// The name is used to set CELL.NAME within the concepts.
     172pmCell *pmCellAlloc(pmChip *chip,       ///< Parent chip, or NULL
     173                    const char *name    ///< Name of cell, for CELL.NAME
     174                   );
     175
     176/// Allocate a chip associated with an FPA
     177///
     178/// The name is used to set CHIP.NAME within the concepts
     179pmChip *pmChipAlloc(pmFPA *fpa,         ///< Parent FPA, or NULL
     180                    const char *name    ///< Name of chip, for CHIP.NAME
     181                   );
     182
     183/// Allocate an FPA
     184pmFPA *pmFPAAlloc(const psMetadata *camera ///< Camera configuration (to store in FPA)
     185                 );
    213186
    214187
    215 /** Verify parent links.
    216  *
    217  *  This function checks the validity of the parent links in the FPA hierarchy.
    218  *  If a parent link is not set (or not set correctly), it is corrected, and the
    219  *  function shall return false. If all the parent pointers were correct, the
    220  *  function shall return true.
    221  *
    222  */
    223 bool pmFPACheckParents(
    224     pmFPA *fpa
    225 );
    226 
    227 /* functions to turn on/off the file_exists flags */
    228 bool pmFPASetFileStatus (pmFPA *fpa, bool status);
    229 bool pmChipSetFileStatus (pmChip *chip, bool status);
    230 bool pmCellSetFileStatus (pmCell *cell, bool status);
    231 
    232 /* Functions to check the file_exists flags */
    233 bool pmFPACheckFileStatus(const pmFPA *fpa);
    234 bool pmChipCheckFileStatus(const pmChip *chip);
    235 bool pmCellCheckFileStatus(const pmCell *cell);
    236 
    237 /* functions to turn on/off the data_exists flags */
    238 bool pmFPASetDataStatus (pmFPA *fpa, bool status);
    239 bool pmChipSetDataStatus (pmChip *chip, bool status);
    240 bool pmCellSetDataStatus (pmCell *cell, bool status);
    241 
    242 /** Specify the level for an operation.
    243  */
    244 typedef enum {
    245     PM_FPA_LEVEL_NONE,                  ///< No particular level specified
    246     PM_FPA_LEVEL_FPA,                   ///< Level corresponds to an FPA
    247     PM_FPA_LEVEL_CHIP,                  ///< Level corresponds to a Chip
    248     PM_FPA_LEVEL_CELL,                  ///< Level corresponds to a Cell
    249     PM_FPA_LEVEL_READOUT                ///< Level corresponds to a Readout
    250 } pmFPALevel;
     188/// Check parent links within an FPA
     189///
     190/// Iterates through the FPA to verify that the "parent" links in the chip, cell and readout are set
     191/// correctly.  If there are any incorrect links, they are fixed, and the function returns false.
     192bool pmFPACheckParents(pmFPA *fpa       ///< FPA to check
     193                      );
    251194
    252195
    253 /**
    254  *
    255  * pmFPASelectChip shall set valid to true for the specified chip number
    256  * (chipNum), and all other chips shall have valid set to false. In the event
    257  * that the specified chip number does not exist within the fpa, the function
    258  * shall return false.
    259  *
    260  */
    261 bool pmFPASelectChip(
    262     pmFPA *fpa,
    263     int chipNum,
    264     bool exclusive
    265 );
    266 
    267 bool pmChipSelectCell(pmChip *chip,
    268                       int cellNum,
    269                       bool exclusive
    270                      );
    271 
    272 /**
    273  *
    274  * pmFPAExcludeChip shall set valid to false only for the specified chip
    275  * number (chipNum). In the event that the specified chip number does not exist
    276  * within the fpa, the function shall generate a warning, and perform no action.
    277  * The function shall return the number of chips within the fpa that have valid
    278  * set to true.
    279  *
    280  */
    281 int pmFPAExcludeChip(
    282     pmFPA *fpa,
    283     int chipNum
    284 );
    285 
    286 int pmChipExcludeCell(pmChip *chip,
    287                       int cellNum
    288                      );
    289 
    290 // Set the weights and masks within a cell, based on the gain and RN
    291 bool pmCellSetWeights(pmCell *cell // Cell for which to set weights
    292                      );
    293 
    294 
    295 char *pmFPALevelToName(pmFPALevel level);
    296 pmFPALevel pmFPALevelFromName(const char *name);
    297 
    298196#endif // #ifndef PM_FPA_H
Note: See TracChangeset for help on using the changeset viewer.