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

Timestamp:

Jan 15, 2006, 2:26:17 PM (20 years ago)

Author:

eugene

Message:

fleshing out psphot APIs

File:

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

trunk/doc/modules/ModulesSDRS.tex

@@ -1 @@
-%%% $Id: ModulesSDRS.tex,v 1.69 2006-01-07 02:53:15 price Exp $
+%%% $Id: ModulesSDRS.tex,v 1.70 2006-01-16 00:26:17 eugene Exp $
 \documentclass[panstarrs,spec]{panstarrs}
 
@@ -53 +53 @@
 
 \tableofcontents
+\pagebreak 
+
+\listoffigures
 \pagebreak 
 \pagenumbering{arabic}
@@ -1632 +1635 @@
 \subsection{Structures to Describe Sources}
 
-\subsubsection{pmSource and pmPeak}
-
-We start by defining a single source detected in a single band:
-\begin{datatype}
-typedef struct {
-  pmPeak *peak;            // description of peak pixel
-  psImage *pixels;         // rectangular region including object pixels
-  psImage *mask;           // mask to mark pixels associated with object in region
-  pmMoments *moments;      // basic moments measure for the object
-  pmModel *modelPSF;       // PSF model parameters and type
-  pmModel *modelFLT;       // FLT model parameters and type
-  pmSourceType type;       // best identification of object
-} pmSource;
-\end{datatype}
-
 In the object analysis process, we will use specific mask values to
 mark the image pixels.  The following structure defines the relevant
 mask values.
 \begin{datatype}
-enum {
+typedef enum {
     PSPHOT_MASK_CLEAR     = 0x00,
     PSPHOT_MASK_INVALID   = 0x01,
@@ -1657 +1645 @@
     PSPHOT_MASK_MARKED    = 0x08,
 } psphotMaskValues;
+\end{datatype}
+
+\subsubsection{pmSource and pmPeak}
+
+We define the following structure to represent a single source
+detected in a single image.  
+\begin{datatype}
+typedef struct {
+  pmPeak *peak;            // description of peak pixel
+  psImage *pixels;         // rectangular region including object pixels
+  psImage *weight;         // Image variance.
+  psImage *mask;           // Mask which marks pixels associated with objects.
+  pmMoments *moments;      // basic moments measure for the object
+  pmModel *modelPSF;       // PSF model parameters and type
+  pmModel *modelEXT;       // FLT model parameters and type
+  pmSourceType type;       // Best identification of object
+  pmSourceMode mode;       // flags describing the model quality 
+  psArray *blends;         // array of other sources blended with this source
+  float apMag;             // measured aperture magnitude for source
+  float fitMag;            // measured model magnitude for source
+  psRegion region;         // area on image covered by selected pixels
+} pmSource;
 \end{datatype}
 
@@ -1684 +1694 @@
   PM_PEAK_EDGE,             // peak on edge
   PM_PEAK_FLAT              // peak has equal-value neighbors
+  PM_PEAK_UNDEF             // Undefined.
 } pmPeakType; 
 \end{datatype}
@@ -1689 +1700 @@
 \subsubsection{pmMoments and source description}
 
-The pixels which contain the source may be specified with the
-\code{psImage *pixels} element, and the mask image may be used to
-exclude any pixels which are not considered part of the source.  Note
-that the source image may be simply a subimage of the main image or a
-separate copy if the pixels are modified (eg, by subtracting flux from
-other sources, etc).
+The pixels which contain the source are specified with the
+\code{psImage *pixels} element, a subimage of the image being
+analysed.  Similarly, the \code{mask} element is a subimage of the
+corresponding mask image and the \code{weight} element is a subimage
+of the corresponding weight image (image varience).  Since these are
+subimages, a collection of many objects may include overlapping
+pixels; care must be taken that pixel manipulations for one source do
+not unintentionally interfere with the other source pixels.  The
+\code{mask} may be used to exclude any pixels which are not considered
+part of the source.  Along with these pixel structures, we include the
+\code{psRegion region} element which defines the boundaries of the
+current associated subimages. 
 
 One of the simplest measurements which can be made quickly for an
@@ -1732 +1749 @@
 A given source may be identified as most-likely to be one of several
 source types.  The \code{pmSource} entry \code{pmSourceType} defines
-the current best-guess for this source.  \tbd{The values given below
-are currently illustrative and will require some modification as the
-source classification code is developed.}
+the current best-guess for this source.  
 
 \begin{datatype}
 typedef enum {
-    PM_SOURCE_DEFECT,              // a cosmic-ray
-    PM_SOURCE_SATURATED,           // random saturated pixels
-
-    PM_SOURCE_SATSTAR,             // a saturated star
-    PM_SOURCE_PSFSTAR,             // a PSF star
-    PM_SOURCE_GOODSTAR,            // a good-quality star
-
-    PM_SOURCE_POOR_FIT_PSF,        // poor quality PSF fit
-    PM_SOURCE_FAIL_FIT_PSF,        // failed to get a good PSF fit
-    PM_SOURCE_FAINTSTAR,           // below S/N cutoff
-
-    PM_SOURCE_GALAXY,              // an extended object (galaxy)
-    PM_SOURCE_FAINT_GALAXY,        // a galaxy below S/N cutoff
-    PM_SOURCE_DROP_GALAXY,         // ?
-    PM_SOURCE_FAIL_FIT_GAL,        // failed on the galaxy fit
-    PM_SOURCE_POOR_FIT_GAL,        // poor quality galaxy fit
-
-    PM_SOURCE_OTHER                // unidentified
-} pmSourceType; 
+    PM_SOURCE_UNKNOWN,                  ///< no guess yet made
+    PM_SOURCE_DEFECT,                   ///< a cosmic-ray
+    PM_SOURCE_SATURATED,                ///< random saturated pixels
+    PM_SOURCE_STAR,                     ///< a good-quality star
+    PM_SOURCE_EXTENDED,                 ///< an extended object (eg, galaxy)
+} pmSourceType;
+\end{datatype}
+
+The related element, \code{pmSourceMode mode}, holds a collection of flags which
+are used to indicate the status of the analysis for a source.  These
+are defined below:
+\begin{datatype} 
+typedef enum {
+    PM_SOURCE_DEFAULT    = 0x0000, ///< no flags are set
+    PM_SOURCE_PSFMODEL   = 0x0001, ///< flags refer to the PSF model
+    PM_SOURCE_EXTMODEL   = 0x0002, ///< flags refer to the EXT model
+    PM_SOURCE_SUBTRACTED = 0x0004, ///< the model has been subtracted from the image
+    PM_SOURCE_FITTED     = 0x0008, ///< the source has been fitted with a model
+    PM_SOURCE_FAIL       = 0x0010, ///< the model fit failed
+    PM_SOURCE_POOR       = 0x0020, ///< the model fit was poor (low S/N, etc)
+    PM_SOURCE_PAIR       = 0x0040, ///< the model fit is one of a paired source
+    PM_SOURCE_PSFSTAR    = 0x0080, ///< the source was used to construct the image PSF model
+    PM_SOURCE_SATSTAR    = 0x0100, ///< the source is saturated
+    PM_SOURCE_BLEND      = 0x0200, ///< the source is a blend with another source
+    PM_SOURCE_LINEAR     = 0x0400, ///< the source was fitted with the linear PSF model
+    PM_SOURCE_TEMPSUB    = 0x0800, ///< the source has been subtracted, but should be replaced
+} pmSourceMode;
 \end{datatype}
 
@@ -1777 +1800 @@
 \end{itemize}
 
-Every source may have two types of models: a PSF model and a FLT
-(floating) model.  The PSF model represents the best fit of the image
-PSF to the specific object.  In this case, the PSF-dependent
-parameters are specified for the object by the PSF, not by the fit.
-The FLT model represents the best fit of the given model to the
-object, with all parameters floating in the fit.  
-
+\tbd{should be include utility pointers to these parameters so that
+  functions do not need to know the parameter sequence?}
+
+The structure which carries the information about a given source model
+is defined below:
 \begin{datatype}
 typedef struct {
@@ -1792 +1813 @@
   psS32 nDOF;               // number of degrees of freedom
   psS32 nIter;              // number of iterations
+  pmModelStatus status;     // fit status
   float radius;             // fit radius actually used
 } pmModel;
 \end{datatype}
+
+The \code{status} element carries the resulting success/failure status
+of an attempt to fit the model to the source:
+\begin{datatype}
+typedef enum {
+    PM_MODEL_UNTRIED,               ///< model fit not yet attempted
+    PM_MODEL_SUCCESS,               ///< model fit succeeded
+    PM_MODEL_NONCONVERGE,           ///< model fit did not converge
+    PM_MODEL_OFFIMAGE,              ///< model fit drove out of range
+    PM_MODEL_BADARGS                ///< model fit called with invalid args
+} pmModelStatus;
+\end{datatype}
+
+We distinguish several ways in which an analytical model may be
+applied to a source.  The PSF model represents the best fit of the
+image PSF to the specific object.  In this case, the PSF-dependent
+parameters are specified for the object by the PSF, not by the fit.
+The EXT model represents the best fit of the given model to the
+object, with all parameters floating in the fit.  Such a model would
+typically be used to represent and extended object, hence the
+abbreviation EXT.  In some circumstances, a source may be fitted with
+a PSF model in which the position is held fixed, and not allowed to
+vary in the model fitting process.  We identify such a model as FIX.
+Finally, we allow for the case in which two nearly-merged PSFs are
+fitted with a single 2-PSF model.  We identify such a model as DBL.
+The \code{pmSource} structure contains a pointer to both a PSF and an
+EXT model, allowing any source to carry information about both
+possible fitting modes \tbd{not clear that we actually use this
+information; we might be better off simply distinguishing with one of
+the pmSourceMode flags}.  The value of the model at a specific
+coordinate can be determined by calling the function:
+\begin{prototype}
+psF32 pmModelEval(pmModel *model, psImage *image, psS32 col, psS32 row);
+\end{prototype}
+For this function, the values of \code{col,row} are in the
+\code{image} coordinates, which may be a subimage, while the reference
+coordinate for the model is in the parent image coordinates.
+
+In the \code{pmSource} structure, the elements \code{apMag} and
+\code{fitMag} are used to carry the measured magnitude of the source
+determined either from aperture photometry or from the integral of the
+fitted model function.  The element \code{blends} is used to carry
+pointers to the collection of sources which were found to be blended
+with this source.  Only the primary source of a blend group carries
+this information (see Section~\ref{blends}).
 
 Every model instance belongs to a class of models, defined by the
@@ -1893 +1960 @@
 should be used to transfer models between programs or systems.
 
+\subsubsection{pmGrowthCurve}
+
+When the photometry of source is measured in a fixed aperture, there
+is always a fraction of the source light which falls outside of the
+aperture.  The resulting aperture magnitude is thus larger (ie,
+fainter) than the actual source.  As the aperture is increased, the
+amount of loss decreases and the measured magnitude increases.  This
+trend is the curve of growth for the source.  We use the following
+structure to carry information about the curve of growth.  We use the
+PSF model to measure the curve of growth for an image.  
+
+\begin{datatype}
+typedef struct {
+    psVector *radius;
+    psVector *apMag;
+    psF32 refRadius;
+    psF32 maxRadius;
+    psF32 fitMag;
+    psF32 apRef;   // apMag[refRadius]
+    psF32 apLoss;  // fitMag - apRef
+} pmGrowthCurve;
+\end{datatype}
+In this structure, \code{radius} is a monotonically increasing
+sequence of radius values (in pixels).  The \code{apMag} vector
+contains the measured magnitude at any of these radius: this is the
+curve-of-growth trend.  The remaining entries summaries the
+relationship: \code{refRadius} is the global reference radius used for
+this image; \code{maxRadius} is the outermost radius at which the
+curve of growth was measured; \code{fitMag} is the fitted PSF model
+magnitude integrated to infinity; \code{apRef} is the aperture
+magnitude at the reference radius; \code{apLoss} is the difference
+between the aperture magnitude at the reference radius and the fitted
+model magnitude.  A few related functions are specified to interact
+with the curve of growth:
+
+\begin{prototype}
+pmGrowthCurve *pmGrowthCurveAlloc (psF32 minRadius, psF32 maxRadius, psF32 dRadius);
+\end{prototype}
+This function allocates a \code{pmGrowthCurve} structure and fills in
+the \code{radius} vector (see psLib SDRS \code{psVectorCreate}).  It
+does {\em not} allocate the \code{apMag} vector.
+
+\begin{prototype}
+psF32 pmGrowthCurveCorrect (pmGrowthCurve *growth, psF32 radius);
+\end{prototype}
+This function accepts a \code{growth} curve structure and returns the
+correction between the specified radius and the reference radius
+($apMag(refRadius) - apMag(radius)$).
+
+The following two functions are used to search the growth curve to the
+corresponding radius entry:
+\begin{prototype}
+int psVectorBracket (psVector *index, psF32 key, bool above);
+psF32 psVectorInterpolate (psVector *index, psVector *value, psF32 key);
+\end{prototype}
+
+\subsubsection{Aperture Trends}
+
+With PSF model fitting, there is always some discrepancy between the
+model of the PSF and the actual PSF.  As a result, the measured flux
+from the model will not represent exactly the flux of the source.  It
+is necessary to measure the correction between the model and the
+actual source flux.  One way to perform this measurement is to compare
+the model flux with the flux measured for bright stars within a fixed
+aperture.  The quantity to be measured is $dA = m_{\rm aperture} -
+m_{\rm fit}$.  In practice, $dA$ exhibits variations as a function of
+the source position ($x,y$) and the source flux.  The variations as a
+function of source position can be understood as a change in the PSF
+model error as a function of position due to the changing shape of the
+PSF (despite the varying PSF model, it is possible that the fitted
+model yields positional variations in the residual flux).  The
+variations in $dA$ as a function of magnitude can be understood as the
+result of a bias in the local background measurement (for the fainter
+sources) and as a result of non-linearity in the detector setting on
+the bright end.  We use a 4D polynomial to represent these trends.
+The first two dimensions of the polynomial represent the variation of
+$dA$ as a function of $x,y$; we provide helper functions to define 1st
+and 2nd order polynomials in $x,y$.  The next two dimensions are
+fitted independently (no cross terms).  The first represents the
+variation as a function of $r^2 / flux$, where $r$ is the aperture
+radius used to measure $dA$; this is the scaling of a magnitude error
+in the presence of a constant error in the sky level.  The last
+dimension represents the variation of $dA$ as a function of the
+stellar flux.
+
+The following forms of the aperture correction model may be selected
+by the user:
+\begin{datatype}
+typedef enum {
+    PM_PSF_NONE,
+    PM_PSF_CONSTANT,
+    PM_PSF_SKYBIAS,
+    PM_PSF_SKYSAT,
+    PM_PSF_XY_LIN,
+    PM_PSF_XY_QUAD,
+    PM_PSF_SKY_XY_LIN,
+    PM_PSF_SKYSAT_XY_LIN,
+    PM_PSF_ALL
+} pmPSF_ApTrendOptions;
+\end{datatype}
+
+The following utility function sets the aperture correction model
+coefficient masks to select the specific desired coefficients:
+\begin{prototype}
+bool pmPSF_MaskApTrend (pmPSF *psf, pmPSF_ApTrendOptions option);
+\end{prototype}
+
 \subsubsection{pmPSF, pmPSFtry, and PSF model} 
 
@@ -1902 +2076 @@
 of all of the source parameters, except the first four PSF-independent
 parameters, are represented as polynomial, stored in a \code{psArray}.
+The structure also contains the aperture correction model
+(\code{ApTrend}) and the curve-of-growth model (\code{growth}).  The
+additional elements are: \code{ApResid}, the constant term in the
+aperture correction model; \code{dApResid}, the residual scatter for
+bright sources ($S/N > 100$) after applying the aperture correction;
+\code{skyBias}, the measured average bias in the sky measurement;
+\code{skySat}, the scaling of the flux-dependent portion of the
+correction.
+
 The other elements of the structure define the quality of the PSF
-determination.
+determination.  
 
 \begin{datatype}
 typedef struct {
-    psS32 type;             ///< PSF Model in use
-    psArray *params;        ///< Model parameters (psPolynomial2D)
-    psF32 chisq;            ///< PSF goodness statistic
-    psS32 nPSFstars;        ///< number of stars used to measure PSF
+    pmModelType type;                   ///< PSF Model in use
+    psArray *params;                    ///< Model parameters (psPolynomial2D)
+    psPolynomial4D *ApTrend;            ///< ApResid vs (x,y,rflux) (rflux = ten(0.4*mInst)
+    pmGrowthCurve *growth;              ///< apMag vs Radius
+    float ApResid;                      ///< ???
+    float dApResid;                     ///< ???
+    float skyBias;                      ///< ???
+    float skySat;                       ///< ???
+    float chisq;                        ///< PSF goodness statistic
+    int nPSFstars;                      ///< number of stars used to measure PSF
+    int nApResid;                       ///< number of stars used to measure ApResid
 } pmPSF;
 \end{datatype}
 
 \begin{prototype}
-pmModel     *pmModelFromPSF (pmModel *model, pmPSF *psf);
+pmModel *pmModelFromPSF (pmModel *model, pmPSF *psf);
 \end{prototype}
 This function constructs a \code{pmModel} instance based on the
@@ -1925 +2115 @@
 
 \begin{prototype}
-bool         pmPSFFromModels (pmPSF *psf, psArray *models, psVector *mask);
+bool pmPSFFromModels (pmPSF *psf, psArray *models, psVector *mask);
 \end{prototype}
 This function takes a collection of \code{pmModel} fitted models from
@@ -1937 +2127 @@
 mask value (1 == \code{PSFTRY_MASK_OUTLIER}).  
 
+We definet he following two functions to convert the PSF model
+parameters into a collection of elements on a metadata structure, and
+vice versa.  These can be used to read and write PSFs to a file and or
+a database.
+\begin{prototype}
+psMetadata *pmPSFtoMD (psMetadata *metadata, pmPSF *psf);
+pmPSF *pmPSFfromMD (psMetadata *metadata);
+\end{prototype}
+
 We have the capability to test several different model functions in an
 attempt to build an accurate PSF for an image.  The complete set of
@@ -1946 +2145 @@
     pmPSF      *psf;
     psArray    *sources;      // pointers to the original sources
-    psArray    *modelFLT;     // model fits, floating parameters 
+    psArray    *modelEXT;     // model fits, floating parameters 
     psArray    *modelPSF;     // model fits, PSF parameters
     psVector   *mask;
     psVector   *metric;
     psVector   *fitMag;
-    float       ApResid;
-    float       dApResid;
-    float       skyBias;
 } pmPSFtry;
 \end{datatype}
@@ -1967 +2163 @@
 the fitted instrumental magnitude is stored in \code{fitMag}.  The
 quality metric for the PSF model is the aperture magnitude minus the
-fitted magnitude for each source.  This collection of aperture
-residuals is examined in the analysis process, and a linear trend of
-the residual with the inverse object flux (ie, $10^{0.4*mag}$) is
-fitted.  The result of this fit is a measured sky bias (systematic
-error in the sky measured by the fits), an effective
-infinite-magnitude aperture correction (\code{ApResid}), and the
-scatter of the aperture correction for the ensemble of PSF stars
-(\code{dApResid}).  The ultimate metric to intercompare multiple types
-of PSF models is the value of the aperture correction scatter.
+fitted magnitude for each source.  
+
+This collection of aperture residuals is examined in the analysis
+process, and a linear trend of the residual with the inverse object
+flux (ie, $10^{0.4*mag}$) is fitted.  The result of this fit is a
+measured sky bias (systematic error in the sky measured by the fits),
+an effective infinite-magnitude aperture correction (\code{ApResid}),
+and the scatter of the aperture correction for the ensemble of PSF
+stars (\code{dApResid}).  The ultimate metric to intercompare multiple
+types of PSF models is the value of the aperture correction scatter.
 
 The following functions are used to try out a single PSF model.
@@ -1999 +2196 @@
     PSFTRY_MASK_CLEAR    = 0x00,
     PSFTRY_MASK_OUTLIER  = 0x01, // 1: outlier in psf polynomial fit (provided by psPolynomials)
-    PSFTRY_MASK_FLT_FAIL = 0x02, // 2: flt model failed to converge 
+    PSFTRY_MASK_EXT_FAIL = 0x02, // 2: ext model failed to converge 
     PSFTRY_MASK_PSF_FAIL = 0x04, // 3: psf model failed to converge 
     PSFTRY_MASK_BAD_PHOT = 0x08, // 4: invalid source photometry           
@@ -2005 +2202 @@
 } pmPSFtryMaskValues;
 \end{datatype}
+
 
 \begin{datatype}
@@ -2079 +2277 @@
                           psF32 y,
                           psF32 Radius)
-\end{prototype}
-
-Define \code{psImage} subarrays for the source located at coordinates
-\code{x,y} on the image set defined by \code{readout}.  The pixels
-defined by this operation consist of a square window (of full width $2
-Radius + 1$) centered on the pixel which contains the given
-coordinate, in the frame of the readout.  The window is defined to
-have limits which are valid within the boundary of the \code{readout}
-image, thus if the radius would fall outside the image pixels, the
-subimage is truncated to only consist of valid pixels.  If
-\code{readout->mask} or \code{readout->weight} are not \code{NULL},
-matching subimages are defined for those images as well.  This
-function fails if no valid pixels can be defined (x or y less than
-Radius, for example).  This function should be used to define a region
-of interest around a source, including both source and sky pixels.
+
+bool pmSourceRedefinePixels(pmSource *mySource, 
+                            pmReadout *readout,
+                            psF32 x, 
+                            psF32 y,
+                            psF32 Radius)
+\end{prototype}
+
+The first form defines \code{psImage} subarrays (pixel, weight, and
+mask) for the source located at coordinates \code{x,y} on the image
+set defined by \code{readout}.  The pixels defined by this operation
+consist of a square window (of full width $2 Radius + 1$) centered on
+the pixel which contains the given coordinate, in the frame of the
+readout.  The window is defined to have limits which are valid within
+the boundary of the \code{readout} image, thus if the radius would
+fall outside the image pixels, the subimage is truncated to only
+consist of valid pixels.  If \code{readout->mask} or
+\code{readout->weight} are not \code{NULL}, matching subimages are
+defined for those images as well.  This function fails if no valid
+pixels can be defined (x or y less than Radius, for example).  This
+function should be used to define a region of interest around a
+source, including both source and sky pixels.  The second form accepts
+an existing source and redefines the pixels if the requested radius
+encompasses more pixels than the existing images.
 
 \begin{prototype}
 pmSource *pmSourceLocalSky(pmSource *source,
                            psStatsOptions statsOptions,
-                           psF32 Radius)
+                           float Radius)
 \end{prototype}
 
@@ -2124 +2331 @@
 source is returned.  The moments are measured within the given
 circular radius of the \code{source.peak} coordinates.  The return
-value indicates the success (TRUE) of the operation.
+value indicates the success (TRUE) of the operation.  This function
+also measures the approximate signal-to-noise ratio of the source
+(\code{source.SN}) based on the total number of source counts divided
+by the square-root of the total source variance, as determined from
+the weight image.
 
 \begin{prototype}
@@ -2172 +2383 @@
 type for these parameters are \code{psF32}.
 
-The following rules are used to make the classification.  Sources with
-peak pixel above the value of \code{SATURATE} are identified as type
-\code{PM_SOURCE_SATURATED}.  For the remaining sources, the signal to
-noise of the detection is approximated by:
-\[
-SN = \frac{S \sqrt{g}}{\sqrt{S + A B + \frac{A R_e^2}{\sqrt{g}}}}
-\]
-where 
-\[
-A = \pi \sigma_x \sigma_y
-\]
-and $\sigma_x$ is \code{pmMoment.Sx}, $\sigma_y$ is
-\code{pmMoment.Sy}, $B$ is \code{pmMoment.Sky} and $S$ is
-\code{pmMoment.Sum}. The two parameters, $g$ and $R_e$ are the gain,
-stored with the metadata keyword \code{GAIN} and the read-noise in
-electrons, stored with the metadata keyword \code{READ_NOISE}.
-
-All sources with:
-\[ |\sigma_x - \mbox{CLUMP}_x| < \mbox{CLUMP}_{dx}\]
-and
-\[ |\sigma_y - \mbox{CLUMP}_y| < \mbox{CLUMP}_{dy}\]
-should be identified as type \code{PM_SOURCE_PSFSTAR}.  Sources with 
-\[ \sigma_x < \mbox{CLUMP}_{x} - \mbox{CLUMP}_{dx}\]
+The following rules are used to make the classification.  The number
+of saturated pixels are counted, based on the mask having the
+\code{PSPHOT_MASK_SATURATED} bit set.  Sources which are greater than
+1$\sigma$ larger than the \code{pmPSFClump} center in both dimensions
+and which have more than a single saturated pixel are identified as
+being a likely saturated star (\code{type = PM_SOURCE_STAR, mode =
+PM_SOURCE_SATSTAR}).  Sources which are not so large but which have
+multiple saturated pixels are identified as saturated regions, ie
+bleed trails or hot columns (\code{type = PM_SOURCE_SATURATED}).
+
+Sources with 
+\[ \sigma_x < 0.05 \]
+or
+\[ \sigma_y < 0.05\]
+should be identified as type \code{PM_SOURCE_DEFECT} (likely cosmic
+ray pixel).
+
+Sources with
+\[ \sigma_x > \mbox{CLUMP}_{x} + 3\mbox{CLUMP}_{dx}\]
 and 
-\[ \sigma_y < \mbox{CLUMP}_{y} - \mbox{CLUMP}_{dy}\]
-should be identified as type \code{PM_SOURCE_DEFECT}.  Sources with
-\[ \sigma_x > \mbox{CLUMP}_{x} + \mbox{CLUMP}_{dx}\]
-and 
-\[ \sigma_y > \mbox{CLUMP}_{y} + \mbox{CLUMP}_{dy}\]
-should be identified as type \code{PM_SOURCE_GALAXY}.  All other
-sources should be identified as type \code{PM_SOURCE_OTHER}.
-\tbd{need to exclude stars outside valid data region}.
-
-Sources with $SN$ less than \code{FAINT_SN_LIM} are identified as type
-\code{PM_SOURCE_FAINTSTAR}.  Sources with $SN$ greater than
-\code{PSF_SN_LIM} are then selected as possible PSF stars.  These
-sources are used to determine a guess at the shape of the PSF, based
-on the collection of $\sigma_x$ and $\sigma_y$ values.
-
-\tbd{this discussion needs to be adjusted to match the implementation}
+\[ \sigma_y > \mbox{CLUMP}_{y} + 3\mbox{CLUMP}_{dy}\]
+should be identified as type \code{PM_SOURCE_EXTENDED}.  
+
+All other sources should be identified as type \code{PM_SOURCE_STAR}.
+Of these sources, the mode should be set to \code{PM_SOURCE_PSFSTAR}
+for any sources with $SN$ greater than \code{PSF_SN_LIM} which are
+within 1.5$\sigma$ of the PSF clump center.  These sources are used to
+determine a guess at the shape of the PSF, based on the collection of
+$\sigma_x$ and $\sigma_y$ values.
 
 \subsection{Object Fitting}
@@ -2245 +2445 @@
 function allocates a \code{pmModel} entry for the \code{pmSource}
 structure based on the provided model selection.  The method of
-defining the model parameter guesses are specified for each model
-below.  The guess values are placed in the model parameters.  The
-function returns \code{TRUE} on success or \code{FALSE} on failure.
+defining the model parameter guesses are determined by using
+\code{pmModelGuessFunc_GetFunction} to determine the guess function
+for the model of interest.  The returned function is called and the
+guess values are used to set the model parameters.  The function
+returns \code{TRUE} on success or \code{FALSE} on failure.
 
 \begin{prototype}