Index: trunk/doc/modules/ModulesSDRS.tex =================================================================== --- trunk/doc/modules/ModulesSDRS.tex (revision 1997) +++ trunk/doc/modules/ModulesSDRS.tex (revision 2034) @@ -1,3 +1,3 @@ -%%% $Id: ModulesSDRS.tex,v 1.16 2004-10-07 18:15:06 eugene Exp $ +%%% $Id: ModulesSDRS.tex,v 1.17 2004-10-09 00:35:09 price Exp $ \documentclass[panstarrs]{panstarrs} @@ -10,5 +10,5 @@ \project{Pan-STARRS Image Processing Pipeline} \organization{Institute for Astronomy} -\version{01} +\version{02} \docnumber{PSDC-430-008} % note the use of the docnumber & version number: @@ -353,4 +353,113 @@ image), the function shall generate an error. + + +\section{Calibration} + +The calibration module essentially consists of combining multiple +images of a particular type in order to build up signal-to-noise. For +this, we require a general purpose image combination module. We +forsee this module as only acting upon data from the same detector, +and so each input image will have the same noise characteristics. + +\begin{verbatim} +typedef struct { + psStats *stats; // Statistics to use in combining pixels + unsigned int maskVal, // Mask pixels where mask & maskVal == 1 + float fracHigh; // Fraction of high pixels to throw + float fracLow; // Fraction of low pixels to throw + int nKeep; // Number of pixels to be sure to keep +} pmCombineParams; + +psImage * +pmReadoutCombine(psImage *output, // Output image, or NULL + const psList *inputs, // List of input readouts + pmCombineParams *params, // Combination parameters + const psVector *zero, // Offsets to apply for each image + const psVector *scale, // Scales to apply for each image + bool applyZeroScale, // Are zero and scale for application, or only noise properties? + float gain, // Gain in e/ADU + float readnoise // Read noise in e + ); +\end{verbatim} + +\code{pmReadoutCombine} combines input images pixel by pixel --- for +each pixel of the output image, a stack of contributing input pixels +is formed and combined. Several of its input parameters are lists or +vectors, and if these are not all of the same length (or \code{NULL}), +the module shall generate an error and return \code{NULL}. + +If the provided \code{output} is \code{NULL}, then the module shall +allocate a new image of sufficient size for the input images. If the +\code{output} image is non-\code{NULL} and is not of sufficient size +for the combined image, the module shall generate an error and return +\code{NULL}. + +If the \code{inputs} is \code{NULL}, the module shall generate an +error and return \code{NULL}. Otherwise, the \code{inputs} shall be a +list of \code{psReadout}s. The images contained within the +\code{psReadout}s need not all be of the same size, but the module +shall take into account the offsets (\code{col0,row0}) from the corner +of the detector when comparing pixels, so that it is the same +\textit{physical} pixels that are combined. + +The parameters used in the combination, including how the pixels are +to be combined, and how the rejection is performed is contained within +the \code{params}, which may not be \code{NULL} (otherwise the module +shall generate an error and return \code{NULL}). We choose to use +this structure instead of supplying the values separately in order to +keep down the number of parameters to \code{pmReadoutCombine}; the +\code{psCombineParams} may be recycled for subsequent calls to +\code{pmReadoutCombine} since the values are not dependent upon the +choice of inputs, but merely specify how the combination is to be +performed. + +The particular statistic specified by \code{stats} shall be used to +combine each stack of pixels from the input images. Only one of the +statistics choices may be specified, otherwise the module shall +generate an error and return \code{NULL}. + +If the \code{maskVal} is non-zero, then pixels in the \code{mask} of +each \code{psReadout} in the \code{inputs} which satisfy the +\code{maskVal} shall not have the corresponding pixels placed in the +stack for combination. + +After masking, but before performing the combination, the highest +\code{fracHigh} fraction and lowest \code{fracLow} fraction of pixels +in the stack are immediately rejected, unless this would leave less +than \code{nKeep} pixels in the stack, in which case no immediate +rejection is performed. + +If the \code{zero} vector is non-\code{NULL} and \code{applyZeroScale} +is \code{true}, then the appropriate values shall be added to the +\code{inputs} before combining. In the event that the type of the +\code{psVector} is more precise than that of any of the \code{inputs}, +the module shall generate a warning and truncate the sum to the +precision of the image. If \code{zero} is non-\code{NULL} and +\code{applyZeroScale} is false, then the values shall only be used in +calculating the noise. + +If the \code{scale} vector is non-\code{NULL} and +\code{applyZeroScale} is \code{true}, then the appropriate values +shall multiply the \code{inputs} before combining. In the event that +the type of the \code{psVector} is more precise than that of any of +the \code{inputs}, the module shall generate a warning and truncate +the multiplication to the precision of the image. If \code{scale} is +non-\code{NULL} and \code{applyZeroScale} is false, then the values +shall only be used in calculating the noise. + +The purpose of \code{applyZeroScale} is to allow combination of fringe +frames, where the frames have been deliberately sky-subtracted and +rescaled (to get the fringes amplitudes running from -1 to 1), which +actions should not be undone when combining, but yet it is desirable +to provide the \code{zero} and \code{scale} values so that the correct +noise properties are used in the combination. + +If the \code{gain} and \code{readnoise} are positive and non-negative +(respectively), then these shall be used to provide weights for the +combination. + + + \section{Revision Change Log} \input{ChangeLogSDRS.tex} @@ -607,5 +716,4 @@ %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - \begin{verbatim} char *pmCameraFromHeader (psFitsHeader *header);