IPP Software Navigation Tools IPP Links Communication Pan-STARRS Links

Changeset 4563


Ignore:
Timestamp:
Jul 15, 2005, 11:42:13 AM (21 years ago)
Author:
Paul Price
Message:

Fixes following Gene's comments

Location:
trunk/doc/modules
Files:
2 edited

Legend:

Unmodified
Added
Removed

  • trunk/doc/modules/CameraImages.tex

    r4555 r4563  
    157157faster.  The cell also contains metadata containers for the concepts
    158158and analysis, a link to the parent, and pointers to the various FITS
    159 data, if that corresponds to this level.
     159data, if that corresponds to this level.  A boolean indicates whether
     160the cell is of interest, allowing it to be excluded from analysis.
    160161
    161162\begin{verbatim}
    … …  
    173174    psArray *readouts;                 // The readouts (referred to by number)
    174175    pmChip *parent;                    // Parent chip
     176    bool valid;                        // Do we bother about reading and working with this cell?
    175177    // FITS data
    176178    const char *extname;               // Extension name, if it corresponds to this level
    … …  
    196198amplifiers on the device).  The chip contains metadata containers for
    197199the concepts and analysis, a link to the parent, and pointers to the
    198 various FITS data, if that corresponds to this level.  For astrometry,
    199 in addition to the rough positioning information, it contains a
    200 coordinate transform from the chip to the focal plane.  It is expected
    201 that this transform will consist of two second-order 2D polynomials;
    202 hence we think that it is prudent to include a reverse transformation
    203 which will be derived from numerically inverting the forward
    204 transformation.
     200pointers to the various FITS data, if that corresponds to this level.
     201For astrometry, in addition to the rough positioning information, it
     202contains a coordinate transform from the chip to the focal plane.  It
     203is expected that this transform will consist of two second-order 2D
     204polynomials; hence we think that it is prudent to include a reverse
     205transformation which will be derived from numerically inverting the
     206forward transformation.  A boolean indicates whether the chip is of
     207interest, allowing it to be excluded from analysis.
    205208
    206209\begin{verbatim}
    … …  
    217220    psArray *cells;                    // The cells (referred to by name)
    218221    pmFPA *parent;                     // Parent FPA
     222    bool valid;                        // Do we bother about reading and working with this chip?
    219223    // FITS data
    220224    const char *extname;               // Extension name, if it corresponds to this level
    … …  
    240244of pieces of contiguous silicon).  It contains metadata containers for
    241245the concepts and analysis, a link to the parent, and pointers to the
    242 various FITS data, if that corresponds to this level.  For astrometry,
    243 it contains a transformation from the focal plane to the tangent plane
    244 and the fixed pattern residuals.  It is expected that the
    245 transformation will consist of two 4D polynomials (i.e.\ a function of
    246 two coordinates in position, the magnitude of the object, and the
    247 color of the object) in order to correct for optical distortions and
    248 the effects of the atmosphere; hence we think that it is prudent to
    249 include a reverse transformation which will be derived from
    250 numerically inverting the forward transformation.
     246FITS header, if that corresponds to this level (the FPA may be the
     247PHU, but will not ever contain pixels).  For astrometry, it contains a
     248transformation from the focal plane to the tangent plane and the fixed
     249pattern residuals.  It is expected that the transformation will
     250consist of two 4D polynomials (i.e.\ a function of two coordinates in
     251position, the magnitude of the object, and the color of the object) in
     252order to correct for optical distortions and the effects of the
     253atmosphere; hence we think that it is prudent to include a reverse
     254transformation which will be derived from numerically inverting the
     255forward transformation.
    251256
    252257\begin{verbatim}
    … …  
    263268    psArray *chips;                    // The chips
    264269    // FITS data
    265     const char *extname;               // Extension name, if it corresponds to this level
    266     psArray *pixels;                   // The pixel data, if it corresponds to this level
    267270    psMetadata *header;                // The FITS header, if it corresponds to this level
    268271} pmFPA;
    269272\end{verbatim}
     273
     274\tbd{Carrying the DB handle around in the pmFPA may not be what we
     275really want to do in the end (we might want to stuff it into a
     276separate structure with other sources of information), but for now this
     277serves as an approximation and a useful convenience.}
    270278
    271279The constructor for \code{pmFPA} shall be:
    … …  
    367375extant \code{fpa}.
    368376
    369 \tbd{Functions to remove things from an fpa so that only certain
    370 pieces of the FITS file are read in, and not the whole thing?}
     377\tbd{Functions to set the valid booleans within an fpa so that only
     378certain pieces of the FITS file are read in, and not the whole thing?}
    371379
    372380We specify an additional two functions to write out a focal plane

  • trunk/doc/modules/ModulesSDRS.tex

    r4555 r4563  
    1 %%% $Id: ModulesSDRS.tex,v 1.46 2005-07-15 00:54:03 price Exp $
     1%%% $Id: ModulesSDRS.tex,v 1.47 2005-07-15 21:42:13 price Exp $
    22\documentclass[panstarrs]{panstarrs}
    33
    … …  
    120120command line if provided, or from the the camera configuration (more
    121121detail below).
    122 
    123 \begin{prototype}
    124 bool pmConfigRead(psMetadata **site, psMetadata **camera, psMetadata **recipe,
    125                   int *argc, char **argv, const char *recipeName);
    126 psMetadata *pmConfigCameraFromHeader(const psMetadata *site, const psMetadata *header);
    127 psMetadata *pmConfigRecipeFromCamera(const psMetadata *camera, const char *recipeName);
    128 \end{prototype}
    129 
    130 \code{pmConfigRead} shall load the \code{site} configuration
    131 (according to the above rule for determining the source).  The
    132 \code{camera} configuration shall also be loaded if it is specified on
    133 the command line (\code{argc, argv}); otherwise it shall be set to
    134 \code{NULL}.  The \code{recipe} shall also be loaded from the command
    135 line (if specified) or, if the camera configuration has been loaded,
    136 from the camera configuration and recipe specification therein (see
    137 below).  In dealing with the command line parameters, the functions
    138 shall use the appropriate functions in psLib to retrieve and remove
    139 the relevant options from the argument list; this simplifies
    140 assignment of the mandatory arguments, since all the optional command
    141 line arguments are removed leaving only the mandatory arguments.
    142 
    143 \code{pmConfigCameraFromHeader} shall load the \code{camera}
    144 configuration based on the contents of the FITS \code{header}, using
    145 the list of known cameras contained in the \code{site} configuration.
    146 If more than one camera matches the FITS header, a warning shall be
    147 generated and the first matching camera returned.
    148 
    149 \code{pmConfigRecipeFromCamera} shall load the \code{recipe}
    150 configuration based on the \code{recipeName} and the list of known
    151 recipes contained in the \code{camera} configuration (details below).
    152 
    153 We also specify an additional function:
    154 \begin{prototype}
    155 bool pmConfigValidateCamera(psMetadata *camera, psMetadata *header);
    156 \end{prototype}
    157 
    158 This function, used by \code{pmConfigCameraFromHeader}, shall return
    159 \code{true} if the FITS \code{header} matches the rule contained in
    160 the \code{camera} configuration (see \S\ref{sec:camerarule});
    161 otherwise it shall return \code{false}.
    162 
    163 \subsubsection{Example usage}
    164 
    165 The following is provided as an example of how the above functions
    166 are envisioned in use.
    167 
    168 \begin{verbatim}
    169 int main(int argc, char *argv[])
    170 {
    171     // Parse other command-line arguments here
    172     psMetadata *site = NULL;            // Site configuration
    173     psMetadata *camera = NULL;          // Camera configuration
    174     psMetadata *recipe = NULL;          // Recipe configuration
    175     if (! pmConfigRead(&site, &camera, &recipe, &argc, argv, "moduleName")) {
    176         psLogMsg("moduleName", PS_LOG_ERROR, "Can't find site configuration!\n");
    177         exit(EXIT_FAILURE);
    178     }
    179     // Parse other command-line arguments here
    180 
    181     // The command-line argument list now contains only mandatory arguments
    182     // Assume the first of these is an input image
    183     char *imageName = argv[1];          // Name of FITS file
    184     psFits *imageFH = psFitsOpen(imageName, "r"); // File handle for FITS file
    185     if (! imageFH) {
    186         psLogMsg("moduleName", PS_LOG_ERROR, "Can't open input image %s\n", imageName);
    187         exit(EXIT_FAILURE);
    188     }
    189     psMetadata *header = psFitsReadHeader(NULL, imageFH); // FITS header
    190 
    191     if (!camera && !(camera = pmConfigCameraFromHeader(site, header))) {
    192         psLogMsg("moduleName", PS_LOG_ERROR, "Can't find camera configuration!\n");
    193         exit(EXIT_FAILURE);
    194     }
    195 
    196     if (! recipe && !(recipe = pmConfigRecipeFromCamera(camera, "moduleName"))) {
    197         psLogMsg("moduleName", PS_LOG_ERROR, "Can't find recipe configuration!\n");
    198         exit(EXIT_FAILURE);
    199     }
    200 
    201     // Now go on and do stuff
    202     ....
    203 }
    204 \end{verbatim}
    205122
    206123\subsection{Configuration Files}
    … …  
    225142  the data.
    226143\end{itemize}
     144
     145\tbd{No doubt there is a need for better security than storing the
     146database password directly in the file, but we push this problem onto
     147the stack for now.}
     148
     149\tbd{We will add other data sources in the future, e.g., file paths,
     150configuration for Nebulous and DVO, etc.}.
     151
    227152
    228153An example site configuration file:
    … …  
    341266CELLS   METADATA
    342267        left    METADATA        # Left amplifier
     268                CELL.BIASSEC.SOURCE     STR     HEADER
    343269                CELL.BIASSEC            STR     BIASSEC
     270                CELL.TRIMSEC.SOURCE     STR     HEADER
    344271                CELL.TRIMSEC            STR     DATASEC
    345272                CELL.PARITY             S32     1
    … …  
    347274        right   METADATA        # Right amplifier
    348275                # This cell is read out in the opposite direction
     276                CELL.BIASSEC.SOURCE     STR     HEADER
    349277                CELL.BIASSEC            STR     BIASSEC
    350                 CELL.TRIMSEC            STR     DATASEC
     278                CELL.TRIMSEC.SOURCE     STR     VALUE
     279                CELL.TRIMSEC            STR     [1025:2048,1:2048]
    351280                CELL.PARITY             S32     -1
    352281        END
    … …  
    358287associated with a chip, and has a cell type.
    359288
    360 The \code{_SOURCE} keywords will be explained in \S\ref{sec:concepts}.
     289The \code{.SOURCE} keywords in the \code{CELLS}, explained in more
     290detail in \S\ref{sec:concepts}, are necessary in order to distinguish
     291a pointer to a header from an actual value.
    361292
    362293\paragraph{Deriving concept values}
    … …  
    412343DEFAULTS        METADATA
    413344        CELL.BAD                S32     0
    414         CELL.YPARITY_DEPEND     STR     CHIP.NAME
     345        CELL.YPARITY.DEPEND     STR     CHIP.NAME
    415346        CELL.YPARITY    METADATA
    416347                ccd00   S32     -1
    … …  
    421352END
    422353
    423 # How to translation PS concepts into database lookups
     354# How to translate PS concepts into database lookups
    424355DATABASE        METADATA
    425356        TYPE            dbEntry         TABLE           COLUMN          GIVENDBCOL      GIVENPS
    … …  
    429360\end{verbatim}
    430361
    431 The \code{_DEPEND} entry in the \code{DEFAULTS} will be explained in
     362The \code{.DEPEND} entry in the \code{DEFAULTS} will be explained in
    432363\S\ref{sec:concepts}.
    433364
    … …  
    463394configuration filename.
    464395
     396An example:
     397\begin{verbatim}
     398# Recipes for LRIS
     399RECIPES METADATA
     400        PHASE1          STR     lris_phase1.config
     401        PHASE2          STR     lris_phase2.config
     402        PHASE4          STR     lris_phase4.config
     403END
     404\end{verbatim}
     405
    465406\subsubsection{Recipe Configuration}
    466407
    … …  
    481422level, while others are logically defined at the cell level.
    482423
    483 Below is a list of concepts that the IPP should require, with the
     424Below is a list of concepts that the IPP requires, with the
    484425expected type and a short description.
    485426
    … …  
    517458\item The \code{DEFAULTS} value.
    518459\end{itemize}
    519 When a concept is retrieved, it shall be stored in the cache to
    520 optimise future retrieval.  We have specified a cache and FITS header
    521 storage in the various focal plane structures for the purposes of
    522 concept retrieval.
     460When a concept is retrieved, it shall be stored in a cache (a
     461\code{psMetadata} within the FPA/chip/cell structures) to optimise
     462future retrieval.  We have specified a cache and FITS header storage
     463in the various focal plane structures for the purposes of concept
     464retrieval.
    523465
    524466Because of the variety of methods for specifying these concepts
    … …  
    528470
    529471In the \code{DEFAULTS} table in the camera configuration, we allow the
    530 specification of the concept with an additional suffix,
    531 \code{_DEPEND}.  The value (of type \code{STR}) of the
    532 \code{CONCEPT_DEPEND} is the name of a concept on which the first
    533 concept depends.  For example, it might depend on the chip name.  Then
    534 the first concept becomes of type \code{METADATA}, with the component
    535 keywords being the value of the second concept (on which the first
    536 depends).  To avoid infinite recursion, no further dependency is
    537 permitted.  An example of the dependency:
     472specification of the concept with an additional suffix, \code{DEPEND}.
     473The value (of type \code{STR}) of the \code{CONCEPT.DEPEND} is the
     474name of a concept on which the first concept depends.  For example, it
     475might depend on the chip name.  Then the first concept becomes of type
     476\code{METADATA}, with the component keywords being the value of the
     477second concept (on which the first depends).  To avoid infinite
     478recursion, no further dependency is permitted.  An example of the
     479dependency:
    538480
    539481\begin{verbatim}
    540482# Default PS concepts that may be specified by value
    541483DEFAULTS        METADATA
    542         CELL.GAIN_DEPEND     STR     CHIP.NAME
     484        CELL.GAIN.DEPEND     STR     CHIP.NAME
    543485        CELL.GAIN    METADATA
    544486                ccd00   F32     1.2
    … …  
    551493In the FITS \code{TRANSLATION} table in the camera configuration, for
    552494certain concepts we allow the specification of the concept with an
    553 additional suffix, \code{_FORMAT} which specifies the format of the
     495additional suffix, \code{FORMAT} which specifies the format of the
    554496FITS header.  The value is dependent upon the particular concept.
    555497
    … …  
    559501ways in FITS files, so care must be taken to specify what the format
    560502is in the file under consideration.  Permitted values of
    561 \code{CELL.TIME_FORMAT} are:
     503\code{CELL.TIME.FORMAT} are:
    562504
    563505\begin{itemize}
    … …  
    591533The binning is usually specified in FITS headers either as separate
    592534headers for the x and the y, or in the same FITS header separated by a
    593 space or a comma.  Permitted values of \code{CELL.BINNING_FORMAT} are:
     535space or a comma.  Permitted values of \code{CELL.BINNING.FORMAT} are:
    594536
    595537\begin{itemize}
    596 \item \code{SEPARATE}: The \code{CELL.BINNING} contains the headers
    597   for the x and the y binning separated by whitespace or a comma.
    598 \item \code{TOGETHER}: The value pointed to by \code{CELL.BINNING}
    599   contains the x and y binning separated by whitespace and/or a comma.
     538\item \code{SEPARATE}: The \code{CELL.BINNING} contains the header
     539  keywords for the x and the y binning separated by whitespace or a
     540  comma.
     541\item \code{TOGETHER}: \code{CELL.BINNING} contains the keyword for
     542  which the x and y binning are separated by whitespace and/or a
     543  comma.
    600544\end{itemize}
    601545
    … …  
    604548The RA and Declination of the boresight might be specified in a few
    605549ways.  We need to specify both how the value is interpreted and the
    606 units.  \code{FPA.RA_FORMAT} and \code{FPA.DEC_FORMAT} should be one
     550units.  \code{FPA.RA.FORMAT} and \code{FPA.DEC.FORMAT} should be one
    607551of the following:
    608552
    … …  
    629573contain \code{CELL.GAIN} and \code{CELL.READNOISE} values as well
    630574instead of going to the trouble of specifying these in the
    631 \code{DEFAULTS} with a long \code{_DEPENDS} listing.
    632 
    633 However, we need to specify for these where the value comes from.  It
    634 should be sufficient to declare the following rules:
     575\code{DEFAULTS} with a long \code{.DEPENDS} listing.
     576
     577However, in some cases, we need to specify for these where the value
     578comes from.  We declare the following rule:
    635579
    636580\begin{itemize}
    637581\item If the type is other than \code{STR}, then the concept has that
    638582  value for the cell.
    639 \item If the type is \code{STR} and contains square brackets
    640   \code{[]}, then it shall be interpreted as a value for one of the
    641   image section concepts (\code{CELL.BIASSEC} and
    642   \code{CELL.TRIMSEC}).
    643 \item Otherwise, it shall be interpreted as a FITS header keyword
    644   which will provide the value.
     583\item If the type is \code{STR}, then the value might potentially be
     584  confused between being a header keyword or an actual value.  For
     585  this reason, we introduce an additional concept suffix,
     586  \code{.SOURCE} (of type \code{STR}) which may be either
     587  \code{HEADER} or \code{VALUE}.
    645588\end{itemize}
    646589
    647 These rules mean that we don't have to bother adding an additional
    648 suffix like \code{_SOURCE}.
     590
     591\subsection{Configuration APIs}
     592
     593\begin{prototype}
     594bool pmConfigRead(psMetadata **site, psMetadata **camera, psMetadata **recipe,
     595                  int *argc, char **argv, const char *recipeName);
     596psMetadata *pmConfigCameraFromHeader(const psMetadata *site, const psMetadata *header);
     597psMetadata *pmConfigRecipeFromCamera(const psMetadata *camera, const char *recipeName);
     598\end{prototype}
     599
     600\code{pmConfigRead} shall load the \code{site} configuration
     601(according to the above rule for determining the source).  The
     602\code{camera} configuration shall also be loaded if it is specified on
     603the command line (\code{argc, argv}); otherwise it shall be set to
     604\code{NULL}.  The \code{recipe} shall also be loaded from the command
     605line (if specified) or, if the camera configuration has been loaded,
     606from the camera configuration and recipe specification therein (see
     607below).  In dealing with the command line parameters, the functions
     608shall use the appropriate functions in psLib to retrieve and remove
     609the relevant options from the argument list; this simplifies
     610assignment of the mandatory arguments, since all the optional command
     611line arguments are removed leaving only the mandatory arguments.
     612
     613\code{pmConfigCameraFromHeader} shall load the \code{camera}
     614configuration based on the contents of the FITS \code{header}, using
     615the list of known cameras contained in the \code{site} configuration.
     616If more than one camera matches the FITS header, a warning shall be
     617generated and the first matching camera returned.
     618
     619\code{pmConfigRecipeFromCamera} shall load the \code{recipe}
     620configuration based on the \code{recipeName} and the list of known
     621recipes contained in the \code{camera} configuration (details below).
     622
     623We also specify an additional function:
     624\begin{prototype}
     625bool pmConfigValidateCamera(psMetadata *camera, psMetadata *header);
     626\end{prototype}
     627
     628This function, used by \code{pmConfigCameraFromHeader}, shall return
     629\code{true} if the FITS \code{header} matches the rule contained in
     630the \code{camera} configuration (see \S\ref{sec:camerarule});
     631otherwise it shall return \code{false}.
     632
     633\subsubsection{Example usage}
     634
     635The following is provided as an example of how the above functions
     636are envisioned in use.
     637
     638\begin{verbatim}
     639int main(int argc, char *argv[])
     640{
     641    // Parse other command-line arguments here
     642    psMetadata *site = NULL;            // Site configuration
     643    psMetadata *camera = NULL;          // Camera configuration
     644    psMetadata *recipe = NULL;          // Recipe configuration
     645    if (! pmConfigRead(&site, &camera, &recipe, &argc, argv, "moduleName")) {
     646        psLogMsg("moduleName", PS_LOG_ERROR, "Can't find site configuration!\n");
     647        exit(EXIT_FAILURE);
     648    }
     649    // Parse other command-line arguments here
     650
     651    // The command-line argument list now contains only mandatory arguments
     652    // Assume the first of these is an input image
     653    char *imageName = argv[1];          // Name of FITS file
     654    psFits *imageFH = psFitsOpen(imageName, "r"); // File handle for FITS file
     655    if (! imageFH) {
     656        psLogMsg("moduleName", PS_LOG_ERROR, "Can't open input image %s\n", imageName);
     657        exit(EXIT_FAILURE);
     658    }
     659    psMetadata *header = psFitsReadHeader(NULL, imageFH); // FITS header
     660
     661    if (!camera && !(camera = pmConfigCameraFromHeader(site, header))) {
     662        psLogMsg("moduleName", PS_LOG_ERROR, "Can't find camera configuration!\n");
     663        exit(EXIT_FAILURE);
     664    }
     665
     666    if (! recipe && !(recipe = pmConfigRecipeFromCamera(camera, "moduleName"))) {
     667        psLogMsg("moduleName", PS_LOG_ERROR, "Can't find recipe configuration!\n");
     668        exit(EXIT_FAILURE);
     669    }
     670
     671    // Now go on and do stuff
     672    ....
     673}
     674\end{verbatim}
    649675
    650676\subsubsection{Lookups}
    … …  
    26602686END
    26612687
    2662 # How to translation PS concepts into database lookups
     2688# How to translate PS concepts into database lookups
    26632689DATABASE        METADATA
    26642690        TYPE            dbEntry         TABLE           COLUMN          GIVENDBCOL      GIVENPS
    … …  
    27712797
    27722798
    2773 # How to translation PS concepts into database lookups
     2799# How to translate PS concepts into database lookups
    27742800DATABASE        METADATA
    27752801        TYPE            dbEntry         TABLE           COLUMN          GIVENDBCOL      GIVENPS
    … …  
    30863112END
    30873113
    3088 # How to translation PS concepts into database lookups
     3114# How to translate PS concepts into database lookups
    30893115DATABASE        METADATA
    30903116        TYPE            dbEntry         TABLE           COLUMN          GIVENDBCOL      GIVENPS
Note: See TracChangeset for help on using the changeset viewer.