Changeset 5030

Timestamp:

Sep 13, 2005, 11:05:23 AM (21 years ago)

Author:

eugene

Message:

updates for cycle 8 release

Location:

trunk/doc/modules

Files:

• CameraImages.tex (modified) (4 diffs)
• ChangeLogSDRS.tex (modified) (3 diffs)
• ModulesSDRS.tex (modified) (49 diffs)

trunk/doc/modules/CameraImages.tex

@@ -114 +114 @@
 of analyses (e.g., the r.m.s. of the overscan fit).
 
-\tbd{At what stage are the offsets (\code{col0,row0}) get set, and how
-are they known?}
+\tbd{At what stage are the offsets ({\tt col0,row0}) set, and how are
+they known?}
 
 \subsubsection{A Readout}
@@ -405 +405 @@
 have \code{valid} set to \code{true}.
 
+\tbd{make these functions richer: select by extention, extname, cell,
+options to invalidate all / validate all, etc}
+
 \begin{prototype}
 bool pmFPAMorph(pmFPA *toFPA, pmFPA *fromFPA, bool positionDependent, int chipNum, int cellNum);
-bool pmFPAWrite(psFits *fits, pmFPA *fpa);
 \end{prototype}
-
-These two functions write out a focal plane hierarchy to a FITS file.
 
 \code{pmFPAMorph} shall morph the \code{fromFPA} focal plane hierarchy
@@ -434 +434 @@
 suitable error message, in which case it shall return \code{false}.
 
+\begin{prototype}
+bool pmFPAWrite(psFits *fits, pmFPA *fpa);
+\end{prototype}
+
 \code{pmFPAWrite} shall write the focal plane hierarchy, \code{fpa},
 to the specified \code{fits} file, returning \code{true} upon success
@@ -445 +449 @@
 \code{pmFPAWriteMask} is very similar to \code{pmFPAWrite}, but it
 shall write the \code{mask} elements of the \code{pmReadout}s
-comprinsing the \code{fpa}.
+comprising the \code{fpa}.
+
+\begin{prototype}
+pmFPAWriteWeight(psFits *fits, pmFPA *fpa);
+\end{prototype}
+
+\code{pmFPAWriteWeight} is very similar to \code{pmFPAWrite}, but it
+shall write the \code{weight} elements of the \code{pmReadout}s
+comprising the \code{fpa}.
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

trunk/doc/modules/ChangeLogSDRS.tex

@@ -1 @@
-%%% $Id: ChangeLogSDRS.tex,v 1.31 2005-09-13 03:26:45 price Exp $
+%%% $Id: ChangeLogSDRS.tex,v 1.32 2005-09-13 21:05:23 eugene Exp $
 
 \subsection{Changes from version 00 (16 August 2004) to version 01 (12 October 2004)}
@@ -87 +87 @@
 \end{itemize}
 
-\subsection{Changes from version 07 (15 July 2005) to present (???)}
+\subsection{Changes from version 07 (15 July 2005) to version 08 (13 Sept 2005)}
 
 \begin{itemize}
@@ -107 +107 @@
 \item Modified \code{pmSubtractBias}.
 \item Remove mask from \code{pmFlatField} (mask is contained in the readout).
+
+\item cleaned up / extended discussion of FITS and the FPA hierarchy.
+\item added \code{CONCEPT.DEFAULT} to \code{DEFAULTS} table.
+\item added \code{psArgumentVerbosity} requirement to \code{pmConfigRead}.
+
+\item substantial changes to the Objects section:
+\begin{itemize}
+  \item added \code{psphotMaskValues}?
+  \item added SN to \code{pmMoments}
+  \item added \code{pmPSFClump}
+  \item modified \code{pmSourceType} enum list
+  \item added radius to \code{pmModel}
+  \item added \code{pmModelGroup}
+  \item added several Model Group functions
+  \item added \code{pmPSF} and related functions
+  \item added \code{pmPSFtry} and related functions
+  \item added \code{pmSourceDefinePixels}
+  \item modified \code{pmSourceLocalSky} API
+  \item modified \code{pmSourceMoments} API
+  \item added \code{pmSourcePSFClump}
+  \item modified \code{pmSourceRoughClass} API
+  \item dropped \code{pmSourceSetPixelsCircle} (replaced with
+  \code{pmSourceDefinePixels} and the image mask functions.
+  \item added \code{pmModelFitStatus}
+  \item added \code{pmSourcePhotometry}
+  \item added \code{pmSourceDophotType}
+  \item added \code{pmSourceSextractType}
+  \item moved discussion of the object models to an appendix
 \end{itemize}
+\end{itemize}

trunk/doc/modules/ModulesSDRS.tex

@@ -1 @@
-%%% $Id: ModulesSDRS.tex,v 1.57 2005-09-13 03:36:09 price Exp $
-\documentclass[panstarrs]{panstarrs}
+%%% $Id: ModulesSDRS.tex,v 1.58 2005-09-13 21:05:23 eugene Exp $
+\documentclass[panstarrs,spec]{panstarrs}
 
 % basic document variables
@@ -11 +11 @@
 \project{Pan-STARRS Image Processing Pipeline}
 \organization{Institute for Astronomy}
-\version{07}
+\version{08}
 \docnumber{PSDC-430-012}
 
-\setlength{\topsep}{-2pt}
-  
 \begin{document}
 \maketitle
@@ -35 +33 @@
 06 & 2005 Apr 27 & final for cycle 6 \\ \hline
 07 & 2005 Jul 15 & final for cycle 7 \\ \hline
+08 & 2005 Sep 13 & final for cycle 8 \\ \hline
 \RevisionsEnd
 
@@ -74 +73 @@
 
 PSLib defines a \code{psMetadata} structure which can carry labeled
-data of arbirtary types.  The associated functions implemented by
+data of arbitrary types.  The associated functions implemented by
 PSLib consist of tools to manipulate and extract data from
-\code{psMetadata} collections.  Within PSLib, the \code{psMetadata}
-stucture is used to carry the data from a FITS header.  In addition,
-functions are available to fill a \code{psMetadata} collection from a
-text-based configuration file using a particular syntax, and to fill a
-\code{psMetadata} collection from a properly formatted XML document.
+\code{psMetadata} collections.  A particular application of the
+\code{psMetadata} structure within PSLib is to carry the data from a
+FITS header.  Other general-purpose information is also carried with
+the structure.  Functions are available to fill a \code{psMetadata}
+collection from a text-based configuration file using a human-readable
+syntax, and to fill a \code{psMetadata} collection from a properly
+formatted XML document.
 
 In the IPP Modules, we use \code{psMetadata} collections to carry
@@ -108 +109 @@
 configuration being the most general, and the recipe configuration the
 most specific.  For example, not all sites will have to deal with all
-cameras, and different cameras will have different recipes according
-to their particular quirks.
+cameras, and different cameras may require different recipes at
+different times according to their particular quirks, analysis
+experimentations, or their evolution.
 
 Each of the levels will have a metadata configuration file.  In the
@@ -116 +118 @@
 environment variable \code{PS_SITE}, if defined, or \code{~/.ipprc}
 otherwise.  The camera configuration shall be specified by the
-\code{camera} option on the command line if provided, or shall be
+\code{-camera} option on the command line if provided, or shall be
 inferred from a FITS header (more detail below).  The recipe
 configuration shall be specified by the \code{-recipe} option on the
@@ -138 +140 @@
   \end{itemize}
 \item \code{CAMERAS} of type \code{METADATA}: A list of instruments
-  that the system can handle.  Cameras are specified as separate
+  that the system understands.  Cameras are specified as separate
   metadata entries, with the name of the camera as the key, and the
   filename of the camera configuration file (of type \code{STR}) as
@@ -197 +199 @@
 \subsubsection{Camera Configuration}
 
-The camera configuration is the most complicated and involved, since
+The camera configuration is somewhat complicated and involved, since
 it must not only specify how to translate the pixels from a FITS file
 into a focal plane hierarchy (\S\ref{sec:focalplane}), but it must
@@ -216 +218 @@
 correspond to individual reads of the detector.
 
+The FITS data storage formation is a standard in the astronomical
+community for storing astronomical images.  A FITS file consists of an
+arbitrary number of coupled human readable \code{ASCII} header
+segments and binary data segments.  The headers describe the format
+and layout of the data segments.  The first of these groups is
+traditionally called the 'primary header unit' (PHU) and the rest are
+referred to as 'extensions'.  The header segments may contain
+extensive documentary information related to the interpretation of the
+data.  Although the FITS format defines a standard representation of
+the data, the header metadata is not so consistently defined within
+the astronomical community.  Also, the flexibility of the data format
+means that different representations are possible for the same
+fundamental collection of data.  The tools presented in this section
+provide a method to define and constrain the wide range of possible
+FITS representations of astronomical images.
+
 Within the FITS data representation, there are various choices which
 can and have been made for the placement of the pixels in the file.
@@ -222 +240 @@
 image data could be written as part of the primary data unit.  In a
 more complex case with multiple chips and multiple cells, the data may
-be organized in various ways.  The data may be distributed into
+be organized in several ways.  The data may be distributed into
 multiple files or in multiple FITS data extensions.  A single camera
 image may be written as a collection of files for individual chips
@@ -231 +249 @@
 
 In all of these representations, there are only two basic distinctions
-in how the pixel data is stored: what level the entire FITS file
-corresponds to (FPA or chip), and what level the extensions correspond
-to (chip, cell or no extensions at all).  Knowing these, and having
-a list of the components, we can construct the focal plane hierarchy.
-
-We therefore specify the following keywords:
+in how the pixel data is stored: what level in the hierarchy the
+entire FITS file corresponds to (FPA, chip, or cell), and what level
+the extensions correspond to (chip, cell or no extensions at all).
+Knowing these, and having a list of the components, we can construct
+the focal plane hierarchy.
+
+Note that a single data extension, consisting of a uniform grid of
+pixels, can only naturally represent a cell or a chip.  In order to
+represent the entire focal plane array as a single grid, some
+artificial choices would be made to fill-in or ignore the gaps between
+chips and their relative rotations.  Within our framework, a complete
+focal plane mosaic of multiple chips could be represented as a single
+extension by treating the collection of pixels as if they were from a
+single chip.  
+
+To define the hierarchy, we specify the following keywords:
 \begin{itemize}
-\item \code{PHU} of type \code{STR}: May be one of \code{CHIP} or
-  \code{CELL}.  This specifies what the scale of the Primary Header
-  Unit (and hence the entire FITS file) is.
+
+\item \code{PHU} of type \code{STR}: May be one of \code{FPA},
+  \code{CHIP}, or \code{CHIP}.  This specifies the focal plane level
+  of the Primary Header Unit, and hence the entire FITS file (the
+  'class' of the file) .
+
 \item \code{EXTENSIONS} of type \code{STR}: May be one of \code{CHIP},
   \code{CELL} or \code{NONE}, though not of a level higher than that
   specified by the \code{PHU}.  This specifies what each extension
   represents.
+
 \item \code{CONTENTS} which may be of type \code{METADATA} or
   \code{STR}, depending upon the \code{PHU} and \code{EXTENSIONS},
@@ -431 +463 @@
 Each image has associated with it what we will call {\it concepts}
 (for want of a better word).  These are values corresponding to
-general quantities and qualities relevant to the IPP such as airmass,
-date, read noise and filter.  The values of each of the below concepts
-shall be determined when the FPA is read into memory (via
-\code{pmFPARead}), and stored at the appropriate level in the focal
-plane hierarchy.
+general quantities and qualities necessary to understand and interpret
+the data such as airmass, date, read noise and filter.  The values of
+each of the below concepts shall be determined when the FPA is read
+into memory (via \code{pmFPARead}), and stored at the appropriate
+level in the focal plane hierarchy.
 
 Below is a list of concepts that the IPP requires, with the
@@ -466 +498 @@
 \end{itemize}
 
-\tbd{Note that \code{CELL.EXPOSURE}, \code{CELL.DARKTIME} and
-\code{CELL.TIME} should actually be specified at the readout level.
-However, at this present time, we're not sure how these should be
-specified, and so we move them up to the cell level and assume that
-all readouts are of the same exposure and dark time.}
+\tbd{Note that CELL.EXPOSURE, CELL.DARKTIME and CELL.TIME should
+actually be specified at the readout level.  However, at this present
+time, we're not sure how these should be specified, and so we move
+them up to the cell level and assume that all readouts are of the same
+exposure and dark time.}
 
 For different camera systems, these concepts are not always known by
@@ -498 +530 @@
 \code{METADATA}, with the component keywords being the value of the
 second concept (on which the first depends).  To avoid infinite
-recursion, no further dependency is permitted.  An example of the
+recursion, no further dependency is permitted.  We also allow an entry
+\code{CONCEPT.DEFAULT} specifiying the default value of the concept if
+a match is not made with the dependcency list.  An example of the
 dependency:
 
@@ -505 +539 @@
 DEFAULTS        METADATA
         CELL.GAIN.DEPEND     STR     CHIP.NAME
+        CELL.GAIN.DEFAULT    STR     1.0
         CELL.GAIN    METADATA
                 ccd00   F32     1.2
@@ -552 +587 @@
 
 Note that the FITS standard is that the time in the header refers to
-the {\it start} of the observation.  \tbd{In the future, we might add
-additional qualifiers that calculate the start time of the observation
-based on someone foolishly putting the end- or mid-time in the header.}
-
-\tbd{Should we move \code{CELL.TIMESYS} into the format as well?}
+the {\it start} of the observation.  
+
+\tbd{the PRE2000 and BACKWARDS qualifiers should be replace with
+explicit format definitions in the form YYYY/MM/DD}
+
+\tbd{In the future, we might add additional qualifiers that calculate
+the start time of the observation based on someone foolishly putting
+the end- or mid-time in the header.}
+
+\tbd{Should we move CELL.TIMESYS into the format as well?}
 
 \paragraph{FPA.RA and FPA.DEC}
@@ -607 +647 @@
 commas or semi-colons) that contains the appropriate values.
 \end{itemize}
+
+\tbd{the use of implicit interpretation of formats should be
+  discouraged: format interpretation guides should be provided}
 
 \subsection{Configuration APIs}
@@ -641 +684 @@
   trace levels specified by the \code{TRACE}.
 \end{itemize}
+Note that additional log/trace command-line options may be specified
+and interpretted using the \code{psArgumentVerbosity} function from
+psLib.  These options should (in the case of logging) override the
+configuration-supplied information or (in the case of tracing)
+supplement it.
 
 \code{pmConfigCameraFromHeader} shall load the \code{camera}
@@ -784 +832 @@
 M_{\rm pM} - pA, M_{\rm sP} - M_{\rm sM} - sA)$.
 
-\section{Phase 2}
-
-Phase 2 is the processing stage wherein the instrumental signatures
-are removed from the detector images, in preparation for the
-combination of multiple images in Phase 4.
-
-The Phase 2 processing modules are:
+\section{Image Detrending}
+
+Image Detrending is the image analysis process wherein the
+instrumental signatures are removed from the individual images.  This
+section discusses the modules used for image detrending.  The basic
+image detrending steps are:
 \begin{itemize}
 \item Subtract bias;
@@ -797 +844 @@
 \item Mask bad pixels;
 \item Subtract the background;
-\item \tbd{Mask cosmic rays;}
-\item \tbd{Mask optical defects;}
-\item \tbd{Measure the PSF;}
-\item \tbd{Find and measure objects;}
-\item \tbd{Correct astrometry; and}
-\item \tbd{Get postage stamps.}
+\item Mask cosmic rays;
+\item Mask optical defects;
 \end{itemize}
-
-Each of these shall be discussed in turn, below.  Those modules which
-are \tbd{} will be deferred until they may be properly defined,
-some of which requires further research to define the best algorithm.
 
 \subsection{Bias subtraction}
@@ -995 +1034 @@
 \label{sec:maskValues}
 
-We define several mask values for use in the phase 2 processing:
+We define several mask values for use in the detrend processing:
 \begin{datatype}
 /** Mask values */
@@ -1033 +1072 @@
 the \code{growVal}).
 
-\tbd{In the future, may change \code{grow} to a convolution kernel}.
+\tbd{In the future, may change {\tt grow} to a convolution kernel}.
 
 Note that the input image, \code{in}, and the \code{mask} need not be
@@ -1104 +1143 @@
 
 The elements of the focal plane hierarchy each contain an
-\code{analysis} member, intended to log the results of the Phase 2
-tasks.  The Phase 2 tasks shall add to the \code{analysis} members as
+\code{analysis} member, intended to log the results of the detrend
+tasks.  The detrend tasks shall add to the \code{analysis} members as
 follows:
 
@@ -1294 +1333 @@
 of the same type.
 
-\section{Object Detection, Measurement, and Classification Routines}
+\section{Objects on Images}
 
 \subsection{Overview}
@@ -1304 +1343 @@
 The elements defined in this section are generally low-level
 components which can be connected together to construct a complete
-object measurement suite.  An example pseudo-C program using these
-functions is provided in Appendix~\ref{psphot}.
+object measurement suite.  
 
 We first define the collection of structures needed to carry
@@ -1329 +1367 @@
 referenced without attempting to supply an analytical model.  Finally,
 it is often useful to allow a single complex model to be represented
-as a collection of simpler contained structures which may be modelled.
+as a collection of simpler contained structures which may be modeled.
 Thus, the representation of an object must be capable of identifying
 children, or substructures, of that object.
@@ -1394 +1432 @@
 edge.  The \code{PM_PEAK_FLAT} represents a peak pixel which has more
 than a specific number of neighbors at the same value, within some
-tolarence:
+tolerance:
 \begin{datatype}
 typedef enum {
@@ -1477 +1515 @@
 \subsubsection{pmModel Source Model and Abstraction} 
 
-An object's flux distribution may be modelled with some analytical
+An object's flux distribution may be modeled with some analytical
 function.  The description of the model includes the model parameters
 and their errors, along with the fit $\chi^2$.  The model type is
@@ -1566 +1604 @@
 
 \code{pmModelFunc} is the function used to determine the value of the
-mdoel at a specific coordinate, and is the one used by
+model at a specific coordinate, and is the one used by
 \code{psMinimizeLMChi2}.  
 
@@ -1681 +1719 @@
 set by the model fitting and psf fitting steps.  For each model, the
 value of the quality metric is stored in the vector \code{metric} and
-the fitted instrumental magntiude is stored in \code{fitMag}.  The
+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
+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
@@ -1709 +1747 @@
 
 The following datatype defines the masks used by the \code{pmPSFtry}
-anslysis to identify sources which should or should not be included in
+analysis to identify sources which should or should not be included in
 the analysis.
 \begin{datatype}
@@ -1736 +1774 @@
 \end{prototype}
 
-\subsection{Object Model Abstraction}
-
-\tbd{this section is duplicating the section above}
-
-The object model functions are defined to allow for the flexible
-addition of new object models.  Every object model, with parameters
-represented by \code{pmModel}, has an associated set of functions
-which provide necessary support operations.  A set of abstract
-functions allow the programmer to select the approriate function or
-property for a specific named object model.
-
-The following function concepts are provided by each model.
-
-\begin{prototype}
-typedef psMinimizeLMChi2Func psModelFunc;
-\end{prototype}
-This function is the model chi-square minimization function for this
-model.
-
-\begin{prototype}
-typedef psF64 (*psModelFlux)(const psVector *params);
-\end{prototype}
-This function returns the integrated flux for the given model
-parameters.
-
-\begin{prototype}
-typedef bool (*psModelGuessFunc)(psModel *model, psSource *source);
-\end{prototype}
-This function provides the model guess parameters based on the details
-of the given source.
-
-\begin{prototype}
-typedef bool (*psModelFromPSFFunc)(psModel *modelPSF, psModel *modelFLT, pmPSF *psf);
-\end{prototype}
-This function constructs the PSF model for the given source based on
-the supplied \code{psf} and the FLT model for the object.  
-
-\begin{prototype}
-typedef psF64 (*psModelRadius)(const psVector *params, double flux);
-\end{prototype}
-This function returns the radius at which the given model and
-parameters achieves the given flux.
-
-Each of the function types above has a corresponding function which
-returns the function given the model type:
-\begin{prototype}
-psModelFunc psModelFunc_GetFunction (psModelType type);
-psModelFlux psModelFlux_GetFunction (psModelType type);
-psModelGuessFunc psModelGuessFunc_GetFunction (psModelType type);
-psModelFromPSFFunc psModelFromPSFFunc_GetFunction (psModelType type);
-psModelRadius psModelRadius_GetFunction (psModelType type);
-\end{prototype}
-
-In addition, the following utility functions return information about
-the specified model:
-
-\begin{prototype}
-psS32 psModelParameterCount (psModelType type);
-psS32 psModelSetType (char *name);
-char *psModelGetType (psModelType type);
-\end{prototype}
-\code{psModelParameterCount} returns the number of parameters for the
-given model.  The remaining functions lookup the name or identifying
-code for the model from the other concept.  Model names are character
-strings in all caps of the form \code{GAUSS}.  Names are invarient
-between multiple compliations of the library, but the model numbers
-are not and should only be used within programs.
-
 \subsection{Basic Object Detection APIs}
 
@@ -1819 +1789 @@
 cases must be addressed.  Equal value elements: If an element has the
 same value as the following element, it is not considered a peak.  If
-an element has the same value as the preceeding element (but not the
+an element has the same value as the preceding element (but not the
 following), then it is considered a peak.  Note that this rule
 (arbitrarily) identifies flat regions by their trailing edge.  Edge
@@ -1858 +1828 @@
 
 \begin{prototype}
-pmSource *pmSourceLocalSky(const psImage *image, const pmPeak *peak, psStatsOptions statsOptions, float innerRadius, float outerRadius);
-\end{prototype}
-
-Measure the local sky in the vicinity of the given \code{peak}.  The
-image pixels in the square annulus with inner and outer half-width
-('square-radii') as specified are used to measure the local background
-in the vicinity of the the specified peak coordinates.  The local
-background measurement uses the specified statistic passed in via the
-\code{stats} entry.  This function allocates a \code{pmSource}
-structure and uses the resulting sky to set the value of the
-\code{pmMoments.sky} element of that \code{pmSource} structure.  The
-input \code{peak} is also placed on the \code{pmSource} structure,
-which is then returned.
+bool pmSourceDefinePixels(pmSource *mySource, 
+                          pmReadout *readout,
+                          psF32 x, 
+                          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.
+
+\begin{prototype}
+pmSource *pmSourceLocalSky(pmSource *source,
+                           psStatsOptions statsOptions,
+                           psF32 Radius)
+\end{prototype}
+
+Measure the local sky in the vicinity of the given \code{source}.  The
+\code{Radius} defines the square aperture in which the moments will be
+measured.  This function assumes the source pixels have been defined,
+and that the value of \code{Radius} here is smaller than the value of
+\code{Radius} used to define the pixels.  The annular region not
+contained within the radius defined here is used to measure the local
+background in the vicinity of the source.  The local background
+measurement uses the specified statistic passed in via the
+\code{statsOptions} entry.  This function allocates the
+\code{pmMoments} structure.  The resulting sky is used to set the
+value of the \code{pmMoments.sky} element of the provided
+\code{pmSource} structure.  
 
 \begin{prototype}
@@ -1884 +1880 @@
 value indicates the success (TRUE) of the operation.
 
-\tbd{add pmSourcePSFClump}
-
-\tbd{fix pmSourceRoughClass}
-
-\tbd{add pmSourcePhotometry}
-
-\tbd{pmSourceDophotType}
-
-\tbd{pmSourceSextractType}
-
-\tbd{pmModelFitStatus}
-
-\begin{prototype}
-bool pmSourceRoughClass(pmArray *source, psMetadata *metadata);
+\begin{prototype}
+pmPSFClump pmSourcePSFClump(psArray *sources, psMetadata *metadata);
+\end{prototype}
+
+We use the source moments to make an initial, approximate source
+classification, and as part of the information needed to build a PSF
+model for the image.  As long as the PSF shape does not vary
+excessively across the image, the sources which are represented by a
+PSF (the start) will have very similar second moments.  The function
+\code{pmSourcePSFClump} searches a collection of \code{sources} with
+measured moments for a group with moments which are all very similar.
+The function returns a \code{pmPSFClump} structure, representing the
+centroid and size of the clump in the $\sigma_x$, $\sigma_y$
+second-moment plane.  
+
+The goal is to identify and characterize the stellar clump within the
+$\sigma_x, \sigma_y$ plane.  To do this, an image is constructed to
+represent this plane.  The units of $\sigma_x$ and $\sigma_y$ are in
+image pixels.  A pixel in this analysis image represents 0.1 pixels in
+the input image.  The dimensions of the image need only be 10 pixels.
+The peak pixel in this image (above a threshold of half of the image
+maximum) is found.  The coordinates of this peak pixel represent the
+2D mode of the $\sigma_x, \sigma_y$ distribution.  The sources with
+$\sigma_x, \sigma_y$ within 0.2 pixels of this value are then used to
+calculate the median and standard deviation of the $\sigma_x,
+\sigma_y$ values.  These resulting values are returned via the
+\code{pmPSFClump} structure.
+
+The return value indicates the success (TRUE) of the operation.
+
+\tbd{limit the S/N of the candidate sources (part of Metadata)?} 
+
+\tbd{save the clump parameters on the Metadata} 
+
+\begin{prototype}
+bool pmSourceRoughClass(psArray *sources, psMetadata *metadata, pmPSFClump clump)
 \end{prototype}
 
 Based on the specified data values, make a guess at the source
 classification.  The sources are provides as a \code{psArray} of
-\code{psSource} entries.  Definable parameters needed to make the
+\code{pmSource} entries.  Definable parameters needed to make the
 classification are provided to the routine with the \code{psMetadata}
 structure.  The rules below refer to values which can be extracted
@@ -1925 +1943 @@
 electrons, stored with the metadata keyword \code{READ_NOISE}.
 
-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.
-
-The goal is to identify and characterize the stellar clump within the
-$\sigma_x, \sigma_y$ plane.  To do this, an image is constructed to
-represent this plane.  The units of $\sigma_x$ and $\sigma_y$ are in
-image pixel.  A pixel in this analysis image represents 0.1 pixels in
-the input image.  The dimensions of the image need only be 10 pixels.
-The peak pixel in this image (above a threshold of half of the image
-maximum) is found.  The coordinates of this peak pixel represent the
-2D mode of the $\sigma_x, \sigma_y$ distribution.  The sources with
-$\sigma_x, \sigma_y$ within 0.2 pixels of this value are then used to
-calculate the median and standard deviation of the $\sigma_x,
-\sigma_y$ values.  These resulting values are placed back on the
-metadata structure with the metadata names \code{PSF_CLUMP_X},
-\code{PSF_CLUMP_dX} and \code{PSF_CLUMP_Y}, \code{PSF_CLUMP_dY}.
-
 All sources with:
 \[ |\sigma_x - \mbox{CLUMP}_x| < \mbox{CLUMP}_{dx}\]
@@ -1961 +1959 @@
 \tbd{need to exclude stars outside valid data region}.
 
-The return value indicates the success (TRUE) of the operation.
+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}
 
 \subsection{Object Fitting}
@@ -1987 +1991 @@
 \item Subtract model from image.
 \end{enumerate}
-
-\begin{prototype}
-bool pmSourceSetPixelsCircle(pmSource *source, const psImage *image, float radius, int maskVal);
-\end{prototype}
-
-Define pixels associated with a source based on a circular aperture.
-This operation creates the \code{source.pixels} and \code{source.mask}
-entries for the source based on a circular aperture centered on the
-source centroid, if the \code{pmSource.pmMoments} entry exists, or
-\code{pmSource.pmPeak} if it does not.  The \code{source.pixels} is a
-subimage of the input image.  The function returns \code{TRUE} on
-success or \code{FALSE} on failure.
 
 \begin{prototype}
@@ -2039 +2031 @@
 
 \begin{prototype}
+bool pmModelFitStatus (pmModel *model);
+\end{prototype}
+
+This function wraps the call to the model-specific function returned
+by \code{pmModelFitStatusFunc_GetFunction}.  The model-specific
+function examines the model parameters, parameter errors, Chisq, S/N,
+and other parameters available from \code{model} to decide if the
+particular fit was successful or not.
+
+\begin{prototype}
 bool pmSourceAddModel(psImage *image, pmSource *source, bool center, bool sky);
 bool pmSourceSubModel(psImage *image, pmSource *source, bool center, bool sky);
@@ -2045 +2047 @@
 Add or subtract the given source model flux to/from the provided
 image.  The boolean option \code{center} selects if the source is
-recentered to the image center or if it is placed at its centroid
+re-centered to the image center or if it is placed at its centroid
 location.  The boolean option \code{sky} selects if the background sky
 is applied (\code{TRUE}) or not.  The pixel range in the target image
@@ -2051 +2053 @@
 image.  The success status is returned.
 
-\subsection{Basic Object Models}
-\label{ObjectModels}
-
-We specify a variety of basic object models which are required.
-Details of the model functional forms, parameters, and the derivatives
-are specified in the ADD.
-
-\subsubsection{Real 2D Gaussian}
-
-\begin{prototype}
-float pmMinLM_Gauss2D(psVector *deriv, psVector *params, psVector *x);
-\end{prototype}
-
-This function is a two-dimensional Gaussian with an elliptical
-cross-section and a constant local background.  
-
-The intial guess for the Gaussian parameters may be taken from the
-moments, peak value, and local sky.
-
-\subsubsection{Pseudo-Gaussian}
-
-\begin{prototype}
-float pmMinLM_PseudoGauss2D(psVector *deriv, psVector *params, psVector *x);
-\end{prototype}
-
-This function is a polynomial approximation of a 2D Gaussian otherwise
-very similar to the real Gaussian.  It is used in place of a real
-Gaussian for speed.
-
-The intial guess for the Gaussian parameters may be taken from the
-moments, peak value, and local sky.
-
-\subsubsection{Waussian}
-
-\begin{prototype}
-float pmMinLM_Wauss2D(psVector *deriv, psVector *params, psVector *x);
-\end{prototype}
-
-The Waussian is a modified polynomial approximation of a 2D Gaussian,
-with non-linear polynomial terms having variable coefficients, rather
-than the Taylor series values of 1/2 and 1/6.  
-
-\subsubsection{Twisted Gaussian}
-
-\begin{prototype}
-float pmMinLM_TwistGauss2D(psVector *deriv, psVector *params, psVector *x);
-\end{prototype}
-
-This function describes an object with power-law wings and a flattened
-core, where the core has a different contour from the wings.  
-
-The intial guess for the Gaussian parameters may be taken from the
-moments, peak value, and local sky.
-
-\tbd{future galaxy models to be implemented}
-
-\subsubsection{Sersic Galaxy Model}
-
-\begin{prototype}
-float pmMinLM_Sersic(psVector *deriv, psVector *params, psVector *x);
-\end{prototype}
-
-\subsubsection{Sersic with Core Galaxy Model}
-
-\begin{prototype}
-float pmMinLM_SersicCore(psVector *deriv, psVector *params, psVector *x);
-\end{prototype}
-
-\subsubsection{Pseudo Sersic Galaxy Model}
-
-\begin{prototype}
-float pmMinLM_PseudoSersic(psVector *deriv, psVector *params, psVector *x);
-\end{prototype}
-
+\begin{prototype}
+bool pmSourcePhotometry (float *fitMag,  // integrated fit magnitude
+                         float *obsMag,  // aperture flux magnitude
+                         pmModel *model, // model used for photometry
+                         psImage *image, // image pixels to be used
+                         psImage *mask   // mask of pixels to ignore
+);
+\end{prototype}
+
+The function returns both the magnitude of the fit, defined as $-2.5
+\log{\rm flux}$, where the flux is integrated under the model,
+theoretically from a radius of 0 to infinity.  In practice, we
+integrate the model beyond $50 \sigma$.  The aperture magnitude is
+defined as $-2.5 \log{\rm flux}$, where the flux is summed for all
+pixels which are not excluded by the aperture mask.  The model flux is
+calculated by calling the model-specific function provided by
+\code{pmModelFlux_GetFunction}.
+
+\begin{prototype}
+int pmSourceDophotType (pmSource *source);
+\end{prototype}
+This function converts the source classification into the closest
+available approximation to the Dophot classification scheme.  The
+following list gives the correspondence:
+\begin{verbatim}
+PM_SOURCE_DEFECT:       8
+PM_SOURCE_SATURATED:    8
+PM_SOURCE_SATSTAR:      10
+PM_SOURCE_PSFSTAR:      1
+PM_SOURCE_GOODSTAR:     1
+PM_SOURCE_POOR_FIT_PSF: 7
+PM_SOURCE_FAIL_FIT_PSF: 4
+PM_SOURCE_FAINTSTAR:    4
+PM_SOURCE_GALAXY:       2
+PM_SOURCE_FAINT_GALAXY: 2
+PM_SOURCE_DROP_GALAXY:  2
+PM_SOURCE_FAIL_FIT_GAL: 2
+PM_SOURCE_POOR_FIT_GAL: 2
+PM_SOURCE_OTHER:        ?
+\end{verbatim}
+
+\begin{prototype}
+int pmSourceSextractType (pmSource *source);
+\end{prototype}
+This function converts the source classification into the closest
+available approximation to the Sextractor classification scheme.
+\tbd{the correspondence is not yet defined}.
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@@ -2218 +2193 @@
   questionable pixels neighbor each other in the transformed image.
 \item The cores of point sources may mimic a cosmic ray, especially in
-  under-sampled images.  To minimise flagging stars as cosmic rays, we
+  under-sampled images.  To minimize flagging stars as cosmic rays, we
   determine the gradient around the pixel of interest; if the gradient
   is large, then the pixel is likely the core of a point source.  In
@@ -2332 +2307 @@
 Image subtraction is arguably the best method of identifying faint
 variable sources in images with different point-spread functions.  It
-relies on fitting for a convolution kernel that minimises the
+relies on fitting for a convolution kernel that minimizes the
 residuals in subtracting small regions of the image.  The use of a
 convolution kernel consisting of a linear combination of basis
@@ -2434 +2409 @@
 \code{spatialOrder}).  The \code{subIndex} is set to the kernel which
 has \code{u = 0}, \code{v = 0}, \code{xOrder = 0} and \code{yOrder =
-0}, for the first of the gaussian widths in the \code{sigmas} vector.
+0}, for the first of the Gaussian widths in the \code{sigmas} vector.
 
 \subsection{Stamps}
@@ -2472 +2447 @@
 
 \begin{prototype}
-psArary *pmSubtractionFindStamps(psArray *stamps, // Output stamps, or NULL
+psArray *pmSubtractionFindStamps(psArray *stamps, // Output stamps, or NULL
                                  const psImage *image, // Image for which to find stamps
                                  const psImage *mask, // Mask
@@ -2491 +2466 @@
 stamp \code{status} is \code{PM_STAMP_REJECTED}.
 
-A stamp shall be recognised as the pixel with the greatest value that
+A stamp shall be recognized as the pixel with the greatest value that
 does not have the corresponding pixel in the \code{mask} matching
 \code{maskVal}.  If the value of the this pixel does not exceed
@@ -2553 +2528 @@
 
 Since this step is one of the major rate-limiting factors in image
-subtraction, care should be taken with optimisation.
+subtraction, care should be taken with optimization.
 
 \begin{prototype}
@@ -2603 +2578 @@
 input image, and then squaring to obtain the mean square residual.
 
-\subsection{Visualisation of kernel}
-
-Having solved for the best-fit kernel, it is often useful to visualise
+\subsection{Visualization of kernel}
+
+Having solved for the best-fit kernel, it is often useful to visualize
 it.
 
@@ -2709 +2684 @@
 \appendix
 
-\section{Pseudo-C PSPhot}
-\label{psphot}
-
-\begin{verbatim}
-# include <pslib.h>
-# include <psmodule.h>
-
-main () {
-
-  psMetadata *header;
-  psImage *image;
-
-  fd = psFitsOpen (argv[1]);
-  md = psFitsReadHeader (fd);
-  image = psFitsReadImage (fd, md);
-
-  stats = psImageStats (NULL, image);
-
-  RDNOISE  = psMetadataLookup (md, "RDNOISE");
-  GAIN     = psMetadataLookup (md, "GAIN");
-  INNER    = psMetadataLookup (config, "INNER_RADIUS");
-  OUTER    = psMetadataLookup (config, "OUTER_RADIUS");
-  SATURATE = psMetadataLookup (config, "SATURATE");
-  NSIGMA   = psMetadataLookup (config, "PSF_PEAK_THRESHOLD");
-  RADIUS   = psMetadataLookup (config, "PSF_MOMENTS_RADIUS");
-  XBORDER  = psMetadataLookup (config, "XBORDER");
-  YBORDER  = psMetadataLookup (config, "YBORDER");
-
-  keep = psRegionAlloc (XBORDER, image->nCol - YBORDER, 
-                        YBORDER, image->nRow - YBORDER);
-  
-  Sky = stats->median;
-  Sig = sqrt(Sky/GAIN + SQ(RDNOISE));
-
-  kernel = psKernelParts ();
-  smooth = psImageConvolve (NULL, image, kernel, PS_PARTS);
-
-  peaks = pmFindImagePeaks (smooth, NSIGMA*Sig + Sky);
-
-  peaks = pmCullImagePeaks (peaks, SATURATE, *keep);
-  
-  sources = pmSourceLocalSky (image, peaks, INNER, OUTER);
-
-  sources = pmSourceMoments (image, sources, RADIUS);
-  
-  sources = pmSourceRoughClassify (sources, SATURATE, MIN_SN_LIM, *keep);
-
-  stars = pmSourceSelectBrightStars (sources);
-
-  stars = pmSourceFitModel (
-}
-
-
-
-psArray *pmFindImagePeaks (psImage *image, float threshold) {
-
-  psVector *row;
-
-  row = psVectorAlloc (image[0].Ncol);
-
-  /* find peaks in each row */
-  for (i = 0; i < image[0].Nrow; i++) {
-    rowpeaks = pmFindVectorPeaks (row, threshold);
-    peaks.x = rowpeaks;
-    peaks.y = i;
-    peaks.z = image (i, x);
-  }
-
-  /* drop non-local peaks (peaks with neighbors) */
-  for (n = 0; n < peaks.n; n++) {
-    if (!local_peak) {
-      drop_peak;
-    }
-  }
-  return (peaks);
-}
-\end{verbatim}
+\section{Basic Object Models}
+\label{ObjectModels}
+
+We specify a variety of basic object models which are required.
+Details of the model functional forms, parameters, and the derivatives
+are specified in the ADD.
+
+\subsubsection{Real 2D Gaussian}
+
+\begin{prototype}
+float pmMinLM_Gauss2D(psVector *deriv, psVector *params, psVector *x);
+\end{prototype}
+
+This function is a two-dimensional Gaussian with an elliptical
+cross-section and a constant local background.  
+
+The initial guess for the Gaussian parameters may be taken from the
+moments, peak value, and local sky.
+
+\subsubsection{Pseudo-Gaussian}
+
+\begin{prototype}
+float pmMinLM_PseudoGauss2D(psVector *deriv, psVector *params, psVector *x);
+\end{prototype}
+
+This function is a polynomial approximation of a 2D Gaussian otherwise
+very similar to the real Gaussian.  It is used in place of a real
+Gaussian for speed.
+
+The initial guess for the Gaussian parameters may be taken from the
+moments, peak value, and local sky.
+
+\subsubsection{Waussian}
+
+\begin{prototype}
+float pmMinLM_Wauss2D(psVector *deriv, psVector *params, psVector *x);
+\end{prototype}
+
+The Waussian is a modified polynomial approximation of a 2D Gaussian,
+with non-linear polynomial terms having variable coefficients, rather
+than the Taylor series values of 1/2 and 1/6.  
+
+\subsubsection{Twisted Gaussian}
+
+\begin{prototype}
+float pmMinLM_TwistGauss2D(psVector *deriv, psVector *params, psVector *x);
+\end{prototype}
+
+This function describes an object with power-law wings and a flattened
+core, where the core has a different contour from the wings.  
+
+The initial guess for the Gaussian parameters may be taken from the
+moments, peak value, and local sky.
+
+\tbd{future galaxy models to be implemented}
+
+\subsubsection{Sersic Galaxy Model}
+
+\begin{prototype}
+float pmMinLM_Sersic(psVector *deriv, psVector *params, psVector *x);
+\end{prototype}
+
+\subsubsection{Sersic with Core Galaxy Model}
+
+\begin{prototype}
+float pmMinLM_SersicCore(psVector *deriv, psVector *params, psVector *x);
+\end{prototype}
+
+\subsubsection{Pseudo Sersic Galaxy Model}
+
+\begin{prototype}
+float pmMinLM_PseudoSersic(psVector *deriv, psVector *params, psVector *x);
+\end{prototype}
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%