Index: /trunk/archive/modules/include/phase2.h
===================================================================
--- /trunk/archive/modules/include/phase2.h	(revision 749)
+++ /trunk/archive/modules/include/phase2.h	(revision 749)
@@ -0,0 +1,156 @@
+#if !defined(PHASE2_H)
+#define PHASE2_H
+
+/** TO BE DEFINED:
+ *  1. Is it the responsibility of the phase2Whatever function to get the appropriate metadata, or should
+ *  it be supplied by the caller?
+ *  2. We want to carry masks around with each image.  Should these be separate psImages, or should we
+ *  incorporate the mask into the definition of psImage?
+ *  3. In some cases, we don't yet know the best algorithm.  How do we make these APIs robust against
+ *  variation of algorithms and input parameters?  For example, the number of parameters may vary.
+ *
+ *  Possible answers:
+ *  1. It's the responsibility of the caller to supply all relevant information.  This means that the
+ *  caller has to worry about getting the current best choice parameters, not the function itself; the
+ *  function can just be dumb, and do what it's told.
+ *  2. Masks will be provided as a member (psImage *mask) of psReadout.
+ *  3. Provide an "int algorithmNumber" plus "void *parameters" which will point to a struct containing the
+ *  parameters for the task.
+ *
+ */
+
+/************************************************************************************************************/
+
+/* Convolution */
+
+/** Returns the kernel of OT shifts made during the course of the exposure. */
+psImage *phase2GetKernel(psVector *shifts ///< List of OT shifts, from which the kernel will be calculated
+			 );
+
+/** Returns an image that is the result of convolving the input image with the specified kernel. */
+psReadout *phase2ConvolveWithKernel(psReadout *out, ///< Output image, or NULL
+				    const psReadout *in, ///< Input image to be convolved
+				    const psImage *kernel ///< Kernel by which to convolve
+				    );
+
+/************************************************************************************************************/
+
+/* Bias/overscan subtraction and trim */
+
+/** Image regions */
+typedef struct {
+    int x0, y0;				///< Offset to region
+    int nRow, nCol;			///< Size of region
+} psImageRegion;
+
+/** Array of image regions */
+typedef struct {
+    int n;				///< Number of image regions
+    psImageRegion *arr;			///< Array of image regions
+} psImageRegionArray;
+
+/** Subtracts an overscan and bias from the input image. */
+psReadout *phase2SubtractBias(psReadout *in, ///< Input image to be de-biased, and output
+			      const psImage *bias, ///< Bias (or dark) image to subtract
+			      const psImageRegionArray *regions, ///< Bias regions
+			      int overscanAxis, ///< 1 = subtract rows; 2 = subtract columns; -1 = fit rows;
+					   ///< -2 = fit columns; 0 = no overscan
+			      const psStatsOptions *stat, ///< Statistic to use
+			      const psPolynomial1D *polySpec ///< Polynomial specification to use for fit
+			      );
+
+/** Trims the input image to remove the edges corrupted by OT shifting, and the overscan. */
+psReadout *phase2Trim(psReadout *in,	///< Input image to be trimmed, and output
+		      const psImageRegion *region ///< Region to keep
+		      );
+
+/************************************************************************************************************/
+
+/* Reduce to counts proportional to photons */
+
+
+/** Applies the correction for detector non-linearity.  Non-linearity coefficients are determined from the
+ *  image metadata.
+ */
+psReadout *phase2CorrectNonLinearity(psReadout *in, ///< Input image to be corrected, and output
+				     psPolynomial1D *coeff ///< Polynomial with which to correct
+				     );
+
+/** Flat-fields the image. */
+psReadout *phase2FlatField(psReadout *in, ///< Input image to be flat-fielded, and output
+			   const psReadout *flat ///< Flat-field image
+			   );
+
+/** Subtracts the sky background. */
+psReadout *phase2SubtractSky(psReadout *in, ///< Input image to be sky-subtracted, and output
+			     psPolynomial2D *poly, ///< Polynomial specification, returns coeffcients
+			     const psImageArray *skyImages ///< Array of sky images
+			     );
+
+/************************************************************************************************************/
+
+/* Masking */
+
+/** Returns an image that has the bad pixels masked.  Also masks saturated pixels */
+psReadout *phase2MaskBadPixels(psReadout *in ///< Image to be masked, and output
+			       const psImage *mask ///< Bad pixel mask to apply
+			       );
+
+/** Masks Cosmic Rays on the input image on the basis of morphology. */
+psReadout *phase2MaskCRs(psReadout *in,	///< Input image to be masked, and output
+			 int algorithm,	///< Algorithm number to use
+			 const void *params ///< Parameters for algorithm
+			 );
+
+/** Masks optical defects in the input image */
+psChip *phase2MaskOpticalDefects(psChip *in, ///< Image to be masked (with astrometry), and output
+				 const psDlist *catalog, ///< Catalog stars nearby: a list of psObjects
+				 int grow ///< Number of pixels to grow
+				 );
+
+/************************************************************************************************************/
+
+/* Object finding */
+
+/** Measures the PSF on the input image.  Returns the PSF */
+psImage *phase2MeasurePSF(const psReadout *in, ///< Input image for which to measure the PSF
+			  int algorithm, ///< Algorithm number to use
+			  const void *params ///< Parameters for algorithm
+			  );
+
+/** Find and measure objects on the input image.  Fills in the "objects" member of the psReadout */
+psReadout *phase2GetObjects(psReadout *in, ///< Input image on which to find objects, and output
+			    const psImage *psf, ///< PSF to use to find objects
+			    const psVector *levels ///< Threshold levels (std dev.s)
+			    );
+
+/************************************************************************************************************/
+
+/* Astrometry */
+
+/** Corrects astrometry on the input chip */
+psChip *phase2Astrometry(psChip *in,	///< Input chip for which to do astrometry, and output
+			 const psDlist *catalog, ///< Catalog stars on the chip: a list of psObjects
+			 int nClips,	///< Number of clipping iterations
+			 float clipLevel ///< Level at which to clip
+			 );
+
+/************************************************************************************************************/
+
+/* Postage stamps */
+
+/** Specification of a postage stamp: location on the sky */
+typedef struct {
+    psSphereCoord *center;		///< Centre of postage stamp
+    psSphereCoord *size;		///< Size of postage stamp
+} psPostageStampSpec;
+
+/** Return postage stamps of a set of regions */
+psImageArray *phase2PostageStamps(const psChip *in, ///< Chip from which to form postage stamps
+				  const psDlist *regions ///< Regions to postage-stampise: a list of
+				                         ///< psPostageStampSpec
+);
+
+/************************************************************************************************************/
+
+#endif