Index: trunk/doc/modules/ModulesSDRS.tex =================================================================== --- trunk/doc/modules/ModulesSDRS.tex (revision 6400) +++ trunk/doc/modules/ModulesSDRS.tex (revision 6422) @@ -1,3 +1,3 @@ -%%% $Id: ModulesSDRS.tex,v 1.73 2006-02-09 19:44:21 price Exp $ +%%% $Id: ModulesSDRS.tex,v 1.74 2006-02-11 03:16:55 price Exp $ \documentclass[panstarrs,spec]{panstarrs} @@ -144,4 +144,6 @@ \item \code{DBPASSWORD} of type \code{STR}: The corresponding database password for \code{psDBInit}. + \item \code{DBNAME} of type \code{STR}: The database name for + \code{psDBInit}. \end{itemize} \item \code{CAMERAS} of type \code{METADATA}: A list of instruments @@ -346,4 +348,5 @@ \paragraph{Deriving concept values} +\label{sec:derivingconcepts} The PS concepts are described in more detail in \S\ref{sec:concepts}. @@ -454,5 +457,5 @@ PHASE1 STR lris_phase1.config PHASE2 STR lris_phase2.config - PHASE4 STR lris_phase4.config + PHASE4 STR lris_phase4.config END \end{verbatim} @@ -465,54 +468,12 @@ \subsection{PS Concepts} -\label{sec:concepts} - -Each image has associated with it what we will call {\it concepts} -(for want of a better word). These are values corresponding to -general quantities and qualities necessary to understand and interpret -the data such as airmass, date, read noise and filter. The values of -each of the below concepts shall be determined when the FPA is read -into memory (via \code{pmFPARead}), and stored at the appropriate -level in the focal plane hierarchy. - -Below is a list of concepts that the IPP requires, with the -expected type and a short description. - -\begin{itemize} -\item \code{FPA.AIRMASS} (F32): Airmass at which the observation is made (boresight). -\item \code{FPA.FILTER} (STR): Filter used in observation -\item \code{FPA.POSANGLE} (F32): Position angle for camera -\item \code{FPA.RA} (F64): Right Ascension of boresight in radians -\item \code{FPA.DEC} (F64): Declination of boresight in radians -\item \code{FPA.RADECSYS} (STR): System of RA,Dec (e.g., J2000 or ICRS) -\item \code{FPA.NAME} (STR): An identifier (e.g., observation number) for the FPA instance -\item \code{CHIP.NAME} (STR): The name of the chip (unique within the FPA) --- set at FITS read -\item \code{CELL.NAME} (STR): The name of the cell (unique within the parent chip) --- set at FITS read -\item \code{CELL.TIME} (\code{psTime}): Time of observation start -\item \code{CELL.READDIR} (S32): Read direction: line (1) or column (2) -\item \code{CELL.BIASSEC} (STR): Overscan region(s) -\item \code{CELL.TRIMSEC} (STR): Trim region -\item \code{CELL.GAIN} (F32): CCD gain (e/ADU) -\item \code{CELL.READNOISE} (F32): CCD read noise (e) -\item \code{CELL.SATURATION} (F32): CCD saturation point (ADU) -\item \code{CELL.BAD} (F32): CCD bad pixel point (ADU) -\item \code{CELL.XBIN} (S32): CCD binning in x -\item \code{CELL.YBIN} (S32): CCD binning in y -\item \code{CELL.XPARITY} (S32): Direction of CCD readout in x relative to the rest of the chip -\item \code{CELL.YPARITY} (S32): Direction of CCD readout in y relative to the rest of the chip -\item \code{CELL.EXPOSURE} (F32): Exposure time of image (sec) -\item \code{CELL.DARKTIME} (F32): Dark time for image (sec) -\end{itemize} - -\tbd{Note that CELL.EXPOSURE, CELL.DARKTIME and CELL.TIME should -actually be specified at the readout level. However, at this present -time, we're not sure how these should be specified, and so we move -them up to the cell level and assume that all readouts are of the same -exposure and dark time.} + +\subsubsection{Ingest} For different camera systems, these concepts are not always known by the same name, nor are they generally obtained in the same manner, and so their source or value must be specified in the camera configuration -file. The value of a concept shall be found by searching in the -following order: +file. At ingest, the value of a concept shall be found by searching in +the following order: \begin{itemize} \item The cell data from the \code{CELLS} metadata in the camera configuration. @@ -521,9 +482,4 @@ \item The \code{DEFAULTS} value. \end{itemize} - -After ingest (performed by \code{pmFPARead}, the user may safely -assume that all of the above concepts exist (defined at the -appropriate level), is of the specified type and in the specified -format. \subsubsection{Dependencies for defaults} @@ -766,4 +722,195 @@ \end{verbatim} +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\section{``Concepts''} +\label{sec:concepts} + +Each image from an astronomical instrument has associated with it what +we will call {\it concepts} (for want of a better word; \tbd{we would +like to call this ``metadata'', but unfortunately that name is already +taken}). These are values corresponding to general quantities and +qualities necessary to understand and interpret the data, such as +airmass, date, read noise and filter. The values of each of the below +concepts shall be determined when the FPA is read into memory (via +\code{pmFPARead}), and stored at the appropriate level in the focal +plane hierarchy. + +After ingest (performed in \code{pmFPARead}, the user may safely +assume that all of the above concepts exist at the appropriate level +(meaning the user needn't be hampered by excessive error checking), is +of the specified type (meaning the user doesn't need to worry about +whether the value of interest is stored in, e.g., floating point or +double precision or even a colon-delimited string) and in the +specified format (meaning the user doesn't need to know, e.g., whether +the right ascension is in radians or degrees) --- all the conversions +are handled by the ``concepts'' functions at ingest. + +Most of the structures and functions in this section are intended to +be ``private'', since there is no need envisioned for the user to call +them directly. + +\subsection{Specifying a concept} + +Specifying a ``concept'' requires a (meaningful) name (preferably with +the level in the name, e.g., \code{CELL.EXPOSURE}), a +comment/description, a type, a default or blank value, functions to +read and write, and a level that the concept applies to +(FPA/Chip/Cell). + +\begin{datatype} +typedef psMetadataItem* (*p_pmConceptReadFunc)(pmFPA *fpa, pmChip *chip, pmCell *cell, psDB *db); +typedef bool (*p_pmConceptWriteFunc)(pmFPA *fpa, pmChip *chip, pmCell *cell, psDB *db); +typedef struct { + psMetadataItem *blank; // Blank value of concept; also contains the name + p_pmConceptReadFunc read; // Function to call to read the concept + p_pmConceptWriteFunc write; // Function to call to write the concept +} p_pmConceptSpec; +\end{datatype} + +\code{blank} is a \code{psMetadataItem} that provides the name, type +and default/blank value for the concept. \code{read} and \code{write} +provide the functions to read and write. + +A concept specification may be allocated: +\begin{prototype} +p_pmConceptSpec *p_pmConceptSpecAlloc(psMetadataItem *blank, pmConceptReadFunc read, + pmConceptWriteFunc write); +\end{prototype} + +\subsection{Registering a concept} + +The concept specifications that have been registered shall be stored in +three \code{psMetadata}s, one for each level (FPA, chip, cell). + +Registering a concept is achieved by: +\begin{prototype} +bool pmConceptRegister(psMetadataItem *blank, pmConceptReadFunc read, + pmConceptWriteFunc write, pmConceptLevel level); +\end{prototype} + +\code{pmConceptRegister} shall generate a concept specification from +the provided \code{blank}, and \code{read} and \code{write} functions, +and register it in the metadata specified by the \code{level}. + +\code{pmConceptLevel} simply specifies which level in the focal plane +hiearchy the concept applies to: +\begin{datatype} +typedef enum { + PM_CONCEPT_LEVEL_FPA, // Store in the FPA + PM_CONCEPT_LEVEL_CHIP, // Store in the chip + PM_CONCEPT_LEVEL_CELL // Store in the cell +} pmConceptLevel; +\end{datatype} + +A \code{read} function of \code{NULL} indicates that there is no +special interpretation of the concept required, and that it can be +used as read. A \code{write} function of \code{NULL} indicates that +no special formatting of the concept is required, and that it can be +written as is. + + +\subsection{Default concepts} + +Below is a list of concepts that the IPP will use, with the expected +type and a short description. + +\begin{itemize} +\item \code{FPA.NAME} (\code{psString}): An identifier (e.g., observation number) for the FPA instance +\item \code{FPA.AIRMASS} (F32): Airmass at which the observation is made (boresight) +\item \code{FPA.FILTER} (\code{psString}): Filter used in observation +\item \code{FPA.POSANGLE} (F32): Position angle for camera +\item \code{FPA.RADECSYS} (\code{psString}): System of RA,Dec (e.g., J2000 or ICRS) +\item \code{FPA.RA} (F64): Right Ascension of boresight in radians +\item \code{FPA.DEC} (F64): Declination of boresight in radians +\item \code{CHIP.NAME} (\code{psString}): The name of the chip (unique within the FPA) --- set at FITS read +\item \code{CELL.NAME} (\code{psString}): The name of the cell (unique within the parent chip) --- set at FITS read +\item \code{CELL.GAIN} (F32): CCD gain (e/ADU) +\item \code{CELL.READNOISE} (F32): CCD read noise (e) +\item \code{CELL.SATURATION} (F32): CCD saturation point (ADU) +\item \code{CELL.BAD} (F32): CCD bad pixel point (ADU) +\item \code{CELL.XPARITY} (S32): Direction of CCD readout in x relative to the rest of the chip +\item \code{CELL.YPARITY} (S32): Direction of CCD readout in y relative to the rest of the chip +\item \code{CELL.READDIR} (S32): Read direction: line (1) or column (2) +\item \code{CELL.EXPOSURE} (F32): Exposure time of image (sec) +\item \code{CELL.DARKTIME} (F32): Dark time for image (sec) +\item \code{CELL.TRIMSEC} (\code{psRegion*}): Trim region +\item \code{CELL.BIASSEC} (\code{psList*} of \code{psRegion*}): Overscan region(s) +\item \code{CELL.XBIN} (S32): CCD binning in x +\item \code{CELL.YBIN} (S32): CCD binning in y +\item \code{CELL.TIMESYS} (\code{psTimeType}): Time system in use +\item \code{CELL.TIME} (\code{psTime*}): Time of observation start +\item \code{CELL.X0} (S32): x position of cell (0,0) on the chip +\item \code{CELL.Y0} (S32): y position of cell (0,0) on the chip +\end{itemize} + +\tbd{CELL.EXPOSURE, CELL.DARKTIME and CELL.TIME should actually be +specified at the readout level. However, at this present time, we're +not sure how these should be specified, and so we move them up to the +cell level and assume that all readouts are of the same exposure and +dark time.} + +The concept specifications for the above shall be registered by +\code{pmConceptsInit}: +\begin{prototype} +bool pmConceptsInit(void); +\end{prototype} + +Since defined concept specifications are required before any concept +ingest can take place, all functions that work with the concepts must +call \code{pmConceptsInit} first. + +The concept specification metadata containers and the concept +specifications that have been registered shall all be freed by +\code{pmConceptsDone}: +\begin{prototype} +void pmConceptsDone(void); +\end{prototype} +Calling \code{pmConceptsDone} is required in order to avoid a memory +leak, since the metadata containers are defined \code{static}. + +\subsection{Reading, Writing and Blanking} + +Reading concepts is the act of determining their values and setting +them in the \code{concepts} metadata in the focal plane hierarchy. +Writing concepts is the act of taking the \code{concepts} metadata +which is in the focal plane hierarchy and preparing them for output. +By ``blanking'', we mean setting the concepts to a default or blank +value (e.g., \code{NaN} for floating point); this takes place before +reading, and can be used to set up a focal plane hierarchy without +reading from any particular source. + +The following functions shall read, write or blank (as appropriate) +the concepts at the appropriate level in the focal plane hierarchy: +\begin{prototype} +bool p_pmConceptsReadFPA(pmFPA *fpa); +bool p_pmConceptsReadChip(pmChip *chip); +bool p_pmConceptsReadCell(pmCell *cell); +bool p_pmConceptsWriteFPA(pmFPA *fpa); +bool p_pmConceptsWriteChip(pmChip *chip); +bool p_pmConceptsWriteCell(pmCell *cell); +bool p_pmConceptsBlankFPA(pmFPA *fpa); +bool p_pmConceptsBlankChip(pmChip *chip); +bool p_pmConceptsBlankCell(pmCell *cell); +\end{prototype} + +Under ordinary circumstances, these functions will be called by +\code{pmFPARead}, \code{pmFPAWrite} and \code{pmFPAConstruct}. + + +\subsection{Copying concepts} + +The values of concepts may be copied from one source to another: +\begin{prototype} +bool pmFPACopyConcepts(pmFPA *target, pmFPA *source); +\end{prototype} + +\code{pmFPACopyConcepts} shall iterate through the focal plane +hierarchy, copying the values of the concepts from the \code{source} +to the \code{target}. + + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + \input{CameraImages.tex} @@ -867,5 +1014,5 @@ pmReadout *pmSubtractBias(pmReadout *in, pmOverscanOptions *overscanOpts, psRegion imageRegion, psList *overscanRegions, - const pmReadout *bias, const pmReadout *dark); + const pmReadout *bias, const pmReadout *dark); \end{prototype} @@ -970,5 +1117,5 @@ pmOverscanOptions *pmOverscanOptionsAlloc(bool single, bool scanRows, pmFit fitType, unsigned int order, - psStats *stat); + psStats *stat); \end{prototype} @@ -1726,5 +1873,5 @@ float Peak; // peak counts above sky float Sky; // sky level (background) - float SN; // approx signal-to-noise + float SN; // approx signal-to-noise int nPixels; // number of pixels used } pmMoments; @@ -1813,5 +1960,5 @@ psS32 nIter; // number of iterations pmModelStatus status; // fit status - float radius; // fit radius actually used + float radius; // fit radius actually used } pmModel; \end{datatype} @@ -2089,15 +2236,15 @@ \begin{datatype} typedef struct { - pmModelType type; ///< PSF Model in use - psArray *params; ///< Model parameters (psPolynomial2D) - psPolynomial4D *ApTrend; ///< ApResid vs (x,y,rflux) (rflux = ten(0.4*mInst) - pmGrowthCurve *growth; ///< apMag vs Radius - float ApResid; ///< ??? - float dApResid; ///< ??? - float skyBias; ///< ??? - float skySat; ///< ??? - float chisq; ///< PSF goodness statistic - int nPSFstars; ///< number of stars used to measure PSF - int nApResid; ///< number of stars used to measure ApResid + pmModelType type; ///< PSF Model in use + psArray *params; ///< Model parameters (psPolynomial2D) + psPolynomial4D *ApTrend; ///< ApResid vs (x,y,rflux) (rflux = ten(0.4*mInst) + pmGrowthCurve *growth; ///< apMag vs Radius + float ApResid; ///< ??? + float dApResid; ///< ??? + float skyBias; ///< ??? + float skySat; ///< ??? + float chisq; ///< PSF goodness statistic + int nPSFstars; ///< number of stars used to measure PSF + int nApResid; ///< number of stars used to measure ApResid } pmPSF; \end{datatype} @@ -2197,5 +2344,5 @@ PSFTRY_MASK_EXT_FAIL = 0x02, // 2: ext model failed to converge PSFTRY_MASK_PSF_FAIL = 0x04, // 3: psf model failed to converge - PSFTRY_MASK_BAD_PHOT = 0x08, // 4: invalid source photometry + PSFTRY_MASK_BAD_PHOT = 0x08, // 4: invalid source photometry PSFTRY_MASK_ALL = 0x0f, } pmPSFtryMaskValues; @@ -2272,14 +2419,14 @@ \begin{prototype} bool pmSourceDefinePixels(pmSource *mySource, - pmReadout *readout, - psF32 x, - psF32 y, - psF32 Radius) + pmReadout *readout, + psF32 x, + psF32 y, + psF32 Radius) bool pmSourceRedefinePixels(pmSource *mySource, pmReadout *readout, psF32 x, - psF32 y, - psF32 Radius) + psF32 y, + psF32 Radius) \end{prototype} @@ -2304,5 +2451,5 @@ pmSource *pmSourceLocalSky(pmSource *source, psStatsOptions statsOptions, - float Radius) + float Radius) \end{prototype} @@ -2503,7 +2650,7 @@ bool pmSourcePhotometry (float *fitMag, // integrated fit magnitude float *obsMag, // aperture flux magnitude - pmModel *model, // model used for photometry - psImage *image, // image pixels to be used - psImage *mask // mask of pixels to ignore + pmModel *model, // model used for photometry + psImage *image, // image pixels to be used + psImage *mask // mask of pixels to ignore ); \end{prototype} @@ -2526,17 +2673,17 @@ \begin{verbatim} PM_SOURCE_DEFECT: 8 -PM_SOURCE_SATURATED: 8 -PM_SOURCE_SATSTAR: 10 -PM_SOURCE_PSFSTAR: 1 -PM_SOURCE_GOODSTAR: 1 +PM_SOURCE_SATURATED: 8 +PM_SOURCE_SATSTAR: 10 +PM_SOURCE_PSFSTAR: 1 +PM_SOURCE_GOODSTAR: 1 PM_SOURCE_POOR_FIT_PSF: 7 PM_SOURCE_FAIL_FIT_PSF: 4 -PM_SOURCE_FAINTSTAR: 4 -PM_SOURCE_GALAXY: 2 +PM_SOURCE_FAINTSTAR: 4 +PM_SOURCE_GALAXY: 2 PM_SOURCE_FAINT_GALAXY: 2 -PM_SOURCE_DROP_GALAXY: 2 +PM_SOURCE_DROP_GALAXY: 2 PM_SOURCE_FAIL_FIT_GAL: 2 PM_SOURCE_POOR_FIT_GAL: 2 -PM_SOURCE_OTHER: ? +PM_SOURCE_OTHER: ? \end{verbatim}