IPP Software Navigation Tools IPP Links Communication Pan-STARRS Links

Ignore:
Timestamp:
Oct 20, 2006, 6:26:36 PM (20 years ago)
Author:
Paul Price
Message:

Fixing pmFPA. Adding pmHDU and pmHDUUtils, pmFPAview.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/doc/modules/CameraImages.tex

    r7783 r9712  
    5252The top level of our image container hierarchy is a complete focal
    5353plane array (\code{pmFPA}).  This structure represents the collection
    54 of chips in the camera, all of which are read out in a given
    55 exposure. 
     54of chips in the camera, all of which are read out in a given exposure.
    5655
    5756For example, take a mosaic camera consisting of eight $2k\times 4k$
    … …  
    8584those metadata containers.
    8685
    87 While the \code{psMetadata} pointers provide a mechanism to carry
    88 generic information about the image, the hierarchy of data structures
    89 also provides an explicit set of information defining the geometrical
    90 relationships between the levels of the hierarchy.  Two types of
    91 information are provided.  In the first case, basic offsets (and in
    92 the case of the readouts, binning and flips) are defined to specify
    93 the location of a given \code{pmCell} with respect to its containing
    94 \code{pmChip} in the assumption that the pixels in the entire focal
    95 plane array are laid out on a uniform grid.  This is a crude
    96 approximation, and cannot be assumed for careful astrometric analysis,
    97 but it can be used as a starting point or to place the the pixels in a
    98 test image.  For higher precision, detailed astrometric
    99 transformations between one frame and the next are also provided.
    100 
    101 \tbd{In the future, it may be worthwhile to migrate all of these
    102 additional pieces to the psMetadata since there is no pressing need to
    103 have them visible in the data structures}
    104 
    105 \subsection{Image Data Container Hierarchy}
     86\subsection{Focal Plane Hierarchy}
    10687
    10788Here we specify the contents of the focal plane hierarchy:
    108 \code{pmReadout}, \code{pmCell}, \code{pmChip} and \code{pmFPA}.  Many
    109 of the components of these are similar.  All but the \code{pmFPA}
    110 contain offsets from the level above (\code{col0,row0}), and a link to
    111 the parent. All but the \code{pmReadout} contain a private pointer to
    112 FITS data and more detailed astrometric transforms.  Each contains an
    113 \code{analysis} metadata container which is intended to store results
    114 of analyses (e.g., the r.m.s. of the overscan fit).
    115 
    116 \tbd{At what stage are the offsets ({\tt col0,row0}) set, and how are
    117 they known?}
     89\code{pmReadout}, \code{pmCell}, \code{pmChip} and \code{pmFPA}.
    11890
    11991\subsubsection{A Readout}
    12092
    121 A readout is the result of a single read of a cell (or a portion
    122 thereof).  It contains the offset from the lower-left corner of the
    123 chip, in the case that the CCD was windowed, as well as the binning
    124 factors and parity (if the binning value is negative, then the parity
    125 is reversed).  It also contains the pixel data (with corresponding
    126 mask and weight), metadata container for the analysis, and a link to
    127 the parent.
     93A readout corresponds to an individual read of a cell (e.g., a single
     94image as part of a video sequence, or one of multiple coadds).  It
     95contains the actual pixels used in analysis (along with mask and
     96weight maps).  When reading from a FITS file, the images are subimages
     97(from CELL.TRIMSEC) of the pixels read from the appropriate HDU (at
     98the FPA, chip or cell level).  The readout also contains a list of
     99bias sections (prescans or overscans, or otherwise), a summary of
     100analysis tasks that have been performed, status flags, and the offsets
     101used for reading a FITS file incrementally.
    128102
    129103\begin{verbatim}
    130104typedef struct {
    131     // Information
    132     psMetadata *analysis;              // Readout-level analysis metadata
    133     pmCell *parent;                    // Parent cell
    134     // Data
    135     psImage *image;                    // Imaging area of readout
    136     psImage *mask;                     // Mask for image
    137     psImage *weight;                   // Weight for image
    138     psList *bias;                      // List of bias section (sub-)images
     105    int col0;                           ///< Column offset; non-zero if reading in columns incrementally
     106    int row0;                           ///< Row offset; non-zero if reading in rows incrementally
     107    psImage *image;                     ///< Imaging area of readout (corresponds to CELL.TRIMSEC region)
     108    psImage *mask;                      ///< Mask of input image (corresponds to CELL.TRIMSEC region)
     109    psImage *weight;                    ///< Weight of input image (corresponds to CELL.TRIMSEC region)
     110    psList *bias;                       ///< List of bias (prescan/overscan) images
     111    psMetadata *analysis;               ///< Readout-level analysis metadata
     112    pmCell *parent;                     ///< Parent cell
     113    bool process;                       ///< Do we bother about reading and working with this readout?
     114    bool file_exists;                   ///< Does the file for this readout exist (read case only)?
     115    bool data_exists;                   ///< Does the data for this readout exist (read case only)?
    139116} pmReadout;
    140117\end{verbatim}   
    141118
    142 The constructor for \code{pmReadout} shall be:
    143 \begin{verbatim}
    144 pmReadout *pmReadoutAlloc(void);
     119The constructor for \code{pmReadout} is:
     120\begin{verbatim}
     121pmReadout *pmReadoutAlloc(pmCell *cell  ///< Parent cell, or NULL
     122                          );
    145123\end{verbatim}
    146124The constructor shall make an empty \code{pmReadout}.  The metadata
    147125container and the \code{bias} list shall be allocated.  All other
    148126pointers in the structure shall be initialized to \code{NULL}.
     127Processing is on by default; the existence flags are initially set to
     128\code{false}.
     129
     130All data within a \code{pmReadout} may be freed:
     131\begin{prototype}
     132void pmReadoutFreeData(pmReadout *readout ///< Readout for which to free data
     133                      );
     134\end{prototype}
    149135
    150136\subsubsection{A Cell}
    151137
    152 A cell consists of one or more readouts (usually only one except in
    153 the case that the cell has been used for fast guiding, or similar
    154 situations).  It has values which specifies the position of the cell
    155 on the chip for rough positioning, along with more precise coordinate
    156 transforms from the cell to the chip and, as a convenience, from the
    157 cell directly to the focal plane.  It is expected that these
    158 transforms will consist of two first-order 2D polynomials, simply
    159 specifying a translation, rotation and magnification; hence they are
    160 easily inverted, and there is no need to add reverse transformations.
    161 We also add an additional transformation, which is intended to provide
    162 a ``quick and dirty'' transform from the cell coordinates to the sky;
    163 this transformation not guaranteed to be as precise as the
    164 ``standard'' transformation of Cell $\rightarrow$ Chip $\rightarrow$
    165 Focal Plane $\rightarrow$ Tangent Plane $\rightarrow$ Sky, but will be
    166 faster.  The cell also contains metadata containers for the concepts
    167 and analysis, a link to the parent, and a container for the FITS data,
    168 if that corresponds to this level.  A boolean indicates whether the
    169 cell is of interest, allowing it to be excluded from analysis.
     138A cell is the lowest-level camera structure, being part of a chip
     139(e.g., an amplifier).  It may consist of one or more readouts, which
     140are individual reads of the cell.  It also contains the concepts
     141metadata appropriate to this level, the cell configuration information
     142(for convenience) from the camera configuration, a summary of analysis
     143tasks that have been performed, status flags, and any HDU that
     144corresponds to this level for the file of interest
     145
     146\begin{verbatim}
     147typedef struct {
     148    psMetadata *concepts;               ///< Cell-level concepts
     149    unsigned int conceptsRead;          ///< Which concepts have been read; see pmConceptsSource
     150    psMetadata *config;                 ///< Cell configuration information (from CELLS in the camera config)
     151    psMetadata *analysis;               ///< Cell-level analysis metadata
     152    psArray *readouts;                  ///< The component readouts
     153    pmChip *parent;                     ///< Parent chip
     154    bool process;                       ///< Do we bother about reading and working with this cell?
     155    bool file_exists;                   ///< Does the file for this cell exist (read case only)?
     156    bool data_exists;                   ///< Does the data for this cell exist (read case only)?
     157    pmHDU *hdu;                         ///< FITS header data unit of interest
     158} pmCell;
     159\end{verbatim}
     160
     161The constructor for \code{pmCell} shall be:
     162\begin{verbatim}
     163pmCell *pmCellAlloc(pmChip *chip,       ///< Parent chip, or NULL
     164                    const char *name    ///< Name of cell, for CELL.NAME
     165                   );
     166\end{verbatim}
     167The constructor shall make an empty \code{pmCell}.  The
     168\code{readouts} array shall be allocated with a zero size, and the
     169metadata containers constructed.  Processing is on by default; the
     170existence flags are initially set to \code{false}.  The \code{name} is
     171used to set \code{CELL.NAME} in the \code{concepts}.  All other
     172pointers in the structure are initialized to \code{NULL}.
     173
     174All readouts, or all data (readouts and metadata) within a cell may be
     175freed:
     176\begin{prototype}
     177void pmCellFreeReadouts(pmCell *cell    ///< Cell for which to free readouts
     178                       );
     179void pmCellFreeData(pmCell *cell        ///< Cell for which to free data
     180                   );
     181\end{prototype}
     182
     183\subsubsection{A Chip}
     184
     185The chip is the mid-level camera structure, being part of an FPA, and
     186consisting of one or more cells (e.g., a CCD).  It also contains the
     187concepts metadata appropriate to this level, a summary of analysis
     188tasks that have been performed, status flags, any HDU that corresponds
     189to this level for the file of interest, and astrometric
     190transformations.  The astrometric transformations provide transforms
     191between the chip and FPA coordinates and back.
     192
     193\tbd{The astrometric transformations will likely disappear into the
     194analysis metadata in the future.}
    170195
    171196\begin{verbatim}
    172197typedef struct {
    173198    // Astrometric transformations
    174     psPlaneTransform* toChip;          // Transformations from cell to chip coordinates
    175     psPlaneTransform* toFPA;           // Transformations from cell to FPA coordinates
    176     psPlaneTransform* toSky;           // Transformations from cell to sky coordinates
     199    psPlaneTransform *toFPA;            ///< Transformation from chip to FPA coordinates, or NULL
     200    psPlaneTransform *fromFPA;          ///< Transformation from FPA to chip coordinates, or NULL
    177201    // Information
    178     psMetadata *concepts;              // Cache for PS concepts
    179     psMetadata *camera;                // Camera information
    180     psMetadata *analysis;              // Cell-level analysis metadata
    181     bool process;                      // Do we want to process?
    182     bool exists;                       // Does the data exist?
    183     // Levels   
    184     psArray *readouts;                 // The readouts (referred to by number)
    185     pmChip *parent;                    // Parent chip
    186     // Sources
    187     pmFile *imageSource;               // Image file on disk
    188     pmFile *maskSource;                // Mask file on disk
    189     pmFile *weightSource;              // Weight file on disk
    190 } pmCell;
    191 \end{verbatim}
    192 
    193 The constructor for \code{pmCell} shall be:
    194 \begin{verbatim}
    195 pmCell *pmCellAlloc(psMetadata *cameraData, psString name);
    196 \end{verbatim}
    197 The constructor shall make an empty \code{pmCell}.  The
    198 \code{readouts} array shall be allocated with a zero size, and the
    199 metadata containers constructed.  The cell's \code{camera} pointer
    200 shall be set to the provided \code{cameraData}, the \code{exists}
    201 boolean shall be set to \code{false}, the \code{process} boolean shall
    202 be set to \code{true}, and the \code{name} shall be used to set
    203 \code{CELL.NAME} in the \code{concepts}.  All other pointers in the
     202    psMetadata *concepts;               ///< Chip-level concepts
     203    unsigned int conceptsRead;          ///< Which concepts have been read; see pmConceptsSource
     204    psMetadata *analysis;               ///< Chip-level analysis metadata
     205    psArray *cells;                     ///< The component cells
     206    pmFPA *parent;                      ///< Parent FPA
     207    bool process;                       ///< Do we bother about reading and working with this chip?
     208    bool file_exists;                   ///< Does the file for this chip exist (read case only)?
     209    bool data_exists;                   ///< Does the data for this chip exist (read case only)?
     210    pmHDU *hdu;                         ///< FITS header data unit of interest,
     211} pmChip;
     212\end{verbatim}
     213
     214The constructor for \code{pmChip} shall be:
     215\begin{verbatim}
     216pmChip *pmChipAlloc(pmFPA *fpa,         ///< Parent FPA, or NULL
     217                    const char *name    ///< Name of cell, for CELL.NAME
     218                   );
     219\end{verbatim}
     220The constructor shall make an empty \code{pmChip}.  The \code{cells}
     221array shall be allocated with a zero size and the metadata containers
     222constructed.  Processing is on by default; the existence flags are
     223initially set to \code{false}.  The \code{name} shall be used to set
     224\code{CHIP.NAME} in the \code{concepts}.  All other pointers in the
    204225structure shall be initialized to \code{NULL}.
     226
     227All cells, or all data (cells and metadata) within a chip may be
     228freed:
     229\begin{prototype}
     230void pmChipFreeCells(pmChip *chip       ///< Chip for which to free cells
     231                    );
     232void pmChipFreeData(pmChip *chip        ///< Chip for which to free data
     233                   );
     234\end{prototype}
     235
     236\subsubsection{A Focal Plane}
     237
     238The FPA is the top-level camera structure, and consists of one or more
     239chips.  It also contains the concepts metadata appropriate to this
     240level, a summary of analysis tasks that have been performed, the
     241camera configuration information, any HDU that corresponds to this
     242level for the file of interest, and astrometric transformations.  The
     243astrometric transformations encode how to transform from the tangent
     244plane to the sky, and back.
     245
     246It is expected that the astrometric transformation will consist of two
     2474D polynomials (i.e.\ a function of two coordinates in position, the
     248magnitude of the object, and the color of the object) in order to
     249correct for optical distortions and the effects of the atmosphere;
     250hence we think that it is prudent to include a reverse transformation
     251which will be derived from numerically inverting the forward
     252transformation.
    205253
    206254\tbd{The astrometric transformations will likely disappear into the
    207255analysis metadata in the future.}
    208256
    209 \subsubsection{A Chip}
    210 
    211 A chip consists of one or more cells (according to the number of
    212 amplifiers on the device).  The chip contains metadata containers for
    213 the concepts and analysis, a link to the parent, and pointers to the
    214 pointers to the various FITS data, if that corresponds to this level.
    215 For astrometry, in addition to the rough positioning information, it
    216 contains a coordinate transform from the chip to the focal plane.  It
    217 is expected that this transform will consist of two second-order 2D
    218 polynomials; hence we think that it is prudent to include a reverse
    219 transformation which will be derived from numerically inverting the
    220 forward transformation.  A boolean indicates whether the chip is of
    221 interest, allowing it to be excluded from analysis.
    222 
    223257\begin{verbatim}
    224258typedef struct {
    225259    // Astrometric transformations
    226     psPlaneTransform* toFPA;           // Transformation from chip to FPA coordinates
    227     psPlaneTransform* fromFPA;         // Transformation from FPA to chip coordinates
     260    psPlaneDistort *fromTangentPlane;   ///< Transformation from tangent plane to focal plane, or NULL
     261    psPlaneDistort *toTangentPlane;     ///< Transformation from focal plane to tangent plane, or NULL
     262    psProjection *projection;           ///< Projection from tangent plane to sky, or NULL
    228263    // Information
    229     psMetadata *concepts;              // Cache for PS concepts
    230     psMetadata *analysis;              // Chip-level analysis metadata
    231     bool process;                      // Do we want to process?
    232     bool exists;                       // Does the data exist?
    233     // Levels
    234     psArray *cells;                    // The cells (referred to by name)
    235     pmFPA *parent;                     // Parent FPA
    236     // Sources
    237     pmFile *imageSource;               // Image file on disk
    238     pmFile *maskSource;                // Mask file on disk
    239     pmFile *weightSource;              // Weight file on disk
    240 } pmChip;
    241 \end{verbatim}
    242 
    243 The constructor for \code{pmChip} shall be:
    244 \begin{verbatim}
    245 pmChip *pmChipAlloc(psString name);
    246 \end{verbatim}
    247 The constructor shall make an empty \code{pmChip}.  The \code{cells}
    248 array shall be allocated with a zero size, the metadata containers
    249 constructed, the \code{exists} boolean shall be set to \code{false},
    250 the \code{process} boolean shall be set to \code{true}, andhe
    251 \code{name} shall be used to set \code{CHIP.NAME} in the
    252 \code{concepts}.  All other pointers in the structure shall be
    253 initialized to \code{NULL}.
    254 
    255 \tbd{The astrometric transformations will likely disappear into the
    256 analysis metadata in the future.}
    257 
    258 \subsubsection{A Focal Plane}
    259 
    260 A focal plane consists of one or more chips (according to the number
    261 of pieces of contiguous silicon).  It contains metadata containers for
    262 the concepts and analysis, a link to the parent, and pointers to the
    263 FITS header, if that corresponds to this level (the FPA may be the
    264 PHU, but will not ever contain pixels).  For astrometry, it contains a
    265 transformation from the focal plane to the tangent plane and the fixed
    266 pattern residuals.  It is expected that the transformation will
    267 consist of two 4D polynomials (i.e.\ a function of two coordinates in
    268 position, the magnitude of the object, and the color of the object) in
    269 order to correct for optical distortions and the effects of the
    270 atmosphere; hence we think that it is prudent to include a reverse
    271 transformation which will be derived from numerically inverting the
    272 forward transformation.
    273 
    274 \begin{verbatim}
    275 typedef struct {
    276     // Astrometric transformations
    277     psPlaneDistort* fromTangentPlane;  // Transformation from tangent plane to focal plane
    278     psPlaneDistort* toTangentPlane;    // Transformation from focal plane to tangent plane
    279     psProjection *projection;          // Projection from tangent plane to sky
    280     // Information
    281     psMetadata *concepts;              // Cache for PS concepts
    282     psMetadata *analysis;              // FPA-level analysis metadata
    283     const psMetadata *camera;          // Camera configuration
    284     // Levels
    285     psArray *chips;                    // The chips
    286     // Sources
    287     pmFile *imageSource;               // Image file on disk
    288     pmFile *maskSource;                // Mask file on disk
    289     pmFile *weightSource;              // Weight file on disk
     264    psMetadata *concepts;               ///< FPA-level concepts
     265    unsigned int conceptsRead;          ///< Which concepts have been read; see pmConceptsSource
     266    psMetadata *analysis;               ///< FPA-level analysis metadata
     267    const psMetadata *camera;           ///< Camera configuration
     268    psArray *chips;                     ///< The component chips
     269    pmHDU *hdu;                         ///< FITS header data unit of interest, or NULL
    290270} pmFPA;
    291271\end{verbatim}
    … …  
    293273The constructor for \code{pmFPA} shall be:
    294274\begin{verbatim}
    295 pmFPA *pmFPAAlloc(const psMetadata *camera);
     275pmFPA *pmFPAAlloc(const psMetadata *camera ///< Camera configuration (to store in FPA)
     276                 );
    296277\end{verbatim}
    297278The constructor shall make an empty \code{pmFPA}.  The \code{chips}
    298279array shall be allocated with a zero size, the \code{camera} pointer
    299280set to the value provided, and the \code{concepts} metadata
    300 constructed. All other pointers in the structure shall be initialized
     281constructed.  All other pointers in the structure shall be initialized
    301282to \code{NULL}.
    302283
    303 \tbd{The astrometric transformations will likely disappear into the
    304 analysis metadata in the future.}
    305 
    306 \subsubsection{Disk files}
    307 
    308 Each of the levels in the hierarchy have a place to hold a
    309 \code{pmFile}, which is the representation of a FITS file and ``header
    310 data unit'':
    311 \begin{datatype}
    312 typedef struct {
    313     const char *filename;               // Name of file
    314     psFits *fits;                       // FITS file
    315     psMetadata *phu;                    // Primary extension
    316     const char *extname;                // Extension name, or NULL
    317     psMetadata *header;                 // The FITS header, or NULL if primary
    318     psArray *images;                    // The pixel data
    319     psDB *database;                     // Database handle for concepts
    320 } pmFile;
    321 \end{datatype}
    322 
     284All data (chips and metadata) within an FPA may be freed:
     285\begin{prototype}
     286void pmFPAFreeData(pmFPA *fpa           ///< FPA for which to free data
     287                  );
     288\end{prototype}
    323289
    324290\subsubsection{Links between levels}
    325 
    326 We provide functions to attach readouts, cells and chips with their
    327 parents:
    328 \begin{prototype}
    329 bool pmReadoutParent(pmReadout *readout, pmCell *cell);
    330 bool pmCellParent(pmCell *cell, pmChip *chip);
    331 bool pmChipParent(pmChip *chip, pmFPA *fpa);
    332 \end{prototype}
    333 In the case of \code{pmReadoutParent}, the function shall set the
    334 \code{parent} pointer for the \code{readout} to \code{cell}, and add
    335 the \code{readout} to the array of \code{readouts} in the \code{cell}.
    336 The other cases are similar.  \textit{Note that, in order to avoid
    337 infinite loops when freeing, the reference counter should \textbf{not}
    338 be incremented when attaching to the \code{parent} pointer, and the
    339 deallocators should \textbf{not} free the parent.}
    340 
    341 The following functions remove all levels below that specified:
    342 \begin{prototype}
    343 void pmCellFreeReadouts(pmCell *cell);
    344 void pmChipFreeCells(pmChip *chip);
    345 void pmFPAFreeChips(pmFPA *fpa);
    346 \end{prototype}
    347291
    348292The inclusion of hierarchical links pointing both down (via the
    … …  
    351295collection of upward-pointing links:
    352296\begin{prototype}
    353 bool pmFPACheckLinks(pmFPA *fpa);
     297bool pmFPACheckParents(pmFPA *fpa);
    354298\end{prototype}
    355299This function checks the validity of the \code{parent} links in the
    … …  
    358302shall return \code{false}.  If all the \code{parent} pointers were
    359303correct, the function shall return \code{true}.
     304
     305
     306\subsection{Header Data Units}
     307
     308Each of the levels in the hierarchy have a place to hold a
     309\code{pmHDU}, which is the representation of a FITS ``header data
     310unit'':
     311\begin{datatype}
     312typedef struct {
     313    psString extname;                   ///< The extension name
     314    bool blankPHU;                      ///< Is this a blank FITS Primary Header Unit, i.e., no data?
     315    psMetadata *format;                 ///< The camera format
     316    psMetadata *header;                 ///< The FITS header, or NULL if primary for FITS; or section info
     317    psArray *images;                    ///< The pixel data
     318    psArray *weights;                   ///< The pixel data
     319    psArray *masks;                     ///< The pixel data
     320} pmHDU;
     321\end{datatype}
     322
     323The \code{pmHDU} simplifies the input/output from/to FITS files, since
     324it is, for the most part, a representation of the HDU on disk.  Of
     325course, it is not an exact replica of a FITS HDU --- they have no mask
     326and weight data, but these are stored here for convenience --- it
     327keeps all the relevant data about the image in one place.
     328
     329The allocator is:
     330\begin{prototype}
     331pmHDU *pmHDUAlloc(const char *extname   ///< Extension name, or NULL for PHU
     332                 );
     333\end{prototype}
     334
     335
     336\subsubsection{HDU I/O}
     337
     338The following function moves to the appropriate extension and reads
     339the FITS header into the \code{pmHDU.header} member:
     340\begin{prototype}
     341bool pmHDUReadHeader(pmHDU *hdu,        ///< HDU for which to read header
     342                     psFits *fits       ///< FITS file from which to read
     343                    );
     344\end{prototype}
     345
     346The following function moves to the appropriate extension and reads
     347the FITS header and pixels into the \code{pmHDU}:
     348\begin{prototype}
     349bool pmHDURead(pmHDU *hdu,              ///< HDU to read
     350               psFits *fits             ///< FITS file to read from
     351              );
     352\end{prototype}
     353
     354The following function writes the HDU header and pixels to the end of
     355the FITS file:
     356\begin{prototype}
     357bool pmHDUWrite(pmHDU *hdu,             ///< HDU to write
     358                psFits *fits            ///< FITS file to write to
     359               );
     360\end{prototype}
     361
     362
     363\subsubsection{HDU Utilities}
     364
     365The following functions return the appropriate HDU, given a member of
     366the focal plane hierarchy.  If no HDU is present at the particular
     367level, it searches the next highest level.  If no HDU can be found,
     368the function returns \code{NULL}.
     369
     370\begin{prototype}
     371pmHDU *pmHDUFromFPA(const pmFPA *fpa    ///< FPA for which to find HDU
     372                   );
     373pmHDU *pmHDUFromChip(const pmChip *chip ///< Chip for which to find HDU
     374                    );
     375pmHDU *pmHDUFromCell(const pmCell *cell ///< Cell for which to find HDU
     376                    );
     377pmHDU *pmHDUFromReadout(const pmReadout *readout ///< Readout for which to find HDU
     378                       );
     379\end{prototype}
     380
     381The following functions take multiple components of a focal plane
     382hierarchy, and return the HDU at the lowest/highest level of the
     383components passed to the function.  If components at all levels are
     384supplied, the lowest HDU in the hierarchy is the one with the actual
     385pixels, while the highest HDU is the PHU.
     386\begin{prototype}
     387pmHDU *pmHDUGetLowest(const pmFPA *fpa, ///< The FPA
     388                      const pmChip *chip, ///< The chip, or NULL
     389                      const pmCell *cell ///< The cell, or NULL
     390                     );
     391pmHDU *pmHDUGetHighest(const pmFPA *fpa, ///< The FPA
     392                       const pmChip *chip, ///< The chip, or NULL
     393                       const pmCell *cell ///< The cell, or NULL
     394                      );
     395\end{prototype}
     396
     397The following function prints details about an HDU: the extension
     398name, headers (if requested), and image sizes.  This function is
     399intended for testing or development use.
     400
     401\begin{prototype}
     402void pmHDUPrint(FILE *fd,               ///< File descriptor to which to print
     403                const pmHDU *hdu,       ///< HDU to print
     404                int level,              ///< Level at which to print
     405                bool header             ///< Print header?
     406               );
     407\end{prototype}
     408
     409
     410\subsection{FPA View}
     411
     412The following structure allows the identification of a single
     413component of the focal plane hierarchy (or multiple, if we consider
     414selecting all those components below the selected component).
     415Components are identified on the basis of their chip, cell, readout
     416index.  An index of -1 means all components at that level.
     417Additionally, since readouts may be read piecemeal, there are
     418additional indices for these.
     419\begin{datatype}
     420typedef struct {
     421    int chip;                           // Number of the chip, or -1 for all
     422    int cell;                           // Number of the cell, or -1 for all
     423    int readout;                        // Number of the readout, or -1 for all
     424    int nRows;                          // Maximum number of rows per readout segment read, or 0 for all
     425    int iRows;                          // Starting point for this read
     426} pmFPAview;
     427\end{datatype}
     428
     429The allocator is:
     430\begin{prototype}
     431pmFPAview *pmFPAviewAlloc(int nRows     ///< Maximum number of rows per readout segment read, or 0 for all
     432    );
     433\end{prototype}
     434
     435\subsubsection{Utilities}
     436
     437A view may have all components reset (select the entire FPA):
     438\begin{prototype}
     439bool pmFPAviewReset(pmFPAview *view     ///< View to reset
     440    );
     441\end{prototype}
     442
     443The view level is the highest index that isn't set to -1.
     444\begin{prototype}
     445pmFPALevel pmFPAviewLevel(const pmFPAview *view ///< View to examine
     446    );
     447\end{prototype}
     448
     449\subsubsection{Lookups}
     450
     451The following functions return the appropriate currently selected
     452hierarchy component.  The functions return \code{NULL} if the selection
     453is not specific or invalid for the appropriate level.
     454
     455\begin{prototype}
     456pmChip *pmFPAviewThisChip(const pmFPAview *view, ///< Current view
     457                          const pmFPA *fpa ///< FPA containing chip
     458    );
     459pmCell *pmFPAviewThisCell(const pmFPAview *view, ///< Current view
     460                          const pmFPA *fpa ///< FPA containing cell
     461    );
     462pmReadout *pmFPAviewThisReadout(const pmFPAview *view, ///< Current view
     463                                const pmFPA *fpa ///< FPA containing readout
     464    );
     465\end{prototype}
     466
     467\subsubsection{Incrementors}
     468
     469The following functions return the next hierarchy component, according
     470to the current selection in the \code{view}.  The functions return
     471\code{NULL} if there is no next.
     472
     473\begin{prototype}
     474pmChip *pmFPAviewNextChip(pmFPAview *view, ///< Current view
     475                          const pmFPA *fpa, ///< FPA containing chips
     476                          int nStep     ///< Number of chips to increment
     477    );
     478pmCell *pmFPAviewNextCell(pmFPAview *view, ///< Current view
     479                          const pmFPA *fpa, ///< FPA containing cells
     480                          int nStep     ///< Number of cells to increment
     481    );
     482pmReadout *pmFPAviewNextReadout(pmFPAview *view, ///< Current view
     483                                const pmFPA *fpa, ///< FPA containing readouts
     484                                int nStep ///< Number of readouts to increment
     485    );
     486\end{prototype}
     487
     488\subsubsection{HDUs}
     489
     490The following function returns the HDU corresponding to the current view,
     491using the \code{pmHDUFrom...} functions, combined with the \code{view}.
     492\begin{prototype}
     493pmHDU *pmFPAviewThisHDU(const pmFPAview *view, ///< Current view
     494                        const pmFPA *fpa ///< FPA for view
     495    );
     496\end{prototype}
     497
     498This function returns the blank Primary HDU corresponding to the
     499current view, if one exists.  The operation is similar to
     500pmFPAviewThisHDU, except it returns \code{NULL} if no HDU is found, or
     501the HDU is not a blank Primary HDU.
     502\begin{prototype}
     503pmHDU *pmFPAviewThisPHU(const pmFPAview *view, ///< Current view
     504                        const pmFPA *fpa ///< FPA for view
     505    );
     506\end{prototype}
     507
     508
     509
     510%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     511%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     512%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     513
     514
     515
     516
    360517
    361518
Note: See TracChangeset for help on using the changeset viewer.