Index: /trunk/doc/pslib/psLibSDRS.tex
===================================================================
--- /trunk/doc/pslib/psLibSDRS.tex	(revision 287)
+++ /trunk/doc/pslib/psLibSDRS.tex	(revision 288)
@@ -418,4 +418,5 @@
 \end{verbatim}
 \caption{An example of reference counting}
+\label{tabReferenceCounting}
 \end{table}
 
@@ -470,5 +471,5 @@
 int psGetTraceLevel(const char *name);  // facilty of interest
 
-void psTraceReset(void);		// turn off all tracing, and free trace's allocated memory
+void psTraceReset(void);                // turn off all tracing, and free trace's allocated memory
 
 void psPrintTraceLevels(void);          // print trace levels
@@ -815,11 +816,10 @@
 
 This type and functions may be declared and defined using two macros
-from \file{psArray.h} (table \ref{tabPsArray}),
-\code{PS_DECLARE_ARRAY_TYPE(psType)} and
-\code{PS_CREATE_ARRAY_TYPE(psType)}.  The former defines the \code{typedef}
-and declares the prototypes (and is thus suitable for use in a
-header file); the latter generates the code for the three functions
-\code{psType(Alloc|Realloc|Free)} (and should thus appear in exactly one
-source file for a given type).
+from \file{psArray.h}, \code{PS_DECLARE_ARRAY_TYPE(psType)} and
+\code{PS_CREATE_ARRAY_TYPE(psType)}.  The former defines the
+\code{typedef} and declares the prototypes (and is thus suitable for
+use in a header file); the latter generates the code for the three
+functions \code{psType(Alloc|Realloc|Free)} (and should thus appear in
+exactly one source file for a given type).
 
 The \code{psType} should be a single word (e.g. \code{psXY}); in particular,
@@ -837,5 +837,5 @@
 If you wish to use arrays of pointers, use the macros
 \code{PS_DECLARE_ARRAY_PTR_TYPE(psType)} and
-\code{PS_CREATE_ARRAY_PTR_TYPE(psType)} (table \ref{tabPsArray}). These
+\code{PS_CREATE_ARRAY_PTR_TYPE(psType)}. These
 create types \code{typedef psType *psTypePtr} and \code{psTypePtrArray}:
 \begin{verbatim}
@@ -931,6 +931,6 @@
 
     for (int i = 0; i < t->n; i++) {
-	t->arr[i].x = i;
-	pt->arr[i]->y = 10*i;
+        t->arr[i].x = i;
+        pt->arr[i]->y = 10*i;
     }
 
@@ -939,5 +939,5 @@
 
     for (int i = 0; i < t->n; i++) {
-	printf("%d %d  ", t->arr[i].x, pt->arr[i]->y);
+        printf("%d %d  ", t->arr[i].x, pt->arr[i]->y);
     }
     printf("\n");
@@ -1100,7 +1100,7 @@
 /** Set a bit mask */
 psBitMask *
-psBitMaskSet(psBitMask *outMask,	//!< Output bit mask or NULL
-	     const psBitMask *myMask,	//!< Input bit mask
-	     int bit			//!< Bit to set
+psBitMaskSet(psBitMask *outMask,        //!< Output bit mask or NULL
+             const psBitMask *myMask,   //!< Input bit mask
+             int bit                    //!< Bit to set
     );
 \end{verbatim}
@@ -1110,5 +1110,5 @@
 int
 psBitMaskTest(const psBitMask *checkMask, //!< Bit mask to check
-	      int bit			//!< Bit to check
+              int bit                   //!< Bit to check
     );
 \end{verbatim}
@@ -1117,8 +1117,8 @@
 /** apply the given operator to two bit masks */
 psBitMask *
-psBitMaskOp(psBitMask *outMask,		//!< Output bit mask or NULL
-	    const psBitMask *restrict inMask1, //!< Input bit mask 1
-	    char *operator,		//!< bit mask operator (AND, OR, XOR)
-	    const psBitMask *restrict inMask2 //!< Input bit mask 2
+psBitMaskOp(psBitMask *outMask,         //!< Output bit mask or NULL
+            const psBitMask *restrict inMask1, //!< Input bit mask 1
+            char *operator,             //!< bit mask operator (AND, OR, XOR)
+            const psBitMask *restrict inMask2 //!< Input bit mask 2
     );
 \end{verbatim}
@@ -1176,6 +1176,6 @@
 /** create a psType-ed structure from a specified type  */
 p_ps_Scalar *
-psScalarType (char *mode, 		///< type description 
-	      ...			///< value (or values) of specified types
+psScalarType (char *mode,               ///< type description 
+              ...                       ///< value (or values) of specified types
 );
 \end{verbatim}
@@ -1185,8 +1185,8 @@
     psType type;
     union {
-	int i;
-	float f;
-	double d;
-	complex float c;
+        int i;
+        float f;
+        double d;
+        complex float c;
     }
 } p_psScalar;
@@ -1213,6 +1213,6 @@
 /** Sort an array. Inputs not restrict-ed to allow sort in place */
 psFloatArray *
-psSort(psFloatArray *out,		//!< Sorted array to return. May be NULL
-       const psFloatArray *myArray	//!< Array to sort
+psSort(psFloatArray *out,               //!< Sorted array to return. May be NULL
+       const psFloatArray *myArray      //!< Array to sort
     );
 \end{verbatim}
@@ -1226,6 +1226,6 @@
 /** Sort an array, along with some other stuff.  Returns an index array */
 psIntArray *
-psSortIndex(psIntArray *restrict out;	//!< Output index array (may be NULL)
-	    const psFloatArray *restrict myArray //!< Array to sort
+psSortIndex(psIntArray *restrict out;   //!< Output index array (may be NULL)
+            const psFloatArray *restrict myArray //!< Array to sort
     );
 \end{verbatim}
@@ -1267,9 +1267,9 @@
 psStats *
 psArrayStats(const psFloatArray *restrict myArray, //!< Array to be analysed
-	     const psIntArray *restrict maskArray, //!< Ignore elements where (maskArray & maskVal) != 0
-						   //!< May be NULL
-	     unsigned int maskVal,	//!< Only mask elements with one of these bits set in maskArray
-	     psStats *stats		//!< stats structure defines stats to be calculated and how
-	     );
+             const psIntArray *restrict maskArray, //!< Ignore elements where (maskArray & maskVal) != 0
+                                                   //!< May be NULL
+             unsigned int maskVal,      //!< Only mask elements with one of these bits set in maskArray
+             psStats *stats             //!< stats structure defines stats to be calculated and how
+             );
 \end{verbatim}
 
@@ -1280,32 +1280,32 @@
 /** generic statistics structure */
 typedef struct {
-    double sampleMean;			//<! formal mean of sample
-    double sampleMedian;		//<! formal median of sample
-    double sampleMode;			//!< Formal mode of sample
-    double sampleStdev;			//<! standard deviation of sample
-    double sampleUQ;			//<! upper quartile of sample
-    double sampleLQ;			//<! lower quartile of sample
-    double robustMean;			//<! robust mean of array
-    double robustMeanError;		//<! error on robust mean
-    int    robustMeanNvalues;		//<! number of measurements used for robust mean
-    double robustMedian;		//<! robust median of array
-    double robustMedianError;		//<! error on robust median
-    int    robustMedianNvalues;		//<! number of measurements used for robust median
-    double robustMode;			//!< Robust mode of array
-    double robustModeErr;		//!< Error in robust mode
-    int    robustModeNvalues;		//!< Number of measurements used for robust mode
-    double robustStdev;			//<! robust standard deviation of array
-    double robustUQ;			//<! robust upper quartile
-    double robustLQ;			//<! robust lower quartile
-    double clippedMean;			//<! Nsigma clipped mean
-    double clippedMeanError;		//<! error on clipped mean
-    int    clippedMeanNvalues;		//<! number of data points used for clipped mean
-    double clippedStdev;		//!< standard deviation after clipping
-    double clipSigma;			//<! Nsigma used for clipping; user input
-    int    clipIter;			//!< Number of clipping iterations; user input
-    double min;				//<! minimum data value in array
-    double max;				//<! maximum data value in array
-    int    nValues;			//<! number of data values in array
-    psStatsOptions options;		//<! bitmask of calculated values
+    double sampleMean;                  //<! formal mean of sample
+    double sampleMedian;                //<! formal median of sample
+    double sampleMode;                  //!< Formal mode of sample
+    double sampleStdev;                 //<! standard deviation of sample
+    double sampleUQ;                    //<! upper quartile of sample
+    double sampleLQ;                    //<! lower quartile of sample
+    double robustMean;                  //<! robust mean of array
+    double robustMeanError;             //<! error on robust mean
+    int    robustMeanNvalues;           //<! number of measurements used for robust mean
+    double robustMedian;                //<! robust median of array
+    double robustMedianError;           //<! error on robust median
+    int    robustMedianNvalues;         //<! number of measurements used for robust median
+    double robustMode;                  //!< Robust mode of array
+    double robustModeErr;               //!< Error in robust mode
+    int    robustModeNvalues;           //!< Number of measurements used for robust mode
+    double robustStdev;                 //<! robust standard deviation of array
+    double robustUQ;                    //<! robust upper quartile
+    double robustLQ;                    //<! robust lower quartile
+    double clippedMean;                 //<! Nsigma clipped mean
+    double clippedMeanError;            //<! error on clipped mean
+    int    clippedMeanNvalues;          //<! number of data points used for clipped mean
+    double clippedStdev;                //!< standard deviation after clipping
+    double clipSigma;                   //<! Nsigma used for clipping; user input
+    int    clipIter;                    //!< Number of clipping iterations; user input
+    double min;                         //<! minimum data value in array
+    double max;                         //<! maximum data value in array
+    int    nValues;                     //<! number of data values in array
+    psStatsOptions options;             //<! bitmask of calculated values
 } psStats;
 \end{verbatim}
@@ -1320,9 +1320,9 @@
 /** Histograms */
 typedef struct {
-    const psFloatArray *restrict lower;	//!< Lower bounds for the bins
+    const psFloatArray *restrict lower; //!< Lower bounds for the bins
     const psFloatArray *restrict upper; //!< Upper bounds for the bins
-    psIntArray *nums;			//!< Number in each of the bins
-    const float minVal, maxVal;		//!< Minimum and maximum values
-    int minNum, maxNum;			//!< Number below the minimum and above the maximum
+    psIntArray *nums;                   //!< Number in each of the bins
+    const float minVal, maxVal;         //!< Minimum and maximum values
+    int minNum, maxNum;                 //!< Number below the minimum and above the maximum
 } psHistogram;
 \end{verbatim}
@@ -1336,7 +1336,7 @@
 /** Constructor */
 psHistogram *
-psHistogramAlloc(float lower,		//!< Lower limit for the bins
-	         float upper,		//!< Upper limit for the bins
-	         float size		//!< Size of the bins
+psHistogramAlloc(float lower,           //!< Lower limit for the bins
+                 float upper,           //!< Upper limit for the bins
+                 float size             //!< Size of the bins
     );
 \end{verbatim}
@@ -1346,7 +1346,7 @@
 psHistogram *
 psHistogramAllocGeneric(const psFloatArray *restrict lower, //!< Lower bounds for the bins
-		        const psFloatArray *restrict upper, //!< Upper bounds for the bins
-		        float minVal,	//!< Minimum value
-		        float maxVal	//!< Maximum value
+                        const psFloatArray *restrict upper, //!< Upper bounds for the bins
+                        float minVal,   //!< Minimum value
+                        float maxVal    //!< Maximum value
     );
 \end{verbatim}
@@ -1369,6 +1369,6 @@
 /** A matrix */
 typedef struct {
-    int xSize, ySize;			//!< Dimensions in x and y
-    float *restrict *restrict value;	//!< Values in matrix
+    int xSize, ySize;                   //!< Dimensions in x and y
+    float *restrict *restrict value;    //!< Values in matrix
 } psMatrix;
 \end{verbatim}
@@ -1379,7 +1379,7 @@
 /** Constructor */
 psMatrix *
-psMatrixAlloc(int Xdimen,			//!< x dimension of new matrix
-	      int Ydimen			//!< y dimension of new matrix
-	      );
+psMatrixAlloc(int Xdimen,                       //!< x dimension of new matrix
+              int Ydimen                        //!< y dimension of new matrix
+              );
 \end{verbatim}
 
@@ -1387,6 +1387,6 @@
 /** Destructor */
 void
-psMatrixFree(psMatrix *restrict myMatrix	//!< Matrix to destroy
-	     );
+psMatrixFree(psMatrix *restrict myMatrix        //!< Matrix to destroy
+             );
 \end{verbatim}
 
@@ -1404,7 +1404,7 @@
 /** Invert matrix.  Not using restrict, to allow inversion to be done in-place */
 psMatrix *
-psMatrixInvert(psMatrix *out,		//!< Matrix to return, or NULL
-	       const psMatrix *myMatrix, //!< Matrix to be inverted
-	       float *restrict determinant //!< Determinant to return, or NULL
+psMatrixInvert(psMatrix *out,           //!< Matrix to return, or NULL
+               const psMatrix *myMatrix, //!< Matrix to be inverted
+               float *restrict determinant //!< Determinant to return, or NULL
     );
 \end{verbatim}
@@ -1414,5 +1414,5 @@
 float
 psMatrixDeterminant(const psMatrix *restrict myMatrix //!< Matrix to get determinant for
-		    );
+                    );
 \end{verbatim}
 
@@ -1420,9 +1420,9 @@
 /** Matrix operations */
 psMatrix *
-psMatrixOp(psMatrix *out,		//!< Matrix to return, or NULL
-	   const psMatrix *matrix1,	//!< Matrix 1
-	   const char *op,		//!< Operation to perform
-	   const psMatrix *matrix2	//!< Matrix 2
-	   );
+psMatrixOp(psMatrix *out,               //!< Matrix to return, or NULL
+           const psMatrix *matrix1,     //!< Matrix 1
+           const char *op,              //!< Operation to perform
+           const psMatrix *matrix2      //!< Matrix 2
+           );
 \end{verbatim}
 
@@ -1430,7 +1430,7 @@
 /** Transpose Matrix */
 psMatrix *
-psMatrixTranspose(psMatrix *out,	//!< Matrix to return, or NULL
-		  const psMatrix *myMatrix //!< Matrix to transpose
-		  );
+psMatrixTranspose(psMatrix *out,        //!< Matrix to return, or NULL
+                  const psMatrix *myMatrix //!< Matrix to transpose
+                  );
 \end{verbatim}
 
@@ -1438,5 +1438,5 @@
 /** Convert matrix to vector.  Intended for a 1-d matrix. */
 psVector *
-psMatrixToVector(psMatrix *myMatrix	//!< Matrix to convert
+psMatrixToVector(psMatrix *myMatrix     //!< Matrix to convert
     );
 \end{verbatim}
@@ -1458,7 +1458,7 @@
 /** Return Fourier Transform of an array */
 psComplexArray *
-psRealFFT(psComplexArray *restrict out,	//!< Output array to be returned; may be NULL
-	  const psFloatArray *restrict myArray //!< Input array
-	  );
+psRealFFT(psComplexArray *restrict out, //!< Output array to be returned; may be NULL
+          const psFloatArray *restrict myArray //!< Input array
+          );
 \end{verbatim}
 
@@ -1467,7 +1467,7 @@
 psComplexArray *
 psComplexFFT(psComplexArray *restrict out, //!< Output array to be returned; may be NULL
-	     const psComplexArray *restrict myArray, //!< Input array
-	     int sign			//!< +1 or -1 to indicate direction of FT
-	     );
+             const psComplexArray *restrict myArray, //!< Input array
+             int sign                   //!< +1 or -1 to indicate direction of FT
+             );
 \end{verbatim}
 
@@ -1475,7 +1475,7 @@
 /** Return Power spectrum of a array */
 psFloatArray *
-psPowerSpec(psFloatArray *restrict out,	//!< Output array to be returned
-	    const psFloatArray *restrict myArray //!< Input array
-	    );
+psPowerSpec(psFloatArray *restrict out, //!< Output array to be returned
+            const psFloatArray *restrict myArray //!< Input array
+            );
 \end{verbatim}
 
@@ -1491,8 +1491,8 @@
     is not a Gaussian deviate.  The evaluated Gaussian is: \f[ exp(-\frac{(x-mean)^2}{2\sigma^2}) \f] */
 float
-psGaussian(float x,			//!< Value at which to evaluate
-	   float mean,			//!< Mean for the Gaussian
-	   float stddev			//!< Standard deviation for the Gaussian
-	   );
+psGaussian(float x,                     //!< Value at which to evaluate
+           float mean,                  //!< Mean for the Gaussian
+           float stddev                 //!< Standard deviation for the Gaussian
+           );
 \end{verbatim}
 
@@ -1509,8 +1509,8 @@
 /** One-dimensional polynomial */
 typedef struct {
-    int n;				//!< Number of terms
-    float *restrict coeff;		//!< Coefficients
-    float *restrict coeffErr;		//!< Error in coefficients
-    char *restrict mask;		//!< Coefficient mask
+    int n;                              //!< Number of terms
+    float *restrict coeff;              //!< Coefficients
+    float *restrict coeffErr;           //!< Error in coefficients
+    char *restrict mask;                //!< Coefficient mask
 } psPolynomial1D;
 \end{verbatim}
@@ -1519,8 +1519,8 @@
 /** Two-dimensional polynomial */
 typedef struct {
-    int nX, nY;				//!< Number of terms in x and y
-    float *restrict *restrict coeff;	//!< Coefficients
-    float *restrict *restrict coeffErr;	//!< Error in coefficients
-    char *restrict *restrict mask;	//!< Coefficients mask
+    int nX, nY;                         //!< Number of terms in x and y
+    float *restrict *restrict coeff;    //!< Coefficients
+    float *restrict *restrict coeffErr; //!< Error in coefficients
+    char *restrict *restrict mask;      //!< Coefficients mask
 } psPolynomial2D;
 \end{verbatim}
@@ -1531,8 +1531,8 @@
 /** Double-precision one-dimensional polynomial */
 typedef struct {
-    int n;				//!< Number of terms
-    double *restrict coeff;		//!< Coefficients
-    double *restrict coeffErr;		//!< Error in coefficients
-    char *restrict mask;		//!< Coefficient mask
+    int n;                              //!< Number of terms
+    double *restrict coeff;             //!< Coefficients
+    double *restrict coeffErr;          //!< Error in coefficients
+    char *restrict mask;                //!< Coefficient mask
 } psDPolynomial1D;
 \end{verbatim}
@@ -1541,8 +1541,8 @@
 /** Double-precision two-dimensional polynomial */
 typedef struct {
-    int nX, nY;				//!< Number of terms in x and y
-    double *restrict *restrict coeff;	//!< Coefficients
+    int nX, nY;                         //!< Number of terms in x and y
+    double *restrict *restrict coeff;   //!< Coefficients
     double *restrict *restrict coeffErr; //!< Error in coefficients
-    char *restrict *restrict mask;	//!< Coefficients mask
+    char *restrict *restrict mask;      //!< Coefficients mask
 } psDPolynomial2D;
 \end{verbatim}
@@ -1565,8 +1565,8 @@
 /** Evaluate 2D polynomial (double precision) */
 double
-psEvalDPolynomial2D(double x,		//!< Value x at which to evaluate
-		    double y,		//!< Value y at which to evaluate
-		    const psDPolynomial2D *restrict myPoly //!< Coefficients for the polynomial
-		    );
+psEvalDPolynomial2D(double x,           //!< Value x at which to evaluate
+                    double y,           //!< Value y at which to evaluate
+                    const psDPolynomial2D *restrict myPoly //!< Coefficients for the polynomial
+                    );
 \end{verbatim}
 
@@ -1583,7 +1583,7 @@
 /** Minimize a particular function */
 psFloatArray *
-psMinimize(float (*myFunction)(const psFloatArray *restrict),	//!< Function to minimize
-	   psFloatArray *restrict initialGuess //!< Initial guess
-	   );
+psMinimize(float (*myFunction)(const psFloatArray *restrict),   //!< Function to minimize
+           psFloatArray *restrict initialGuess //!< Initial guess
+           );
 \end{verbatim}
 
@@ -1592,12 +1592,12 @@
 psFloatArray *
 psMinimizeChi2(float (*evalModel)(const psFloatArray *restrict,
-				  const psFloatArray *restrict), //!< Model to fit; receives domain and
-								 //!< parameters
-	       const psFloatArray *restrict domain, //!< The domain values for the corresponding measurements
-	       const psFloatArray *restrict data, //!< Data to fit
-	       const psFloatArray *restrict errors, //!< Errors in the data
-	       psFloatArray *restrict initialGuess, //!< Initial guess
-	       const psIntArray *restrict guessMask //!< 1 = fit for parameter, 0 = hold parameter constant
-	       );
+                                  const psFloatArray *restrict), //!< Model to fit; receives domain and
+                                                                 //!< parameters
+               const psFloatArray *restrict domain, //!< The domain values for the corresponding measurements
+               const psFloatArray *restrict data, //!< Data to fit
+               const psFloatArray *restrict errors, //!< Errors in the data
+               psFloatArray *restrict initialGuess, //!< Initial guess
+               const psIntArray *restrict guessMask //!< 1 = fit for parameter, 0 = hold parameter constant
+               );
 \end{verbatim}
 
@@ -1606,5 +1606,5 @@
 psFloatArray *
 psGetArrayPolynomial(const psFloatArray *restrict ord, //!< Ordinates (or NULL to just use the indices)
-		     const psFloatArray *restrict coord //!< Coordinates
+                     const psFloatArray *restrict coord //!< Coordinates
     );
 \end{verbatim}
@@ -1707,5 +1707,5 @@
 \begin{verbatim}
 void 
-psImageFree(psImage *restrict image	///< free this image
+psImageFree(psImage *restrict image     ///< free this image
     );
 \end{verbatim}
@@ -2037,9 +2037,9 @@
 definitions do not influence the understanding of this document.
 
-A ``frame'' is a read of the detector.
+A ``readout'' is a read of the detector.
 
 A ``cell'' is defined as the smallest element of the detector readout;
 usually associated with an amplifier.  Correspondingly, each cell has
-its own overscan region.  There may be multiple frames in a cell if
+its own overscan region.  There may be multiple readouts in a cell if
 the cell was used to provide fast guiding.
 
@@ -2055,4 +2055,9 @@
 2k$.  There would be eight chips, each consisting of two cells, and
 the focal plane consists of these eight chips.
+
+As another example, consider an observation by PS1.  The focal plane
+would consist of 60 chips, each of which consist of 64 cells (or less;
+a few cells may be dead).  Some cells (those containing guide stars
+for the orthogonal transfer) will contain multiple readouts.
 
 \subsubsection{Coordinate frames}
@@ -2094,22 +2099,22 @@
 well as the pixel data.
 
-\subsubsection{A Frame}
-
-A frame is the result of a single read of a cell (or a portion
+\subsubsection{A Readout}
+
+A readout is the result of a single read of a cell (or a portion
 thereof).  It contains a pointer to the pixel data, a separate pointer
 to the overscan pixels, and additional pointers to the objects found
-in the frame, and the frame metadata.  It also contains the offset
+in the readout, and the readout metadata.  It also contains the offset
 from the lower-left corner of the chip, in the case that the CCD was
 windowed.
 
 \begin{verbatim}
-/** a Frame: a collection of pixels */
+/** a Readout: a collection of pixels */
 typedef struct {
-    int x0, y0;				//!< Offset from the lower-left corner
+    int x0, y0;                         //!< Offset from the lower-left corner
     psImage *image;                     ///< imaging area of cell 
-    psDlist *objects;			///< objects derived from cell
+    psDlist *objects;                   ///< objects derived from cell
     psImage *overscan;                  ///< bias region (subimage) of cell
-    psMetaDataSet *md;			//!< Frame-level metadata
-} psFrame;
+    psMetaDataSet *md;                  //!< Readout-level metadata
+} psReadout;
 \end{verbatim}    
 
@@ -2117,5 +2122,5 @@
 \subsubsection{A Cell}
 
-A cell consists of one or more frames (usually only one except in the
+A cell consists of one or more readouts (usually only one except in the
 case that the cell has been used for fast guiding).  It also contains
 a pointer to the cell metadata, and a pointer to its parent chip.  On
@@ -2133,17 +2138,17 @@
 
 \begin{verbatim}
-/** a Cell: a collection of frames.
+/** a Cell: a collection of readouts.
  */
 typedef struct {
-    int nFrames;			///< number of frames in this cell realization; each may have its own
-					///< image, objects and overscan.
-    struct psFrame *frames;		//!< Frames from the cell
-    psMetaDataSet *md;			///< Cell-level metadata
-
-    psCoordXform *cellToChip;		///< Transformations from cell coordinates to chip coordinates
-    psCoordXform *cellToFPA;		///< Transformations from cell coordinates to FPA coordinates
-    psCoordXform *cellToSky;		///< Quick and Dirty transformations from cell coordinates to sky
-
-    struct psChip  *parentChip;		///< chip which contains this cell
+    int nReadouts;                      ///< number of readouts in this cell realization; each may have its own
+                                        ///< image, objects and overscan.
+    struct psReadout *readouts;         //!< Readouts from the cell
+    psMetaDataSet *md;                  ///< Cell-level metadata
+
+    psCoordXform *cellToChip;           ///< Transformations from cell coordinates to chip coordinates
+    psCoordXform *cellToFPA;            ///< Transformations from cell coordinates to FPA coordinates
+    psCoordXform *cellToSky;            ///< Quick and Dirty transformations from cell coordinates to sky
+
+    struct psChip  *parentChip;         ///< chip which contains this cell
 } psCell;
 \end{verbatim}
@@ -2169,8 +2174,8 @@
     struct psCell *cells;               ///< Cells in the Chip
 
-    psMetaDataSet *md;			///< Chip-level metadata
+    psMetaDataSet *md;                  ///< Chip-level metadata
     psCoordXform *chipToFPA;            ///< Transformations from chip coordinates to FPA coordinates
 
-    struct psFPA *parentFPA;		///< FPA which contains this chip
+    struct psFPA *parentFPA;            ///< FPA which contains this chip
 } psChip;
 \end{verbatim}
@@ -2202,10 +2207,10 @@
     int nChips;                         ///< Number of Cells assigned
     int nAlloc;                         ///< Number of Cells available
-    struct psChip *chips;		///< Chips in the Focal Plane Array
-
-    psMetaDataSet *md;			///< FPA-level metadata 
-    psDistortion *TPtoFP;		///< Transformation term from 
-    psDistortion *FPtoTP;		///< Transformation term from 
-    psFixedPattern *pattern;		//!< Fixed pattern residual offsets
+    struct psChip *chips;               ///< Chips in the Focal Plane Array
+
+    psMetaDataSet *md;                  ///< FPA-level metadata 
+    psDistortion *TPtoFP;               ///< Transformation term from 
+    psDistortion *FPtoTP;               ///< Transformation term from 
+    psFixedPattern *pattern;            //!< Fixed pattern residual offsets
     psExposure *exp;                    ///< information about this exposure
     psPhotSystem colorPlus, colorMinus; ///< Colour reference
@@ -2289,8 +2294,8 @@
 /** The fixed pattern residual offsets.  These are specified via a coarse grid of x and y offsets. */
 typedef struct {
-    int nX, nY;				//!< Number of elements in x and y
-    double x0, y0;			//!< Position of the lower-left corner of the grid on the focal plane
-    double xScale, yScale;		//!< Scale of the grid
-    double **x, **y;			//!< The grid of offsets in x and y
+    int nX, nY;                         //!< Number of elements in x and y
+    double x0, y0;                      //!< Position of the lower-left corner of the grid on the focal plane
+    double xScale, yScale;              //!< Scale of the grid
+    double **x, **y;                    //!< The grid of offsets in x and y
 } psFixedPattern;
 \end{verbatim}
@@ -2319,5 +2324,5 @@
                 float humidity,         //!< Relative humidity
                 float exptime           //!< Exposure time
-		);
+                );
 \end{verbatim}
 
@@ -2325,7 +2330,10 @@
 \subsubsection{Finding}
 
-We require functions to return the structure containing given coordinates.
-For example, we want the chip that corresponds to the focal plane coordinates
-$(p,q) = (-1.234,+5.678)$.
+We require functions to return the structure containing given
+coordinates.  For example, we want the chip that corresponds to the
+focal plane coordinates $(p,q) = (-1.234,+5.678)$.  These routines
+handle the one-to-many problem --- i.e., for one given focal plane
+coordinate, there are many chips that this coordinate may be
+correspond to; these functions will select the correct one.
 
 
@@ -2333,7 +2341,7 @@
 /** returns Chip in FPA which contains the given FPA coordinate */
 psChip *
-psChipInFPA (psFPA *fpa, 		///< FPA description
-	     psCoord *coord		///< coordinate in FPA
-	     );
+psChipInFPA (psFPA *fpa,                ///< FPA description
+             psCoord *coord             ///< coordinate in FPA
+             );
 \end{verbatim}
 
@@ -2341,7 +2349,7 @@
 /** returns Cell in Chip which contains the given chip coordinate */
 psCell *
-psCellInChip (psChip *chip, 		///< chip description
-	      psCoord *coord		///< coordinate in chip
-	      );
+psCellInChip (psChip *chip,             ///< chip description
+              psCoord *coord            ///< coordinate in chip
+              );
 \end{verbatim}
 
@@ -2353,8 +2361,8 @@
 /** Return the cell in FPA which contains the given FPA coordinates */
 psCell *
-psCellInFPA(psCell *out,		//!< Cell to return, or NULL
-	    psFPA *fpa,			//!< FPA description
-	    psCoord *coord		//!< Coordinate in FPA
-	    );
+psCellInFPA(psCell *out,                //!< Cell to return, or NULL
+            psFPA *fpa,                 //!< FPA description
+            psCoord *coord              //!< Coordinate in FPA
+            );
 \end{verbatim}
 
@@ -2392,8 +2400,8 @@
 /** returns Chip in FPA which contains the given FPA coordinate */
 psChip *
-psChipInFPA (psChip *out,		//!< Chip to return, or NULL
-	     psFPA *fpa, 		///< FPA description
-	     psCoord *coord		///< coordinate in FPA
-	     );
+psChipInFPA (psChip *out,               //!< Chip to return, or NULL
+             psFPA *fpa,                ///< FPA description
+             psCoord *coord             ///< coordinate in FPA
+             );
 \end{verbatim}
 
@@ -2401,8 +2409,8 @@
 /** returns Cell in Chip which contains the given chip coordinate */
 psCell *
-psCellInChip(psCell *out,		//!< Cell to return, or NULL
-	     psChip *chip, 		///< chip description
-	     psCoord *coord		///< coordinate in chip
-	     );
+psCellInChip(psCell *out,               //!< Cell to return, or NULL
+             psChip *chip,              ///< chip description
+             psCoord *coord             ///< coordinate in chip
+             );
 \end{verbatim}
 
@@ -2410,8 +2418,8 @@
 /** Return the cell in FPA which contains the given FPA coordinates */
 psCell *
-psCellInFPA(psCell *out,		//!< Cell to return, or NULL
-	    psFPA *fpa,			//!< FPA description
-	    psCoord *coord		//!< Coordinate in FPA
-	    );
+psCellInFPA(psCell *out,                //!< Cell to return, or NULL
+            psFPA *fpa,                 //!< FPA description
+            psCoord *coord              //!< Coordinate in FPA
+            );
 \end{verbatim}
 
@@ -2419,8 +2427,8 @@
 /** Convert (RA,Dec) to cell and cell coordinates */
 psCoord *
-psCoordSkyToCell(psCoord *out,		//!< Coordinates to return, or NULL
-		 psCell *cell,		//!< Cell to return
-		 const psFPA *fpa	//!< FPA description
-		 );
+psCoordSkyToCell(psCoord *out,          //!< Coordinates to return, or NULL
+                 psCell *cell,          //!< Cell to return
+                 const psFPA *fpa       //!< FPA description
+                 );
 \end{verbatim}
 
@@ -2428,8 +2436,8 @@
 /** Convert cell and cell coordinate to (RA,Dec) */
 psCoord *
-psCoordCellToSky(psCoord *out,		//!< Coordinates to return, or NULL
-		 const psCell *cell,	//!< Cell to get coordinates for
-		 psCoord *coord		//!< cell coordinates to transform
-		 );
+psCoordCellToSky(psCoord *out,          //!< Coordinates to return, or NULL
+                 const psCell *cell,    //!< Cell to get coordinates for
+                 psCoord *coord         //!< cell coordinates to transform
+                 );
 \end{verbatim}
 
@@ -2437,8 +2445,8 @@
 /** Quick and dirty cell to (RA,Dec) --- employs cellToSky transformation */
 psCoord *
-psCoordCellToSkyQuick(psCoord *out,	//!< Coordinates to return, or NULL
-		      const psCell *cell, //!< Cell description
-		      psCoord *coord	//!< cell coordinates to transform
-		      );
+psCoordCellToSkyQuick(psCoord *out,     //!< Coordinates to return, or NULL
+                      const psCell *cell, //!< Cell description
+                      psCoord *coord    //!< cell coordinates to transform
+                      );
 \end{verbatim}
 
@@ -2446,8 +2454,8 @@
 /** Convert (RA,Dec) to tangent plane coords */
 psCoord *
-psCoordSkyToTP(psCoord *out,		//!< Coordinates to return, or NULL
-	       psexposure *exp,		//!< Exposure description
-	       psCoord *coord		//!< input Sky coordinate
-	       );
+psCoordSkyToTP(psCoord *out,            //!< Coordinates to return, or NULL
+               psexposure *exp,         //!< Exposure description
+               psCoord *coord           //!< input Sky coordinate
+               );
 \end{verbatim}
 
@@ -2455,8 +2463,8 @@
 /** Convert tangent plane coords to focal plane coordinates */
 psCoord *
-psCoordTPtoFPA(psCoord *out,		//!< Coordinates to return, or NULL
-	       const psFPA *fpa,	//!< FPA description
-	       psCoord *coord		//!< input TP coordinate
-	       );
+psCoordTPtoFPA(psCoord *out,            //!< Coordinates to return, or NULL
+               const psFPA *fpa,        //!< FPA description
+               psCoord *coord           //!< input TP coordinate
+               );
 \end{verbatim}
 
@@ -2464,9 +2472,9 @@
 /** converts the specified FPA coord to the coord on the given Chip */
 psCoord *
-psCoordFPAtoChip (psCoord *out,		//!< Coordinates to return, or NULL
-		  psFPA *fpa, 		///< FPA description
-		  psChip *chip,		///< Chip of interest
-		  psCoord *coord	///< input FPA coordinate
-		  ); 
+psCoordFPAtoChip (psCoord *out,         //!< Coordinates to return, or NULL
+                  psFPA *fpa,           ///< FPA description
+                  psChip *chip,         ///< Chip of interest
+                  psCoord *coord        ///< input FPA coordinate
+                  ); 
 \end{verbatim}
 
@@ -2474,9 +2482,9 @@
 /** converts the specified Chip coord to the coord on the given Cell */
 psCoord *
-psCoordChiptoCell (psCoord *out,	//!< Coordinates to return, or NULL
-		   psChip *chip,	///< Chip description
-		   psCell *cell, 	///< Cell of interest
-		   psCoord *coord	///< input Chip coordinate
-		   );
+psCoordChiptoCell (psCoord *out,        //!< Coordinates to return, or NULL
+                   psChip *chip,        ///< Chip description
+                   psCell *cell,        ///< Cell of interest
+                   psCoord *coord       ///< input Chip coordinate
+                   );
 \end{verbatim}
 
@@ -2484,8 +2492,8 @@
 /** converts the specified Cell coord to the coord on the parent Chip */
 psCoord *
-psCoordCelltoChip (psCoord *out,	//!< Coordinates to return, or NULL
-		   psCell *cell, 	///< Cell description
-		   psCoord *coord	///< input Cell coordinate
-		   );
+psCoordCelltoChip (psCoord *out,        //!< Coordinates to return, or NULL
+                   psCell *cell,        ///< Cell description
+                   psCoord *coord       ///< input Cell coordinate
+                   );
 \end{verbatim}
 
@@ -2493,8 +2501,8 @@
 /** converts the specified Chip coord to the coord on the parent FPA */
 psCoord *
-psCoordChiptoFPA (psCoord *out,		//!< Coordinates to return, or NULL
-		  psChip *chip, 	///< Chip description
-		  psCoord *coord	///< input Chip coordinate
-		  );
+psCoordChiptoFPA (psCoord *out,         //!< Coordinates to return, or NULL
+                  psChip *chip,         ///< Chip description
+                  psCoord *coord        ///< input Chip coordinate
+                  );
 \end{verbatim}
 
@@ -2502,8 +2510,8 @@
 /** Convert focal plane coords to tangent plane coordinates */
 psCoord *
-psCoordFPAToTP(psCoord *out,		//!< Coordinates to return, or NULL
-	       psFPA *fpa,		//!< FPA description
-	       psCoord *coord		//!< input FPA coordinate
-	       );
+psCoordFPAToTP(psCoord *out,            //!< Coordinates to return, or NULL
+               psFPA *fpa,              //!< FPA description
+               psCoord *coord           //!< input FPA coordinate
+               );
 \end{verbatim}
 
@@ -2511,8 +2519,8 @@
 /** Convert tangent plane coords to (RA,Dec) */
 psCoord *
-psCoordTPtoSky(psCoord *out,		//!< Coordinates to return, or NULL
-	       psExposure *exp,		//!< Exposure description
-	       psCoord *coord		//!< input TP coordinate
-	       );
+psCoordTPtoSky(psCoord *out,            //!< Coordinates to return, or NULL
+               psExposure *exp,         //!< Exposure description
+               psCoord *coord           //!< input TP coordinate
+               );
 \end{verbatim}
 
@@ -2520,8 +2528,8 @@
 /** Convert Cell coords to FPA coordinates */
 psCoord *
-psCoordCellToFPA(psCoord *out,		//!< Coordinates to return, or NULL
-		 psCell *cell,		//!< Cell description
-		 psCoord *coord		//!< Input cell coordinates
-		 );
+psCoordCellToFPA(psCoord *out,          //!< Coordinates to return, or NULL
+                 psCell *cell,          //!< Cell description
+                 psCoord *coord         //!< Input cell coordinates
+                 );
 \end{verbatim}
 
@@ -2536,7 +2544,7 @@
 /** Get the airmass for a given position and sidereal time */
 float
-psGetAirmass(const psCoord *coord,	//!< Position on the sky
-             double siderealTime,	//!< Sidereal time
-	     float height		//!< Height above sea level
+psGetAirmass(const psCoord *coord,      //!< Position on the sky
+             double siderealTime,       //!< Sidereal time
+             float height               //!< Height above sea level
              );
 \end{verbatim}
@@ -2545,5 +2553,5 @@
 /** Get the parallactic angle for a given position and sidereal time */
 float
-psGetParallactic(const psCoord *coord,	//!< Position on the sky
+psGetParallactic(const psCoord *coord,  //!< Position on the sky
                  double siderealTime    //!< Sidereal time
                  );
@@ -2554,10 +2562,16 @@
 float
 psGetRefraction(float colour,           //!< Colour of object
-		psPhotSystem colorPlus,	///< Colour reference
-		psPhotSystem colorMinus, ///< Colour reference
-                const psExposure *exp	//!< Telescope pointing information, for airmass, temp and pressure
-		);
-\end{verbatim}
-
+                psPhotSystem colorPlus, ///< Colour reference
+                psPhotSystem colorMinus, ///< Colour reference
+                const psExposure *exp   //!< Telescope pointing information, for airmass, temp and pressure
+                );
+\end{verbatim}
+
+\begin{verbatim}
+/** Calculate the parallax factor */
+double
+psGetParallaxFactor(const psExposure *exp //!< Exposure details
+    );
+\end{verbatim}
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@@ -2649,6 +2663,6 @@
 \begin{verbatim}
 typedef struct {
-    psDlist *list;			// list of psMetaDataItem
-    psHash *table;			// hash table of the same metadata
+    psDlist *list;                      // list of psMetaDataItem
+    psHash *table;                      // hash table of the same metadata
 } psMetaDataSet;
 \end{verbatim}
@@ -2732,15 +2746,15 @@
 \begin{verbatim}
 psMetaDataItem *psMetaDataItemAlloc(
-    psMetaDataType type,		// type of this piece of metadata
-    const void *val,			// value of new item
-    					// N.b. a pointer even if the item
-    					// is of type e.g. int
-    const char *comment,		// comment associated with item
-    const char *name,			// name of new item of metadata (may be an sprintf format)
-    ...);				// possible arguments for name format
+    psMetaDataType type,                // type of this piece of metadata
+    const void *val,                    // value of new item
+                                        // N.b. a pointer even if the item
+                                        // is of type e.g. int
+    const char *comment,                // comment associated with item
+    const char *name,                   // name of new item of metadata (may be an sprintf format)
+    ...);                               // possible arguments for name format
 
 void psMetaDataItemFree(psMetaDataItem *ms); // piece of metadata to destroy
 
-psMetaDataSet *psMetaDataSetAlloc(void);	  // make a new set of metadata
+psMetaDataSet *psMetaDataSetAlloc(void);          // make a new set of metadata
 void psMetaDataSetDel(psMetaDataSet *ms); // destroy a set of metadata
 
@@ -2756,6 +2770,6 @@
 psMetaDataItem *psMetaDataLookup(const psMetaDataSet *ms, const char *key);
 
-void psMetaDataItemPrint(FILE *fd,		// file descriptor to write to
-			 const psMetaDataItem *ms); // item of metadata to print
+void psMetaDataItemPrint(FILE *fd,              // file descriptor to write to
+                         const psMetaDataItem *ms); // item of metadata to print
 \end{verbatim}
 
@@ -2772,14 +2786,14 @@
 typedef union {
     struct {
-	double x;			//!< x position
-	double y;			//!< y position
-	double xErr;			//!< Error in x position
-	double yErr;			//!< Error in y position
+        double x;                       //!< x position
+        double y;                       //!< y position
+        double xErr;                    //!< Error in x position
+        double yErr;                    //!< Error in y position
     } xy;
     struct {
-	double r;			//!< RA
-	double d;			//!< Dec
-	double rErr;			//!< Error in RA
-	double dErr;			//!< Error in Dec
+        double r;                       //!< RA
+        double d;                       //!< Dec
+        double rErr;                    //!< Error in RA
+        double dErr;                    //!< Error in Dec
     } rd;
 } psCoord;
@@ -2821,5 +2835,5 @@
 /** apply the coordinate transformation to the given coordinate */
 psCoord *psCoordXformApply (psCoordXform *frame, ///< coordinate transformation
-			    psCoord *coords) ///< input coordiate
+                            psCoord *coords) ///< input coordiate
 ;
 \end{verbatim}
@@ -2828,7 +2842,7 @@
 /** apply the optical distortion to the given coordinate, magnitude, color */
 psCoord *psDistortionApply (psDistortion *pattern, ///< optical distortion pattern
-psCoord *coords,			///< input coordinate
-float mag,				///< magnitude of object
-float color)				///< color of object
+psCoord *coords,                        ///< input coordinate
+float mag,                              ///< magnitude of object
+float color)                            ///< color of object
 ;
 \end{verbatim}
@@ -2844,6 +2858,6 @@
 psCoord *
 psGetOffset(const psCoord *restrict position1, //!< Position 1
-	    const psCoord *restrict position2, //!< Position 2
-	    const char *type		//!< Type of offset: Linear, Spherical/Arcsec, Spherical/Degreees etc
+            const psCoord *restrict position2, //!< Position 2
+            const char *type            //!< Type of offset: Linear, Spherical/Arcsec, Spherical/Degreees etc
     );
 \end{verbatim}
@@ -2853,6 +2867,6 @@
 psCoord *
 psApplyOffset(const psCoord *restrict position, //!< Position
-	      const psCoord *restrict offset, //!< Offset
-	      const char *type		//!< Type of offset: Linear, Spherical/Arcsec, Spherical/Degreees etc
+              const psCoord *restrict offset, //!< Offset
+              const char *type          //!< Type of offset: Linear, Spherical/Arcsec, Spherical/Degreees etc
     );
 \end{verbatim}
@@ -2867,5 +2881,5 @@
 /** Get Sun Position */
 psCoord *
-psGetSunPos(float mjd)			//!< MJD to get position for
+psGetSunPos(float mjd)                  //!< MJD to get position for
 ;
 \end{verbatim}
@@ -2874,7 +2888,7 @@
 /** Get Moon position */
 psCoord *
-psGetMoonPos(float mjd,			//!< MJD to get position for
-	     double latitude,		//!< Latitude for apparent position
-	     double longitude)		//!< Longitude for apparent position
+psGetMoonPos(float mjd,                 //!< MJD to get position for
+             double latitude,           //!< Latitude for apparent position
+             double longitude)          //!< Longitude for apparent position
 ;
 \end{verbatim}
@@ -2883,5 +2897,5 @@
 /** Get Moon phase */
 float
-psGetMoonPhase(float mjd)		//!< MJD to get phase for
+psGetMoonPhase(float mjd)               //!< MJD to get phase for
 ;
 \end{verbatim}
@@ -2891,5 +2905,5 @@
 psCoord *
 psGetSolarSystemPos(char *solarSystemObject, //!< Named S.S. object
-		    float mjd)		//!< MJD to get position for
+                    float mjd)          //!< MJD to get position for
 ;
 \end{verbatim}
@@ -2955,9 +2969,9 @@
 \begin{verbatim}
 typedef struct {
-    int ID;				//!< ID number for this photometric system
-    char *name;				//!< Name of photometric system
-    char *camera;			//!< Camera for photometric system
-    char *filter;			//!< Filter used for photometric system
-    char *detector;			//!< Detector used for photometric system
+    int ID;                             //!< ID number for this photometric system
+    char *name;                         //!< Name of photometric system
+    char *camera;                       //!< Camera for photometric system
+    char *filter;                       //!< Filter used for photometric system
+    char *detector;                     //!< Detector used for photometric system
 } psPhotSystem;
 \end{verbatim}
@@ -2967,10 +2981,10 @@
 \begin{verbatim}
 typedef struct {
-    psPhotSystem src;			//!< Source photometric system
-    psPhotSystem dst;			//!< Destination photometric system
-    psPhotSystem pP, pM;		///< Primary colour reference
-    psPhotSystem sP, sM;		///< Secondary colour reference
-    float pA, sA;			///< Colour offset for primary and secondary references
-    psPolynomial3D transform;		//!< Transformation from source to destination
+    psPhotSystem src;                   //!< Source photometric system
+    psPhotSystem dst;                   //!< Destination photometric system
+    psPhotSystem pP, pM;                ///< Primary colour reference
+    psPhotSystem sP, sM;                ///< Secondary colour reference
+    float pA, sA;                       ///< Colour offset for primary and secondary references
+    psPolynomial3D transform;           //!< Transformation from source to destination
 } psPhotTransform;
 \end{verbatim}