Index: /trunk/doc/modules/CameraImages.tex =================================================================== --- /trunk/doc/modules/CameraImages.tex (revision 4562) +++ /trunk/doc/modules/CameraImages.tex (revision 4563) @@ -157,5 +157,6 @@ faster. The cell also contains metadata containers for the concepts and analysis, a link to the parent, and pointers to the various FITS -data, if that corresponds to this level. +data, if that corresponds to this level. A boolean indicates whether +the cell is of interest, allowing it to be excluded from analysis. \begin{verbatim} @@ -173,4 +174,5 @@ psArray *readouts; // The readouts (referred to by number) pmChip *parent; // Parent chip + bool valid; // Do we bother about reading and working with this cell? // FITS data const char *extname; // Extension name, if it corresponds to this level @@ -196,11 +198,12 @@ amplifiers on the device). The chip contains metadata containers for the concepts and analysis, a link to the parent, and 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. +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. \begin{verbatim} @@ -217,4 +220,5 @@ psArray *cells; // The cells (referred to by name) pmFPA *parent; // Parent FPA + bool valid; // Do we bother about reading and working with this chip? // FITS data const char *extname; // Extension name, if it corresponds to this level @@ -240,13 +244,14 @@ of pieces of contiguous silicon). It contains metadata containers for the concepts and analysis, a link to the parent, and pointers to the -various FITS data, if that corresponds to this level. 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. +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. \begin{verbatim} @@ -263,9 +268,12 @@ psArray *chips; // The chips // FITS data - const char *extname; // Extension name, if it corresponds to this level - psArray *pixels; // The pixel data, if it corresponds to this level psMetadata *header; // The FITS header, if it corresponds to this level } pmFPA; \end{verbatim} + +\tbd{Carrying the DB handle around in the pmFPA may not be what we +really want to do in the end (we might want to stuff it into a +separate structure with other sources of information), but for now this +serves as an approximation and a useful convenience.} The constructor for \code{pmFPA} shall be: @@ -367,6 +375,6 @@ extant \code{fpa}. -\tbd{Functions to remove things from an fpa so that only certain -pieces of the FITS file are read in, and not the whole thing?} +\tbd{Functions to set the valid booleans within an fpa so that only +certain pieces of the FITS file are read in, and not the whole thing?} We specify an additional two functions to write out a focal plane Index: /trunk/doc/modules/ModulesSDRS.tex =================================================================== --- /trunk/doc/modules/ModulesSDRS.tex (revision 4562) +++ /trunk/doc/modules/ModulesSDRS.tex (revision 4563) @@ -1,3 +1,3 @@ -%%% $Id: ModulesSDRS.tex,v 1.46 2005-07-15 00:54:03 price Exp $ +%%% $Id: ModulesSDRS.tex,v 1.47 2005-07-15 21:42:13 price Exp $ \documentclass[panstarrs]{panstarrs} @@ -120,87 +120,4 @@ command line if provided, or from the the camera configuration (more detail below). - -\begin{prototype} -bool pmConfigRead(psMetadata **site, psMetadata **camera, psMetadata **recipe, - int *argc, char **argv, const char *recipeName); -psMetadata *pmConfigCameraFromHeader(const psMetadata *site, const psMetadata *header); -psMetadata *pmConfigRecipeFromCamera(const psMetadata *camera, const char *recipeName); -\end{prototype} - -\code{pmConfigRead} shall load the \code{site} configuration -(according to the above rule for determining the source). The -\code{camera} configuration shall also be loaded if it is specified on -the command line (\code{argc, argv}); otherwise it shall be set to -\code{NULL}. The \code{recipe} shall also be loaded from the command -line (if specified) or, if the camera configuration has been loaded, -from the camera configuration and recipe specification therein (see -below). In dealing with the command line parameters, the functions -shall use the appropriate functions in psLib to retrieve and remove -the relevant options from the argument list; this simplifies -assignment of the mandatory arguments, since all the optional command -line arguments are removed leaving only the mandatory arguments. - -\code{pmConfigCameraFromHeader} shall load the \code{camera} -configuration based on the contents of the FITS \code{header}, using -the list of known cameras contained in the \code{site} configuration. -If more than one camera matches the FITS header, a warning shall be -generated and the first matching camera returned. - -\code{pmConfigRecipeFromCamera} shall load the \code{recipe} -configuration based on the \code{recipeName} and the list of known -recipes contained in the \code{camera} configuration (details below). - -We also specify an additional function: -\begin{prototype} -bool pmConfigValidateCamera(psMetadata *camera, psMetadata *header); -\end{prototype} - -This function, used by \code{pmConfigCameraFromHeader}, shall return -\code{true} if the FITS \code{header} matches the rule contained in -the \code{camera} configuration (see \S\ref{sec:camerarule}); -otherwise it shall return \code{false}. - -\subsubsection{Example usage} - -The following is provided as an example of how the above functions -are envisioned in use. - -\begin{verbatim} -int main(int argc, char *argv[]) -{ - // Parse other command-line arguments here - psMetadata *site = NULL; // Site configuration - psMetadata *camera = NULL; // Camera configuration - psMetadata *recipe = NULL; // Recipe configuration - if (! pmConfigRead(&site, &camera, &recipe, &argc, argv, "moduleName")) { - psLogMsg("moduleName", PS_LOG_ERROR, "Can't find site configuration!\n"); - exit(EXIT_FAILURE); - } - // Parse other command-line arguments here - - // The command-line argument list now contains only mandatory arguments - // Assume the first of these is an input image - char *imageName = argv[1]; // Name of FITS file - psFits *imageFH = psFitsOpen(imageName, "r"); // File handle for FITS file - if (! imageFH) { - psLogMsg("moduleName", PS_LOG_ERROR, "Can't open input image %s\n", imageName); - exit(EXIT_FAILURE); - } - psMetadata *header = psFitsReadHeader(NULL, imageFH); // FITS header - - if (!camera && !(camera = pmConfigCameraFromHeader(site, header))) { - psLogMsg("moduleName", PS_LOG_ERROR, "Can't find camera configuration!\n"); - exit(EXIT_FAILURE); - } - - if (! recipe && !(recipe = pmConfigRecipeFromCamera(camera, "moduleName"))) { - psLogMsg("moduleName", PS_LOG_ERROR, "Can't find recipe configuration!\n"); - exit(EXIT_FAILURE); - } - - // Now go on and do stuff - .... -} -\end{verbatim} \subsection{Configuration Files} @@ -225,4 +142,12 @@ the data. \end{itemize} + +\tbd{No doubt there is a need for better security than storing the +database password directly in the file, but we push this problem onto +the stack for now.} + +\tbd{We will add other data sources in the future, e.g., file paths, +configuration for Nebulous and DVO, etc.}. + An example site configuration file: @@ -341,5 +266,7 @@ CELLS METADATA left METADATA # Left amplifier + CELL.BIASSEC.SOURCE STR HEADER CELL.BIASSEC STR BIASSEC + CELL.TRIMSEC.SOURCE STR HEADER CELL.TRIMSEC STR DATASEC CELL.PARITY S32 1 @@ -347,6 +274,8 @@ right METADATA # Right amplifier # This cell is read out in the opposite direction + CELL.BIASSEC.SOURCE STR HEADER CELL.BIASSEC STR BIASSEC - CELL.TRIMSEC STR DATASEC + CELL.TRIMSEC.SOURCE STR VALUE + CELL.TRIMSEC STR [1025:2048,1:2048] CELL.PARITY S32 -1 END @@ -358,5 +287,7 @@ associated with a chip, and has a cell type. -The \code{_SOURCE} keywords will be explained in \S\ref{sec:concepts}. +The \code{.SOURCE} keywords in the \code{CELLS}, explained in more +detail in \S\ref{sec:concepts}, are necessary in order to distinguish +a pointer to a header from an actual value. \paragraph{Deriving concept values} @@ -412,5 +343,5 @@ DEFAULTS METADATA CELL.BAD S32 0 - CELL.YPARITY_DEPEND STR CHIP.NAME + CELL.YPARITY.DEPEND STR CHIP.NAME CELL.YPARITY METADATA ccd00 S32 -1 @@ -421,5 +352,5 @@ END -# How to translation PS concepts into database lookups +# How to translate PS concepts into database lookups DATABASE METADATA TYPE dbEntry TABLE COLUMN GIVENDBCOL GIVENPS @@ -429,5 +360,5 @@ \end{verbatim} -The \code{_DEPEND} entry in the \code{DEFAULTS} will be explained in +The \code{.DEPEND} entry in the \code{DEFAULTS} will be explained in \S\ref{sec:concepts}. @@ -463,4 +394,14 @@ configuration filename. +An example: +\begin{verbatim} +# Recipes for LRIS +RECIPES METADATA + PHASE1 STR lris_phase1.config + PHASE2 STR lris_phase2.config + PHASE4 STR lris_phase4.config +END +\end{verbatim} + \subsubsection{Recipe Configuration} @@ -481,5 +422,5 @@ level, while others are logically defined at the cell level. -Below is a list of concepts that the IPP should require, with the +Below is a list of concepts that the IPP requires, with the expected type and a short description. @@ -517,8 +458,9 @@ \item The \code{DEFAULTS} value. \end{itemize} -When a concept is retrieved, it shall be stored in the cache to -optimise future retrieval. We have specified a cache and FITS header -storage in the various focal plane structures for the purposes of -concept retrieval. +When a concept is retrieved, it shall be stored in a cache (a +\code{psMetadata} within the FPA/chip/cell structures) to optimise +future retrieval. We have specified a cache and FITS header storage +in the various focal plane structures for the purposes of concept +retrieval. Because of the variety of methods for specifying these concepts @@ -528,17 +470,17 @@ In the \code{DEFAULTS} table in the camera configuration, we allow the -specification of the concept with an additional suffix, -\code{_DEPEND}. The value (of type \code{STR}) of the -\code{CONCEPT_DEPEND} is the name of a concept on which the first -concept depends. For example, it might depend on the chip name. Then -the first concept becomes of type \code{METADATA}, with the component -keywords being the value of the second concept (on which the first -depends). To avoid infinite recursion, no further dependency is -permitted. An example of the dependency: +specification of the concept with an additional suffix, \code{DEPEND}. +The value (of type \code{STR}) of the \code{CONCEPT.DEPEND} is the +name of a concept on which the first concept depends. For example, it +might depend on the chip name. Then the first concept becomes of type +\code{METADATA}, with the component keywords being the value of the +second concept (on which the first depends). To avoid infinite +recursion, no further dependency is permitted. An example of the +dependency: \begin{verbatim} # Default PS concepts that may be specified by value DEFAULTS METADATA - CELL.GAIN_DEPEND STR CHIP.NAME + CELL.GAIN.DEPEND STR CHIP.NAME CELL.GAIN METADATA ccd00 F32 1.2 @@ -551,5 +493,5 @@ In the FITS \code{TRANSLATION} table in the camera configuration, for certain concepts we allow the specification of the concept with an -additional suffix, \code{_FORMAT} which specifies the format of the +additional suffix, \code{FORMAT} which specifies the format of the FITS header. The value is dependent upon the particular concept. @@ -559,5 +501,5 @@ ways in FITS files, so care must be taken to specify what the format is in the file under consideration. Permitted values of -\code{CELL.TIME_FORMAT} are: +\code{CELL.TIME.FORMAT} are: \begin{itemize} @@ -591,11 +533,13 @@ The binning is usually specified in FITS headers either as separate headers for the x and the y, or in the same FITS header separated by a -space or a comma. Permitted values of \code{CELL.BINNING_FORMAT} are: +space or a comma. Permitted values of \code{CELL.BINNING.FORMAT} are: \begin{itemize} -\item \code{SEPARATE}: The \code{CELL.BINNING} contains the headers - for the x and the y binning separated by whitespace or a comma. -\item \code{TOGETHER}: The value pointed to by \code{CELL.BINNING} - contains the x and y binning separated by whitespace and/or a comma. +\item \code{SEPARATE}: The \code{CELL.BINNING} contains the header + keywords for the x and the y binning separated by whitespace or a + comma. +\item \code{TOGETHER}: \code{CELL.BINNING} contains the keyword for + which the x and y binning are separated by whitespace and/or a + comma. \end{itemize} @@ -604,5 +548,5 @@ The RA and Declination of the boresight might be specified in a few ways. We need to specify both how the value is interpreted and the -units. \code{FPA.RA_FORMAT} and \code{FPA.DEC_FORMAT} should be one +units. \code{FPA.RA.FORMAT} and \code{FPA.DEC.FORMAT} should be one of the following: @@ -629,22 +573,104 @@ contain \code{CELL.GAIN} and \code{CELL.READNOISE} values as well instead of going to the trouble of specifying these in the -\code{DEFAULTS} with a long \code{_DEPENDS} listing. - -However, we need to specify for these where the value comes from. It -should be sufficient to declare the following rules: +\code{DEFAULTS} with a long \code{.DEPENDS} listing. + +However, in some cases, we need to specify for these where the value +comes from. We declare the following rule: \begin{itemize} \item If the type is other than \code{STR}, then the concept has that value for the cell. -\item If the type is \code{STR} and contains square brackets - \code{[]}, then it shall be interpreted as a value for one of the - image section concepts (\code{CELL.BIASSEC} and - \code{CELL.TRIMSEC}). -\item Otherwise, it shall be interpreted as a FITS header keyword - which will provide the value. +\item If the type is \code{STR}, then the value might potentially be + confused between being a header keyword or an actual value. For + this reason, we introduce an additional concept suffix, + \code{.SOURCE} (of type \code{STR}) which may be either + \code{HEADER} or \code{VALUE}. \end{itemize} -These rules mean that we don't have to bother adding an additional -suffix like \code{_SOURCE}. + +\subsection{Configuration APIs} + +\begin{prototype} +bool pmConfigRead(psMetadata **site, psMetadata **camera, psMetadata **recipe, + int *argc, char **argv, const char *recipeName); +psMetadata *pmConfigCameraFromHeader(const psMetadata *site, const psMetadata *header); +psMetadata *pmConfigRecipeFromCamera(const psMetadata *camera, const char *recipeName); +\end{prototype} + +\code{pmConfigRead} shall load the \code{site} configuration +(according to the above rule for determining the source). The +\code{camera} configuration shall also be loaded if it is specified on +the command line (\code{argc, argv}); otherwise it shall be set to +\code{NULL}. The \code{recipe} shall also be loaded from the command +line (if specified) or, if the camera configuration has been loaded, +from the camera configuration and recipe specification therein (see +below). In dealing with the command line parameters, the functions +shall use the appropriate functions in psLib to retrieve and remove +the relevant options from the argument list; this simplifies +assignment of the mandatory arguments, since all the optional command +line arguments are removed leaving only the mandatory arguments. + +\code{pmConfigCameraFromHeader} shall load the \code{camera} +configuration based on the contents of the FITS \code{header}, using +the list of known cameras contained in the \code{site} configuration. +If more than one camera matches the FITS header, a warning shall be +generated and the first matching camera returned. + +\code{pmConfigRecipeFromCamera} shall load the \code{recipe} +configuration based on the \code{recipeName} and the list of known +recipes contained in the \code{camera} configuration (details below). + +We also specify an additional function: +\begin{prototype} +bool pmConfigValidateCamera(psMetadata *camera, psMetadata *header); +\end{prototype} + +This function, used by \code{pmConfigCameraFromHeader}, shall return +\code{true} if the FITS \code{header} matches the rule contained in +the \code{camera} configuration (see \S\ref{sec:camerarule}); +otherwise it shall return \code{false}. + +\subsubsection{Example usage} + +The following is provided as an example of how the above functions +are envisioned in use. + +\begin{verbatim} +int main(int argc, char *argv[]) +{ + // Parse other command-line arguments here + psMetadata *site = NULL; // Site configuration + psMetadata *camera = NULL; // Camera configuration + psMetadata *recipe = NULL; // Recipe configuration + if (! pmConfigRead(&site, &camera, &recipe, &argc, argv, "moduleName")) { + psLogMsg("moduleName", PS_LOG_ERROR, "Can't find site configuration!\n"); + exit(EXIT_FAILURE); + } + // Parse other command-line arguments here + + // The command-line argument list now contains only mandatory arguments + // Assume the first of these is an input image + char *imageName = argv[1]; // Name of FITS file + psFits *imageFH = psFitsOpen(imageName, "r"); // File handle for FITS file + if (! imageFH) { + psLogMsg("moduleName", PS_LOG_ERROR, "Can't open input image %s\n", imageName); + exit(EXIT_FAILURE); + } + psMetadata *header = psFitsReadHeader(NULL, imageFH); // FITS header + + if (!camera && !(camera = pmConfigCameraFromHeader(site, header))) { + psLogMsg("moduleName", PS_LOG_ERROR, "Can't find camera configuration!\n"); + exit(EXIT_FAILURE); + } + + if (! recipe && !(recipe = pmConfigRecipeFromCamera(camera, "moduleName"))) { + psLogMsg("moduleName", PS_LOG_ERROR, "Can't find recipe configuration!\n"); + exit(EXIT_FAILURE); + } + + // Now go on and do stuff + .... +} +\end{verbatim} \subsubsection{Lookups} @@ -2660,5 +2686,5 @@ END -# How to translation PS concepts into database lookups +# How to translate PS concepts into database lookups DATABASE METADATA TYPE dbEntry TABLE COLUMN GIVENDBCOL GIVENPS @@ -2771,5 +2797,5 @@ -# How to translation PS concepts into database lookups +# How to translate PS concepts into database lookups DATABASE METADATA TYPE dbEntry TABLE COLUMN GIVENDBCOL GIVENPS @@ -3086,5 +3112,5 @@ END -# How to translation PS concepts into database lookups +# How to translate PS concepts into database lookups DATABASE METADATA TYPE dbEntry TABLE COLUMN GIVENDBCOL GIVENPS