Index: trunk/doc/modules/ModulesSDRS.tex =================================================================== --- trunk/doc/modules/ModulesSDRS.tex (revision 1110) +++ trunk/doc/modules/ModulesSDRS.tex (revision 1113) @@ -1,3 +1,3 @@ -%%% $Id: ModulesSDRS.tex,v 1.4 2004-06-26 03:42:48 price Exp $ +%%% $Id: ModulesSDRS.tex,v 1.5 2004-06-29 01:44:23 price Exp $ \documentclass[panstarrs]{panstarrs} @@ -294,4 +294,5 @@ \subsection{Bias subtraction} +\label{sec:bias} Given an input image and various other parameters, @@ -299,5 +300,5 @@ The API shall be the following: \begin{verbatim} -psReadout *psPhase2SubtractBias(psReadout *in, void *fitSpec, psOverscanAxis overscanAxis, psBiasFit fit, +psReadout *psPhase2SubtractBias(psReadout *in, void *fitSpec, psOverscanAxis overscanAxis, psFit fit, int nBin, const psList *regions, const psStats *stat, const psImage *bias); \end{verbatim} @@ -310,24 +311,23 @@ \begin{verbatim} -/** Fit type for bias */ +/** Fit type */ typedef enum { - PS_OVERSCAN_FIT_NONE, ///< No fit to bias - PS_OVERSCAN_FIT_LINEAR, ///< Do linear interpolation on bias - PS_OVERSCAN_FIT_POLYNOMIAL, ///< Fit polynomial to bias - PS_OVERSCAN_FIT_CHEBYSHEV, ///< Fit chebyshev to bias - PS_OVERSCAN_FIT_SPLINE ///< Fit cubic splines to bias -} psBiasFit; -\end{verbatim} - -If \code{fitSpec} is \code{NULL}, or \code{fit} is -\code{PS_OVERSCAN_FIT_NONE}, then no fit shall be performed to the -overscan. If \code{fit} is \code{PS_OVERSCAN_FIT_LINEAR}, then the -function shall perform simple linear interpolation between points in -the overscan. Otherwise, \code{fitSpec} shall be interpreted to be a -structure of the appropriate type (\code{psPolynomial1D} for -\code{PS_OVERSCAN_FIT_POLYNOMIAL} and -\code{PS_OVERSCAN_FIT_CHEBYSHEV}, and \code{psSpline1D} for -\code{PS_OVERSCAN_FIT_SPLINE}), and the overscan shall be fit using -the specified functional form. Upon return, the \code{fitSpec} shall + PS_FIT_NONE, ///< No fit + PS_FIT_LINEAR, ///< Do linear interpolation + PS_FIT_POLYNOMIAL, ///< Fit polynomial + PS_FIT_CHEBYSHEV, ///< Fit chebyshev + PS_FIT_SPLINE ///< Fit cubic splines +} psFit; +\end{verbatim} + +If \code{fitSpec} is \code{NULL}, or \code{fit} is \code{PS_FIT_NONE}, +then no fit shall be performed to the overscan. If \code{fit} is +\code{PS_FIT_LINEAR}, then the function shall perform simple linear +interpolation between points in the overscan. Otherwise, +\code{fitSpec} shall be interpreted to be a structure of the +appropriate type (\code{psPolynomial1D} for \code{PS_FIT_POLYNOMIAL} +and \code{PS_FIT_CHEBYSHEV}, and \code{psSpline1D} for +\code{PS_FIT_SPLINE}), and the overscan shall be fit using the +specified functional form. Upon return, the \code{fitSpec} shall contain the coefficients of the overscan fit. @@ -351,5 +351,5 @@ warning shall be generated if the \code{overscanAxis} is \code{PS_OVERSCAN_NONE} or \code{PS_OVERSCAN_ALL} and the \code{fit} -is not \code{PS_OVERSCAN_FIT_NONE}. +is not \code{PS_FIT_NONE}. If the \code{overscanAxis} is \code{PS_OVERSCAN_ROWS} or @@ -361,5 +361,5 @@ If the overscan is not defined for each row/column, then the function shall generate a warning and then interpolate using the provided -functional form if \code{fit} is not \code{PS_OVERSCAN_FIT_NONE}; +functional form if \code{fit} is not \code{PS_FIT_NONE}; otherwise, the function shall generate an error. @@ -484,70 +484,57 @@ \subsection{Subtract sky} -Given an input image, a polynomial specifying the order of a desired -fit, a list of template background images, a list of catalog stars on -or near the chip, and parameters specifying how to grow the radius of -the objects, and the binning factor, \code{psPhase2SubtractSky} shall -fit and subtract the background of the image. The API shall be the -following: -\begin{verbatim} -/** Subtracts the sky background. */ +\tbd{This is a simply sky subtraction routine. A more complicated +routine will be specified in the future, following research into the +best algorithm.} + +Given an input image, a polynomial or spline specifying the order of a +desired fit, a binning factor and statistics to use for the binning, +along with a clipping level, \code{psPhase2SubtractSky} shall fit and +subtract a model for the background of the image. The API shall be +the following: +\begin{verbatim} +/** Simple sky subtraction */ psReadout *psPhase2SubtractSky(psReadout *in, ///< Input image to be sky-subtracted, and output - psPolynomial2D *poly, ///< Polynomial specification, returns coeffcients - psVector *outNorms, ///< Normalisations of the template sky images: output - const psList *skyImages, ///< Template sky images: a list of type psImage, or - ///< NULL - const psList *catalog, ///< Sources nearby to mask when measuring the - ///< background: a list of type psObject, or NULL - float radiusMultiply, ///< Multiplying factor of object radius for mask - float radiusAdd, ///< Additive factor to grow the object masks - int binFactor ///< Binning factor to use on image before solving for polynomial - ); -\end{verbatim} - -The polynomial specification, \code{poly}, specifies the order of the -polynomial to be used in fitting the background. Note that the input -image, \code{in}, shall be subtracted in-place. The function shall -return the subtracted image, and also update the polynomial, -\code{poly}, to hold the polynomial coefficients used in the -subtraction, and update the vector \code{outNorms} to hold the -normalisations of each of the template background images used in the -subtraction. The \code{outNorms} vector shall be resized if necessary -to match the number of template sky images in the list -\code{skyImages}. If the polynomial specification is \code{NULL}, then -no polynomial shall be fit to the input image. - -Note that the input image, \code{in}, and the template sky images, -\code{skyImages}, need not be the same size, since the input image may -already have been trimmed (following overscan subtraction), but the -function shall use the offsets in the image (\code{in->x0} and -\code{in->y0}) to determine the appropriate offsets to obtain the -correct pixels. In the event that one (or more) of the -\code{skyImages} is too small (i.e., pixels on the input image refer -to pixels outside the range of the \code{skyImages} image), the -function shall generate an error. - -The \code{catalog} shall be a linked list of \code{psObject} which -corresponds to objects on the input image. If the size of a source in -the \code{catalog} is \code{size}, then the radius to mask around the -source before fitting the background shall be \code{radiusMultiply} -$\times$ \code{size} + \code{radiusAdd}. - -\tbd{Are the catalog stars in celestial or pixel coordinates? I lean -to pixel coordinates.} - -\tbd{What size do we use? FWHM?} - -When fitting a polynomial, the function shall bin the input image by -\code{binFactor} in order to reduce the required processing time. - -\code{poly} may be \code{NULL} in order to specify that only the -template sky images should be used in the fitting, and no polynomial -terms. \code{outNorms} may be \code{NULL} if the caller is not -interested in the normalisations. \code{skyImages} may be \code{NULL} -in order to specify that there are no input sky template images. -\code{catalog} may be \code{NULL} in order to specify that there are -no objects to mask. If both \code{poly} and \code{skyImages} are -\code{NULL}, then the function shall simply return the input image -with no processing. + void *fitSpec, ///< Polynomial/Spline specification, returns coeffcients + psFit fit, ///< Fit type + int binFactor, ///< Binning factor to use on image before solving for polynomial + psStats *stats, ///< Statistics to use in binning + float clipSD ///< Standard deviations to clip at after binning. + ); +\end{verbatim} + +Note that the input image, \code{in}, shall be subtracted in-place. +The function shall return the subtracted image, and also update the +polynomial, chebyshev or spline specified by \code{fitSpec}, to hold +the coefficients used in the subtraction. + +The fit specification, \code{fitSpec}, specifies the order of the +polynomial or spline to be used in fitting the background. +\code{fitSpec} shall be interpreted as a polynomial, Chebyshev or +spline on the basis of \code{fit} (in the same manner as for bias +subtraction; \S\ref{sec:bias}). If \code{fitSpec} is \code{NULL} or +\code{fit} is \code{PS_FIT_NONE}, then no fit shall be performed, and +the function shall simply return. + +When fitting the polynomial, the function shall first bin the input +image by \code{binFactor} in order to reduce the required processing +time. The statistic to use in this binning is specified by +\code{stat}. \code{stat} is of type \code{psStats} instead of simply +\code{psStatsOptions} so that clipping levels may be specified, if +desired. In the event that multiple options are specified by +\code{stats}, a warning shall be generated, and the option with the +highest priority shall be used, according to the following priority +order: \code{PS_STAT_SAMPLE_MEAN}, \code{PS_STAT_SAMPLE_MEDIAN}, +\code{PS_STAT_CLIPPED_MEAN}, \code{PS_STAT_ROBUST_MEAN},\ +\code{PS_STAT_ROBUST_MEDIAN}, \code{PS_STAT_ROBUST_MODE}. If the +\code{binFactor} is non-positive, or \code{stats} is \code{NULL} or +fails to specify an option, a warning shall be generated, and the fit +shall be performed on the entire image. + +Binned pixels deviating more than \code{clipSD} standard deviations +from the mean of the binned pixels shall be clipped in a single +clipping iteration. If the \code{clipSD} is non-positive, then the +function shall generate a warning and not perform any clipping. + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%