Changeset 5937 for trunk/doc/modules/ModulesSDRS.tex

Timestamp:

Jan 6, 2006, 4:53:15 PM (20 years ago)

Author:

Paul Price

Message:

Reworking API for bias subtraction.

File:

• trunk/doc/modules/ModulesSDRS.tex (modified) (4 diffs)

trunk/doc/modules/ModulesSDRS.tex

@@ -1 @@
-%%% $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 +860 @@
 
 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 +876 @@
 
 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 +901 @@
 \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}
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%