IPP Software Navigation Tools IPP Links Communication Pan-STARRS Links

Changeset 1436


Ignore:
Timestamp:
Aug 9, 2004, 1:20:02 PM (22 years ago)
Author:
Paul Price
Message:

Moved a lot of stuff out to the PSLib SDRS (trim, convolution,
splines), cleaned up, renamed functions. Functions which aren't
in the next iteration have been moved to after the \end{document}.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/doc/modules/ModulesSDRS.tex

    r1145 r1436  
    1 %%% $Id: ModulesSDRS.tex,v 1.9 2004-06-30 10:08:52 price Exp $
     1%%% $Id: ModulesSDRS.tex,v 1.10 2004-08-09 23:20:02 price Exp $
    22\documentclass[panstarrs]{panstarrs}
    33
    44% basic document variables
    5 \title{Pan-STARRS IPP Phase 2}
     5\title{Pan-STARRS IPP Modules}
    66\subtitle{Supplementary Design Requirements}
    77\author{Paul Price}
    … …  
    5252
    5353This document describes the Pan-STARRS Image Processing Pipeline (IPP)
    54 Phase 2 image processing modules.  Phase 2 is the processing stage wherein
    55 the instrumental signatures are removed from the detector images, in
    56 preparation for the combination of multiple images in Phase 4.
    57 
    58 The Phase 2 processing \textit{stage} is composed of several
    59 \textit{modules} which perform the individual steps in the processing,
    60 each of which will act upon a data element of the appropriate size.
    61 For example, the bias subtraction module will act upon a detector
    62 ``readout'' (\code{psReadout}).  It will be the responsibility of the
    63 caller of the Phase 2 processing modules (i.e., the Phase 2 processing
    64 stage, which will likely be script written in a high-level language
    65 such as \tbd{Python}) to iterate over the components with which it is
    66 charged.
     54image processing modules.  The modules use the functionality \PS{}
     55Library (PSLib) perform more complex tasks.
     56
     57In order to preserve name space, globally-visible structures and
     58functions shall be prefixed with \code{pm}, for ``\PS{} Modules''.
     59
     60Modules will be constructed to support each of the processing stages.
     61
     62\section{Phase 2}
     63
     64Phase 2 is the processing stage wherein the instrumental signatures
     65are removed from the detector images, in preparation for the
     66combination of multiple images in Phase 4.
     67
     68The Phase 2 processing stage is composed of several modules which
     69perform the individual steps in the processing, each of which will act
     70upon a data element of the appropriate size.  For example, the bias
     71subtraction module will act upon a detector ``readout''
     72(\code{psReadout}).  It will be the responsibility of the caller of
     73the Phase 2 processing modules (i.e., the Phase 2 processing stage,
     74which will likely be a script written in a high-level language such as
     75\tbd{Python}) to iterate over the components with which it is charged.
    6776
    6877The Phase 2 processing modules are:
    6978\begin{itemize}
    70 \item Read in an FPA;
    71 \item Calculate the convolution kernel;
    72 \item Convolve an image with the kernel;
    7379\item Subtract bias;
    74 \item Trim an image;
    7580\item Correct for non-linearity;
    7681\item Flat-field;
    77 \item Subtract the background;
    7882\item Mask bad pixels;
     83\item \tbd{Subtract the background;}
    7984\item \tbd{Mask cosmic rays;}
    8085\item \tbd{Mask optical defects;}
    … …  
    8994some of which requires further research to define the best algorithm.
    9095
    91 These modules are built on top of, and are dependent upon, the \PS{}
    92 Library, PSLib.  Some functions are specified below which should be
    93 added to PSLib, since we anticipate that these will also find use in
    94 other modules.
    95 
    96 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    97 
    98 \section{Read in an image}
    99 
    100 Of course, before any image manipulation may occur, the image must be
    101 read in.  This involves populating the FPA with structures to
    102 represent the true focal plane.  However, different instruments have
    103 different focal planes, and the images are written to disk in
    104 different ways.  We have proposed a configuration file format which
    105 appears to be able to document the structure of a focal plane and
    106 specify how the IPP can read the required information from the FITS
    107 files \tbd{A REFERENCE GOES HERE}.
    108 
    109 Given an open \code{FILE} pointer to a configuration file,
    110 \code{config}, and the name of an FPA image, \code{fpaName},
    111 \code{psFPAGenerate} shall return a \code{psFPA} of the correct
    112 structure, with all the metadata entries read from the nominated FPA
    113 image.  Astrometric information shall be initialised to values
    114 specified by the configuration file.  The API shall be:
    115 
    116 \begin{verbatim}
    117 psFPA *psFPAGenerate(FILE *config, const char *fpaName);
    118 \end{verbatim}
    119 
    120 Once an FPA has been generated, the pixels may all be read in at once,
    121 or the pixels may be read in a chip, cell or readout at a time.  The
    122 corresponding APIs are:
    123 
    124 \begin{verbatim}
    125 psFPA *psFPAReadAll(psFPA *in);
    126 psFPA *psFPAReadChip(psFPA *in, const char *chipName);
    127 psChip *psChipReadCell(psChip *in, const char *cellName);
    128 psCell *psCellReadReadout(psCell *in, const char *readoutName);
    129 \end{verbatim}
    130 
    131 Note that reads of a cell or readout do not act upon an FPA, but
    132 rather a chip and a cell, respectively.  This saves the user from
    133 specifying the name of the FPA, chip, and cell just to get a readout,
    134 since this information is already stored in the generated \code{psFPA}
    135 struct.
    136 
    137 \tbd{How to write the output???}
    138 
    139 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    140 
    141 \section{Convolution}
    142 
    143 If images on the sky are obtained in Orthogonal Transfer (OT) mode,
    144 then the calibration frames used to correct them must be convolved by
    145 a kernel derived from the list of OT shifts made during the exposure.
    146 
    147 \subsection{Kernel definition}
    148 
    149 In order to perform a convolution, we need to define the convolution
    150 kernel.  We need a more general object than a \code{psImage} so that
    151 we can incorporate the offset from the $(0,0)$ pixel to the $(0,0)$
    152 value of the kernel\footnote{The kernel has both positive and negative
    153 indices to convey the positive and negative shifts.  One might
    154 consider setting the \code{x0} and \code{y0} members of a
    155 \code{psImage} to the appropriate offsets, but this is not the purpose
    156 of these members, and doing so may affect the behavior of other
    157 \code{psImage} operations.}.  Hence we define a \code{psKernel}:
    158 
    159 \begin{verbatim}
    160 /** A convolution kernel */
    161 typedef struct {
    162     int xMin, yMin;                     ///< Most negative indices
    163     int xMax, yMax;                     ///< Most positive indices
    164     float **kernel;                     ///< The kernel data
    165 } psKernel;
    166 \end{verbatim}
    167 
    168 The \code{kernel} shall contain the kernel values.  The kernel has
    169 both positive and negative indices to convey the positive and negative
    170 shifts.  The maximum extent of these shifts shall be defined by the
    171 \code{xMin}, \code{xMax}, \code{yMin} and \code{yMax} members.  Note
    172 that \code{xMin} and \code{yMin}, under normal circumstances, should
    173 be negative numbers.  That is, \code{myKernel->kernel[-3][-2]} may be
    174 defined if \code{yMin} and \code{xMin} are equal to or more negative
    175 than -3 and -2, respectively.
    176 
    177 Of course, we require the appropriate constructor and destructor:
    178 \begin{verbatim}
    179 psKernel *psKernelAlloc(int xMin, int xMax, int yMin, int yMax);
    180 void psKernelFree(psKernel *myKernel);
    181 \end{verbatim}
    182 
    183 \code{psKernelAlloc} shall allocate a kernel.  In the event that one
    184 of the minimum values is greater than the corresponding maximum value,
    185 the function shall generate a warning, and the offending values shall
    186 be exchanged.
    187 
    188 \subsection{Calculate the convolution kernel}
    189 
    190 Given a list of pixel shifts made in the course of OT guiding,
    191 \code{psPhase2GetKernel} shall return the appropriate kernel.  The API
    192 shall be the following:
    193 \begin{verbatim}
    194 psKernel *psPhase2GetKernel(const psVector *xShifts, const psVector *yShifts);
    195 \end{verbatim}
    196 
    197 The shift vectors, \code{xShifts} and \code{yShifts}, will be supplied
    198 by the user, most probably from the FITS file containing the image.
    199 
    200 The elements of the shift vectors should be of an integer type;
    201 otherwise the values shall be truncated to integers.  The output
    202 kernel shall be normalized such that the sum over the kernel is unity.
    203 
    204 The format of the shifts vectors will be a list of the net shift
    205 position relative to the starting point for each timestep.  In the
    206 normal course of \PS{} observations using orthogonal transfer, there
    207 will likely be about 10~Hz $\times$ 30~sec $=$ 300 timesteps.
    208 
    209 If the vectors are not of the same number of elements, then the
    210 function shall generate a warning shall be generated, following which,
    211 the longer vector trimmed to the length of the shorter, and the
    212 function shall continue.
    213 
    214 \subsection{Convolve an image with the kernel}
    215 
    216 Given an input image and the convolution kernel,
    217 \code{psPhase2ConvolveWithKernel} shall convolve the input image,
    218 \code{in}, with the kernel, \code{kernel} and return the convolved
    219 image, \code{out}.  The API shall be the following:
    220 \begin{verbatim}
    221 psImage *psImageConvolve(psImage *out, const psImage *in, const psKernel *kernel, bool direct);
    222 \end{verbatim}
    223 
    224 Two methods shall be available for the convolution: if \code{direct}
    225 is \code{true}, then the convolution shall be performed in real space
    226 (appropriate for small kernels); otherwise, the convolution shall be
    227 performed using Fast Fourier Transforms (FFTs; appropriate for larger
    228 kernels).
    229 
    230 In the event that \code{out} is \code{NULL}, a new \code{psImage}
    231 shall be allocated and returned.
    232 
    233 \subsection{PSLib Routines}
    234 
    235 \code{psKernel} and \code{psImageConvolve} shall be incorporated into
    236 the \PS{} Library, \code{PSLib}, so that they may be re-used for other
    237 modules.
    238 
    239 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    240 
    241 \section{Bias subtraction and trim}
    242 
    243 The following modules correct detector images for the electronic
    244 pedestal introduced by the readout electronics.
    245 
    246 \subsection{Image region specification}
    247 
    248 In order to specify regions on the detector image which may be used to
    249 determine the bias levels (i.e., a prescan or overscan region), we
    250 define the following structure:
    251 \begin{verbatim}
    252 /** Image regions */
    253 typedef struct {
    254     const int x0, y0;                   ///< Offset to region
    255     const int nX, nY;                   ///< Size of region
    256 } psImageRegion;
    257 \end{verbatim}
    258 
    259 A \code{psImageRegion} specifies the offset from $(0,0)$ on the
    260 detector\footnote{Note that an image may be smaller than the entire
    261 area of the detector if the detector is windowed, or if a subimage has
    262 been generated.} and the size of the region.
    263 
    264 We also require a corresponding constructor and destructor:
    265 \begin{verbatim}
    266 psImageRegion *psImageRegionAlloc(int x0, int y0, int nX, int nY);
    267 void psImageRegionFree(psImageRegion *reg);
    268 \end{verbatim}
    269 
    270 Multiple image regions may be specified using a linked list
    271 (\code{psList}) of \code{psImageRegion}s.
    272 
    273 \subsection{Splines}
    274 
    275 A spline is a popular choice for fitting 1D data, such as overscans,
    276 but we neglected to define them for PSLib.  We now define
    277 one-dimensional cubic splines, \code{psSpline1D}, which shall be
    278 incorporated into PSLib:
    279 
    280 \begin{verbatim}
    281 /** A 1D cubic-spline */
    282 typedef struct {
    283     int n;                              ///< Number of spline pieces
    284     float *coeff[4];                    ///< Coefficients.  There are 4 coefficients for each spline piece.
    285     float *coeffErr[4];                 ///< Errors in the coefficients.
    286     bool *mask[4];                      ///< Mask for the coefficients.
    287     float *domains;                     ///< The boundaries between each spline piece.  Size is n+1.
    288 } psSpline1D;
    289 \end{verbatim}
    290 
    291 The \code{psSpline1D} structure is very similar to that of the
    292 one-dimensional Chebyshev polynomial, \code{psPolynomial1D},
    293 except for the following:
    294 \begin{itemize}
    295 \item Each spline piece has 4 coefficients (with corresponding error
    296 and mask), corresponding to each of the zeroth through third order
    297 coefficients of a cubic; and
    298 \item It includes an additional member, \code{domains}, which
    299 specifies the boundaries between each spline piece (including the two
    300 ends).
    301 \end{itemize}
    302 
    303 Of course, we require the appropriate constructors and destructor:
    304 \begin{verbatim}
    305 psSpline1D *psSpline1DAlloc(int n, float min, float max);
    306 psSpline1D *psSpline1DAllocGeneric(const psVector *bounds);
    307 void psSpline1DFree(psSpline1D *mySpline);
    308 \end{verbatim}
    309 
    310 \code{psSpline1DAlloc} shall allocate and return a \code{psSpline1D},
    311 setting the \code{domains} on the basis of the input number of spline
    312 pieces, \code{n}, and the minimum (\code{min}) and maximum
    313 (\code{max}) data values.
    314 
    315 \code{psSpline1DAllocGeneric} shall allocate and return a
    316 \code{psSpline1D}, using the \code{bounds} to define the number of
    317 spline pieces and the \code{domains}.
    318 
    319 \code{psSpline1DFree} shall free the given spline, and its members.
    320 
    321 Also, as for the polynomials, we require an evaluator.  Given a
    322 \code{spline} and ordinate at which to evaluate, \code{x},
    323 \code{psSpline1DEval} shall evaluate and return the value of the
    324 spline at the ordinate.  If the ordinate is outside the bounds, then
    325 the function shall generate a warning, and extrapolate the spline to
    326 the ordinate and return the value.
    327 
    328 \begin{verbatim}
    329 float psSpline1DEval(const psSpline1D *spline, float x);
    330 \end{verbatim}
    331 
    332 
    33396\subsection{Bias subtraction}
    33497\label{sec:bias}
    33598
     99The bias subtraction module provides a facility to correct detector
     100images for the electronic pedestal introduced by the readout
     101electronics.
     102
    336103Given an input image and various other parameters,
    337 \code{psPhase2SubtractBias} shall subtract the bias from the image.
     104\code{pmSubtractBias} shall subtract the bias from the image.
    338105The API shall be the following:
    339106\begin{verbatim}
    340 psReadout *psPhase2SubtractBias(psReadout *in, void *fitSpec, psOverscanAxis overscanAxis, psFit fit,
    341                                 int nBin, const psList *regions, const psStats *stat, const psImage *bias);
     107psReadout *pmSubtractBias(psReadout *in, void *fitSpec, const psList *overscans,
     108                          pmOverscanAxis overscanAxis, const psStats *stat,
     109                          int nBin, psFit fit, const psReadout *bias);
    342110\end{verbatim}
    343111
    344112The input image, \code{in}, shall have the bias subtracted in-place.
    345113
    346 The type of the overscan fit specification, \code{fitSpec}, shall be
     114The type of the overscan fit function, \code{fitSpec}, shall be
    347115dependent upon the value of \code{fit}, which specifies the type of
    348116fit to be employed.  \code{fit} is an enumerated type:
    349117
    350118\begin{verbatim}
    351 /** Fit type */
     119/** Fit types */
    352120typedef enum {
    353     PS_FIT_NONE,                ///< No fit
    354     PS_FIT_LINEAR,              ///< Do linear interpolation
    355     PS_FIT_POLYNOMIAL,          ///< Fit polynomial
    356     PS_FIT_CHEBYSHEV,           ///< Fit chebyshev
    357     PS_FIT_SPLINE               ///< Fit cubic splines
    358 } psFit;
    359 \end{verbatim}
    360 
    361 If \code{fitSpec} is \code{NULL}, or \code{fit} is \code{PS_FIT_NONE},
    362 then no fit shall be performed to the overscan.  If \code{fit} is
    363 \code{PS_FIT_LINEAR}, then the function shall perform simple linear
    364 interpolation between points in the overscan.  Otherwise,
     121    PM_FIT_NONE,                        ///< No fit
     122    PM_FIT_POLYNOMIAL,                  ///< Fit polynomial
     123    PM_FIT_SPLINE                       ///< Fit cubic splines
     124} pmFit;
     125\end{verbatim}
     126
     127If \code{fitSpec} is \code{NULL}, or \code{fit} is \code{PM_FIT_NONE},
     128then no fit shall be performed to the overscan.  Otherwise,
    365129\code{fitSpec} shall be interpreted to be a structure of the
    366 appropriate type (\code{psPolynomial1D} for \code{PS_FIT_POLYNOMIAL}
    367 and \code{PS_FIT_CHEBYSHEV}, and \code{psSpline1D} for
    368 \code{PS_FIT_SPLINE}), and the overscan shall be fit using the
    369 specified functional form.  Upon return, the \code{fitSpec} shall
    370 contain the coefficients of the overscan fit.
     130appropriate type (\code{psPolynomial1D} for \code{PM_FIT_POLYNOMIAL},
     131and \code{psSpline1D} for \code{PM_FIT_SPLINE}), and the overscan
     132shall be fit using the specified functional form.  Upon return, the
     133\code{fitSpec} shall contain the coefficients of the overscan fit.
     134
     135The prescan and/or overscan regions to be used are specified in
     136\code{overscans}, which is a linked list of subimages.  If
     137\code{overscans} is non-\code{NULL} and \code{overscanAxis} is not
     138\code{PM_OVERSCAN_NONE}, then the function shall generate a warning.
    371139
    372140The \code{overscanAxis} specifies how the prescan/overscan subtraction
    … …  
    375143/** Overscan axis */
    376144typedef enum {
    377     PS_OVERSCAN_NONE,                   ///< No overscan subtraction
    378     PS_OVERSCAN_ROWS,                   ///< Subtract rows
    379     PS_OVERSCAN_COLUMNS,                ///< Subtract columns
    380     PS_OVERSCAN_ALL                     ///< Subtract the statistic of all pixels in overscan region
    381 } psOverscanAxis;
    382 \end{verbatim}
    383 
    384 If the \code{overscanAxis} is \code{PS_OVERSCAN_NONE}, then the
     145    PM_OVERSCAN_NONE,                   ///< No overscan subtraction
     146    PM_OVERSCAN_ROWS,                   ///< Subtract rows
     147    PM_OVERSCAN_COLUMNS,                ///< Subtract columns
     148    PM_OVERSCAN_ALL                     ///< Subtract the statistic of all pixels in overscan region
     149} pmOverscanAxis;
     150\end{verbatim}
     151
     152If the \code{overscanAxis} is \code{PM_OVERSCAN_NONE}, then the
    385153function shall not perform any overscan subtraction.  If the
    386 \code{overscanAxis} is \code{PS_OVERSCAN_ALL}, then all the overscan
     154\code{overscanAxis} is \code{PM_OVERSCAN_ALL}, then all the overscan
    387155regions shall be used to generate a single statistic (specified by
    388156\code{stat}) which shall be subtracted from the entire image.  A
    389157warning shall be generated if the \code{overscanAxis} is
    390 \code{PS_OVERSCAN_NONE} or \code{PS_OVERSCAN_ALL} and the \code{fit}
    391 is not \code{PS_FIT_NONE}.
    392 
    393 If the \code{overscanAxis} is \code{PS_OVERSCAN_ROWS} or
    394 \code{PS_OVERSCAN_COLUMNS}, then the overscan shall be reduced to a
    395 single vector in the dimension specified using the specified statistic
    396 (\code{stat}).  If \code{nBin} is positive and less than the dimension
    397 of the vector, then the vector shall subsequently be binned down into
    398 \code{nBin} bins, again using the specified statistic (\code{stat}).
    399 If the overscan is not defined for each row/column, then the function
    400 shall generate a warning and then interpolate using the provided
    401 functional form if \code{fit} is not \code{PS_FIT_NONE};
    402 otherwise, the function shall generate an error.
    403 
    404 The prescan and/or overscan regions to be used are specified in
    405 \code{regions}, which is a linked list of \code{psImageRegion}s.  If
    406 \code{regions} is non-\code{NULL} and \code{overscanAxis} is not
    407 \code{PS_OVERSCAN_NONE}, then the function shall generate a warning.
     158\code{PM_OVERSCAN_NONE} or \code{PM_OVERSCAN_ALL} and the \code{fit}
     159is not \code{PM_FIT_NONE}.
     160
     161If the \code{overscanAxis} is \code{PM_OVERSCAN_ROWS} or
     162\code{PM_OVERSCAN_COLUMNS}, then the overscan shall be reduced to a
     163single vector (in the specified dimension) using the specified
     164statistic (\code{stat}).
    408165
    409166The statistic to use in combining multiple pixels in the
    … …  
    418175\code{PS_STAT_ROBUST_MODE}.
    419176
     177If \code{nBin} is positive and less than the dimension
     178of the vector, then the vector shall subsequently be binned down into
     179\code{nBin} bins, again using the specified statistic (\code{stat}).
     180If the overscan is not defined for each row/column, then the function
     181shall generate a warning and then interpolate using the provided
     182functional form if \code{fit} is not \code{PM_FIT_NONE};
     183otherwise, the function shall generate an error.
     184
     185Following any binning, the vector shall be fit by the functional form
     186specified by \code{fit} (see above).  Then the overscan shall be
     187subtracted from the image, using values from the fit if \code{fit} is
     188not \code{PM_FIT_NONE}; otherwise using values from the overscan vector
     189if \code{overscanAxis} is not \code{PM_OVERSCAN_ALL}; otherwise using
     190the appropriate statistic applied to all the prescan/overscan pixels.
     191
    420192A bias (or dark) image shall be subtracted pixel-by-pixel from the
    421193input image if \code{bias} is non-NULL.  Note that the input image,
    … …  
    426198image is too small (i.e., pixels on the input image refer to pixels
    427199outside the range of the \code{bias} image), the function shall
    428 generate an error.
    429 
    430 
    431 \subsection{Trim}
    432 
    433 Given an input image and region to keep, \code{psPhase2Trim} shall
    434 trim the input image, \code{in}, leaving only the specified region,
    435 \code{region}.  The API shall be the following:
    436 \begin{verbatim}
    437 psReadout *psPhase2Trim(psReadout *in, const psImageRegion *region);
    438 \end{verbatim}
    439 
    440 Note that the trim shall be performed on the input image in-place, so
    441 that the input image is modified.
    442 
    443 The offset of the input image (\code{in->x0} and \code{in->y0}) shall
    444 be updated to reflect the trim.
    445 
    446 The function shall generate an error if the \code{region} is outside
    447 the bounds of the input image.
    448 
    449 \subsection{PSLib}
    450 
    451 The \code{psSpline1D} and \code{psFit} shall be incorporated into
    452 PSLib.
    453 
    454 
    455 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    456 
    457 \section{Preparation for photometry}
    458 
    459 The following modules take an image and process it so that counts are
    460 proportional to the flux from an astronomical source.
     200generate an error.  Any pixels masked in the \code{bias} shall also be
     201masked in the output.
     202
     203%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    461204
    462205\subsection{Non-linearity}
    … …  
    466209the correction.
    467210
    468 The first, \code{psPhase2NonLinearityPolynomial} shall correct the
    469 input image for non-linearity by applying the given polynomial,
     211The first, \code{pmNonLinearityPolynomial} shall correct the input
     212image for non-linearity by applying the given polynomial,
    470213\code{coeff}, to the flux of each pixel in the input image, \code{in}.
    471214The API shall be the following:
    472215
    473216\begin{verbatim}
    474 /** Applies the correction for detector non-linearity. */
    475 psReadout *psPhase2CorrectNonLinearity(psReadout *in, const psPolynomial1D *coeff);
     217psReadout *pmNonLinearityPolynomial(psReadout *in, const psPolynomial1D *coeff);
    476218\end{verbatim}
    477219
    … …  
    479221caller, likely from the image metadata.
    480222
    481 The second function, \code{psPhase2NonLinearityLookup} shall correct
     223The second function, \code{pmNonLinearityLookup} shall correct
    482224the input image for non-linearity by using a lookup table.  The API
    483225shall be the following:
    484226
    485227\begin{verbatim}
    486 psReadout *psPhase2NonLinearityLookup(psReadout *in, const psVector *inFlux, const psVector *outFlux);
     228psReadout *pmNonLinearityLookup(psReadout *in, const psVector *inFlux, const psVector *outFlux);
    487229\end{verbatim}
    488230
    … …  
    495237to be pre-sorted.
    496238
    497 Both \code{psPhase2NonLinearityPolynomial} and
    498 \code{psPhase2NonLinearityLookup} shall modify the input image
    499 in-place.
     239If the particular value of a pixel is not found in the \code{inFlux}
     240vector, the corresponding \code{outFlux} shall be calculated through
     241linear interpolation.
     242
     243In the event that the \code{inFlux} vector does not contain two or
     244more entries (necessary for linear interpolation), then the function
     245shall generate a warning, and make no correction to any of the pixels.
     246
     247Both \code{pmNonLinearityPolynomial} and \code{pmNonLinearityLookup}
     248shall modify the input image in-place.
    500249
    501250\subsection{Flat-fielding}
    502251
    503 Given an input image and a flat-field image, \code{psPhase2FlatField}
     252Given an input image and a flat-field image, \code{pmFlatField}
    504253shall divide the input image by the flat-field image.  The API shall
    505254be the following:
    506255\begin{verbatim}
    507 psReadout *psPhase2FlatField(psReadout *in, const psImage *flat);
     256psReadout *pmFlatField(psReadout *in, const psReadout *flat);
    508257\end{verbatim}
    509258
    … …  
    519268
    520269Pixels which are negative or zero in the \code{flat} shall be masked
    521 in the input image with the value \code{PS_MASK_FLAT} (see
    522 \S\ref{sec:maskValues}).
     270in the input image with the value \code{PM_MASK_FLAT} (see
     271\S\ref{sec:maskValues}).  Negative pixels in the \code{flat} may be
     272set to zero so that they are treated identically to zeroes.  And
     273pixels masked in the \code{flat} shall be masked in the \code{output}.
    523274
    524275The function shall not normalize the \code{flat}; this responsibility
    525276is left to the caller.  This function is basically equivalent to a
    526 divide, but with care for the region that is divided.
     277divide (with \code{psImageOp}), but with care for the region that is
     278divided, checking for negative pixels, and copying of the mask from
     279the \code{flat} to the output.
     280
     281%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     282
     283\subsection{Masking}
     284
     285The following modules mask various defects on an image.
     286
     287\subsubsection{Mask values}
     288\label{sec:maskValues}
     289
     290We define several mask values for use in the phase 2 processing:
     291\begin{verbatim}
     292/** Mask values */
     293typedef enum {
     294    PM_MASK_TRAP,                       ///< The pixel is a charge trap
     295    PM_MASK_BADCOL,                     ///< The pixel is a bad column
     296    PM_MASK_SAT,                        ///< The pixel is saturated
     297    PM_MASK_FLAT,                       ///< The pixel is non-positive in the flat-field
     298    PM_MASK_CR_MORPH                    ///< The pixel is determined to be a cosmic ray, from morphology
     299} pmMaskValue;
     300\end{verbatim}
     301
     302Of these, masks for the charge traps need to be grown by the extent of
     303the OT convolution kernel.  For other pixel types, orthogonal transfer
     304of the flux in this pixel will not (necessarily) affect the flux in
     305neighbouring pixels.
     306
     307\subsubsection{Bad pixels}
     308
     309Given an input image, \code{in}, a bad pixel \code{mask}, a
     310corresponding value in the bad pixel mask to mask in the input image,
     311\code{maskVal}, a saturation level, and a growing radius,
     312\code{pmMaskBadPixels} shall mask in the input image those
     313pixels in the bad pixel mask that match the value to mask.  The API
     314shall be the following:
     315\begin{verbatim}
     316psReadout *pmMaskBadPixels(psReadout *in, const psImage *mask, int maskVal, float sat, int grow);
     317\end{verbatim}
     318
     319Note that the input image, \code{in}, is modified in-place.  All
     320pixels in the \code{mask} which satisfy the \code{maskVal} shall have
     321their corresponding pixels in the input image, \code{in}, along with
     322all pixels within the \code{grow} radius masked.  Pixels which have
     323flux greater than \code{sat} shall also be masked, but not grown.
     324
     325Note that the input image, \code{in}, and the \code{mask} need not be
     326the same size, since the input image may already have been trimmed
     327(following overscan subtraction), but the function shall use the
     328offsets in the image (\code{in->x0} and \code{in->y0}) to determine
     329the appropriate offsets to obtain the correct pixel on the mask.  In
     330the event that the \code{mask} image is too small (i.e., pixels on the
     331input image refer to pixels outside the range of the \code{mask}
     332image), the function shall generate an error.
     333
     334%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     335\bibliographystyle{plain}
     336\bibliography{panstarrs}
     337
     338\end{document}
     339
     340
     341
     342
    527343
    528344\subsection{Subtract sky}
    … …  
    577393
    578394
    579 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    580 
    581 \section{Masking}
    582 
    583 The following modules mask various defects on an image.
    584 
    585 \subsection{Mask values}
    586 \label{sec:maskValues}
    587 
    588 We define several mask values for use in the phase 2 processing:
    589 \begin{verbatim}
    590 /** Mask values */
    591 typedef enum {
    592     PS_MASK_TRAP,                       ///< The pixel is a charge trap
    593     PS_MASK_BADCOL,                     ///< The pixel is a bad column
    594     PS_MASK_SAT,                        ///< The pixel is saturated
    595     PS_MASK_FLAT,                       ///< The pixel is non-positive in the flat-field
    596     PS_MASK_CR_MORPH                    ///< The pixel is determined to be a cosmic ray, from morphology
    597 } psMaskValue;
    598 \end{verbatim}
    599 
    600 Of these, masks for the charge traps need to be grown by the
    601 extent of the OT convolution kernel.  For other pixel types,
    602 orthogonal transfer of the flux in this pixel will not (necessarily)
    603 affect the flux in neighbouring pixels
    604 
    605 \subsection{Bad pixels}
    606 
    607 Given an input image, \code{in}, a bad pixel \code{mask}, a
    608 corresponding value in the bad pixel mask to mask in the input image,
    609 \code{maskVal}, a saturation level, and a growing radius,
    610 \code{psPhase2MaskBadPixels} shall mask in the input image those
    611 pixels in the bad pixel mask that match the value to mask.  The API
    612 shall be the following:
    613 \begin{verbatim}
    614 psReadout *psPhase2MaskBadPixels(psReadout *in, const psImage *mask, int maskVal, float sat, int grow);
    615 \end{verbatim}
    616 
    617 Note that the input image, \code{in}, is modified in-place.  All
    618 pixels in the \code{mask} which satisfy the \code{maskVal} shall have
    619 their corresponding pixels in the input image, \code{in}, along with
    620 all pixels within the \code{grow} radius masked.  Pixels which have
    621 flux greater than \code{sat} shall also be masked, but not grown.
    622 
    623 
    624 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    625 
    626 
    627 
    628 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    629 \bibliographystyle{plain}
    630 \bibliography{panstarrs}
    631 
    632 \end{document}
    633 
    634395\subsection{Cosmic rays}
    635396
    … …  
    776537not all of which may correspond to legal positions on the input chip,
    777538\code{in}.
     539
     540
     541%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     542
     543\section{Read in an FPA}
     544
     545\TBD{This section on reading in an FPA is all TBD and should not be
     546implemented yet.}
     547
     548Of course, before any image manipulation may occur, the image must be
     549read in.  This involves populating the FPA with structures to
     550represent the true focal plane.  However, different instruments have
     551different focal planes, and the images are written to disk in
     552different ways.  We have proposed a configuration file format which
     553appears to be able to document the structure of a focal plane and
     554specify how the IPP can read the required information from the FITS
     555files \tbd{REFERENCE}.
     556
     557Given an open \code{FILE} pointer to a configuration file,
     558\code{config}, and the name of an FPA image, \code{fpaName},
     559\code{psFPAGenerate} shall return a \code{psFPA} of the correct
     560structure, with all the metadata entries read from the nominated FPA
     561image.  Astrometric information shall be initialised to values
     562specified by the configuration file.  The API shall be:
     563
     564\begin{verbatim}
     565psFPA *psFPAGenerate(FILE *config, const char *fpaName);
     566\end{verbatim}
     567
     568Once an FPA has been generated, the pixels may all be read in at once,
     569or the pixels may be read in a chip, cell or readout at a time.  The
     570corresponding APIs are:
     571
     572\begin{verbatim}
     573psFPA *psFPAReadAll(psFPA *in);
     574psFPA *psFPAReadChip(psFPA *in, const char *chipName);
     575psChip *psChipReadCell(psChip *in, const char *cellName);
     576psCell *psCellReadReadout(psCell *in, const char *readoutName);
     577\end{verbatim}
     578
     579Note that reads of a cell or readout do not act upon an FPA, but
     580rather a chip and a cell, respectively.  This saves the user from
     581specifying the name of the FPA, chip, and cell just to get a readout,
     582since this information is already stored in the generated \code{psFPA}
     583struct.
     584
     585\tbd{Writing the output}
     586
     587%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     588
Note: See TracChangeset for help on using the changeset viewer.