Index: trunk/doc/modules/ModulesSDRS.tex =================================================================== --- trunk/doc/modules/ModulesSDRS.tex (revision 5709) +++ trunk/doc/modules/ModulesSDRS.tex (revision 5937) @@ -1,3 +1,3 @@ -%%% $Id: ModulesSDRS.tex,v 1.68 2005-12-06 19:48:26 eugene Exp $ +%%% $Id: ModulesSDRS.tex,v 1.69 2006-01-07 02:53:15 price Exp $ \documentclass[panstarrs,spec]{panstarrs} @@ -860,9 +860,9 @@ Given an input image and various other parameters, -\code{pmSubtractBias} shall subtract the bias from the image. -The API shall be the following: -\begin{prototype} -pmReadout *pmSubtractBias(pmReadout *in, void *fitSpec, pmFit fit, bool overscan, - const psStats *stat, int nBin, +\code{pmSubtractBias} shall subtract the bias from the image: + +\begin{prototype} +pmReadout *pmSubtractBias(pmReadout *in, pmOverscanOptions *overscanOpts, + psRegion imageRegion, psList *overscanRegions, const pmReadout *bias, const pmReadout *dark); \end{prototype} @@ -876,63 +876,12 @@ The input image, \code{in}, shall have the bias subtracted in-place. -The input image may be of type U16, S32, or F32. - -Overscan subtraction is controlled by the \code{overscan} boolean. If -it is \code{true}, then overscan subtraction is performed. The -prescan and/or overscan regions to be used are specified in by -\code{CELL.BIASSEC} (accessed via the parent of the \code{pmReadout}; -a linked list of \code{psRegion}s). These shall be reduced to a -single vector (in the dimension specified by \code{CELL.READDIR}, -which is accessed via the parent of the \code{pmReadout}). - -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{PM_FIT_NONE} (see below); -otherwise, the function shall generate an error. - -The statistic to use in combining multiple pixels in the -prescan/overscan regions 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 \code{nBin} is positive and less than the size of the vector, then -the vector shall subsequently be binned into \code{nBin} bins, using -the specified statistic (\code{stat}). For example, the whole -overscan region can be taken as a unity if \code{nBin=1}. If -\code{fit} is \code{PM_FIT_SPLINE}, then \code{nBin} also serves as -the number of spline pieces. - -\code{fit} is an enumerated type which specifies the type of fit to -employed on the overscan vector (and hence the type of \code{fitSpec}): -\begin{datatype} -typedef enum { - PM_FIT_NONE, ///< No fit - PM_FIT_POLYNOMIAL, ///< Fit polynomial - PM_FIT_SPLINE ///< Fit cubic splines -} pmFit; -\end{datatype} - -If \code{fit} is \code{PM_FIT_POLYNOMIAL} or \code{PM_FIT_SPLINE}, -then \code{fitSpec} shall be interpreted to be a structure of the -appropriate type (\code{psPolynomial1D} for \code{PM_FIT_POLYNOMIAL}, -and \code{psSpline1D} for \code{PM_FIT_SPLINE}), and the overscan -vector shall be fit using the specified functional form. - -In cases where \code{fitSpec} is \code{NULL} and \code{fit} is not -\code{PM_FIT_NONE} or \code{overscan} is \code{true}, the function -shall generate an error. If \code{overscan} is \code{false} and -\code{fit} is not \code{PM_FIT_NONE}, then the function shall generate -a warning, and no overscan subtraction shall be performed. Upon -return, the \code{fitSpec} shall contain the coefficients of the -overscan fit. - -If \code{fitSpec} is \code{NULL}, or \code{fit} is \code{PM_FIT_NONE}, -then no fit shall be performed to the overscan. +The input image may be of type U16, S32, or F32. The region of the +input image that shall have the overscan or full-frame subtractions +applied is specified by \code{imageRegion}. + +Overscan subtraction is performed if \code{overscanOpts} is +non-\code{NULL} (see \S\ref{sec:overscan}). \code{overscanRegions} +shall be a list of \code{psRegion}s that specify the regions that +comprise the overscans. A \code{bias} frame shall be subtracted pixel-by-pixel from the input @@ -952,4 +901,73 @@ \code{dark} shall also be masked in the output. The bias and dark images may be copied to the same type as the input image if required. + + +\subsubsection{Overscan subtraction} +\label{sec:overscan} + +The options for performing the overscan subtraction are bundled in a +\code{pmOverscanOptions}: + +\begin{datatype} +typedef struct { + // Inputs + bool single; // Reduce all overscan regions to a single value? + bool scanRows; // Scan direction was rows? (otherwise columns) + pmFit fitType; // Type of fit to overscan + unsigned int order; // Order of polynomial, or number of spline pieces + psStats *stat; // Statistic to use when reducing the minor direction + // Outputs + psPolynomial1D *poly; // Result of polynomial fit + psSpline1D *spline; // Result of spline fit +} pmOverscanOptions; +\end{datatype} + +The mode in which the overscan is subtracted is specified by the +\code{single} boolean. If \code{single} is \code{true}, then the +entire overscan region is reduced to a single value using the +\code{stat}. If \code{single} is \code{false}, the overscan shall be +reduced along the dimension specified by \code{scanRows} (rows if +\code{scanRows} is true; otherwise columns). + +If the overscan is not defined for each row/column, +\code{pmSubtractBias} shall generate an error if \code{fitType} is +\code{PM_FIT_NONE}; otherwise, the function shall shall generate a +warning and the undefined values shall be interpolated using the +provided functional form. + +The statistic to use in combining multiple pixels in the +prescan/overscan regions 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}. + +\code{fitType} is an enumerated type which specifies the type of fit +to employed on the overscan vector: +\begin{datatype} +typedef enum { + PM_FIT_NONE, ///< No fit + PM_FIT_POLY_ORD, ///< Fit ordinary polynomial + PM_FIT_POLY_CHEBY, ///< Fit Chebyshev polynomial + PM_FIT_SPLINE ///< Fit cubic splines +} pmFit; +\end{datatype} + +If \code{fitType} is \code{PM_FIT_NONE}, then the overscan vector is +subtracted from the image without fitting. Otherwise, the overscan +vector is fit using the specified functional form, the fit is +subtracted from the image, and the \code{poly} or \code{spline} is +allocated and updated with the results of the fit. + +The allocator for a \code{pmOverscanOptions} shall be: +\begin{prototype} +pmOverscanOptions *pmOverscanOptionsAlloc(bool single, bool scanRows, + pmFit fitType, unsigned int order, + psStats *stat); +\end{prototype} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%