Index: trunk/psModules/src/detrend/pmFringeStats.h =================================================================== --- trunk/psModules/src/detrend/pmFringeStats.h (revision 7875) +++ trunk/psModules/src/detrend/pmFringeStats.h (revision 9615) @@ -1,16 +1,19 @@ -/** @file pmFringeStats.h - * - * @brief Measure Fringe statistics and apply correction - * - * @author Eugene Magnier, IfA - * - * @version $Revision: 1.7 $ $Name: not supported by cvs2svn $ - * @date $Date: 2006-07-12 04:44:01 $ - * - * Copyright 2004 IfA, University of Hawaii - */ +/// @file pmFringeStats.h +/// +/// @brief Measure fringe statistics, and apply correction +/// +/// @ingroup Detrend +/// +/// @author Eugene Magnier, IfA +/// @author Paul Price, IfA +/// +/// @version $Revision: 1.8 $ $Name: not supported by cvs2svn $ +/// @date $Date: 2006-10-17 22:03:32 $ +/// +/// Copyright 2004-2006 Institute for Astronomy, University of Hawaii +/// -# ifndef PM_FRINGE_STATS -# define PM_FRINGE_STATS +#ifndef PM_FRINGE_STATS +#define PM_FRINGE_STATS ////////////////////////////////////////////////////////////////////////////////////////////////////////////// @@ -18,46 +21,59 @@ ////////////////////////////////////////////////////////////////////////////////////////////////////////////// -/** Structure to hold the fringe measurement regions. - */ +/// Fringe measurement regions. +/// +/// Fringes are measured within a box of size dX,dY. A large scale smoothing is performed by subtracting the +/// background within large divisions of the image. The coordinates of the fringe points and the mask may be +/// NULL, which means that they will be generated when required. typedef struct { - psU32 nRequested; // number of fringe points selected - psU32 nAccepted; // number of fringe points not masked - psU32 dX; // median box half-width - psU32 dY; // median box half-height - psU32 nX; // large-scale smoothing in x (col) - psU32 nY; // large-scale smoothing in y (row) - psVector *x; // fringe point coordinates (col) - psVector *y; // fringe point coordinates (row) - psVector *mask; // fringe point on/off mask + psU32 nRequested; // Number of fringe points selected + psU32 nAccepted; // Number of fringe points not masked + psU32 dX; // Median box half-width + psU32 dY; // Median box half-height + psU32 nX; // Number of large-scale smoothing divisions in x (col) + psU32 nY; // Number of large-scale smoothing divisions in y (row) + psVector *x; // Fringe point coordinates (col), or NULL + psVector *y; // Fringe point coordinates (row), or NULL + psVector *mask; // Fringe point on/off mask, or NULL } pmFringeRegions; /// Allocate fringe regions -pmFringeRegions *pmFringeRegionsAlloc ( - int nPts, // number of points to create - int dX, // half-width of fringe boxes - int dY, // half-height of fringe boxes - int nX, // smoothing scale in x - int nY // smoothing scale in y -); +pmFringeRegions *pmFringeRegionsAlloc (int nPts, ///< Number of fringe points to create + int dX, ///< Half-width of fringe boxes + int dY, ///< Half-height of fringe boxes + int nX, ///< Smoothing scale in x + int nY ///< Smoothing scale in y + ); -// Generate the fringe points -bool pmFringeRegionsCreatePoints(pmFringeRegions *fringe, // Fringe regions - const psImage *image, // Image for the regions (defines the size) - psRandom *random // Random number generator +/// Generate the fringe points +/// +/// Fringe points are generated randomly over the image. No effort is made to avoid masked regions (indeed, +/// the function knows nothing about masks). If the random number generator is NULL, then a new one will be +/// used. +bool pmFringeRegionsCreatePoints(pmFringeRegions *fringe, ///< Fringe regions to generate + const psImage *image, ///< Image for the regions (defines the size) + psRandom *random ///< Random number generator, or NULL ); -// Write the regions to a FITS file -bool pmFringeRegionsWriteFits(psFits *fits, // Output FITS file - psMetadata *header, // Header to write, or NULL - const pmFringeRegions *regions, // Regions to write - const char *extname // Extension name, or NULL +/// Write the regions to a FITS file +/// +/// The fringe regions are written to the FITS file, with the given extension name. The header is +/// supplemented with scalar values dX, dY, nX and nY (as PSFRNGDX, PSFRNGDY, PSFRNGNX, PSFRNGNY) from the +/// fringe regions, while the fringe coordinates and mask are written as a FITS table (as x, y, mask). +bool pmFringeRegionsWriteFits(psFits *fits, ///< Output FITS file + psMetadata *header, ///< Additional headers to write, or NULL + const pmFringeRegions *regions, ///< Regions to write + const char *extname ///< Extension name, or NULL ); -// Read the regions from a FITS file -pmFringeRegions *pmFringeRegionsReadFits(psMetadata *header, // Header to read, or NULL - const psFits *fits, // Input FITS file - const char *extname // Extension name, or NULL +/// Read the regions from a FITS file +/// +/// The fringe regions are read from the FITS file, at the given extension name. The scalars are retrieved +/// from the header, while the table provides the fringe coordinates and mask. +pmFringeRegions *pmFringeRegionsReadFits(psMetadata *header, ///< Header to read, or NULL + const psFits *fits, ///< Input FITS file + const char *extname ///< Extension name, or NULL ); @@ -68,11 +84,12 @@ ////////////////////////////////////////////////////////////////////////////////////////////////////////////// -/** Structure to hold the fringe measurements for a particular image - */ +/// Fringe measurements for a particular image +/// +/// Measurements of the median and stdev are made at each of the fringe regions. typedef struct { - pmFringeRegions *regions; // Fringe regions - psVector *f; // fringe point median - psVector *df; // fringe point stdev + pmFringeRegions *regions; ///< Fringe regions + psVector *f; ///< Fringe point median + psVector *df; ///< Fringe point stdev } pmFringeStats; @@ -82,39 +99,44 @@ ); -/** Measure the fringe stats for an image - * - * Given an input image and a fringe stats structure, measure the statistics for each of the fringe points on - * the image. If the fringe vectors are NULL, new vectors are created. - * - * XXX should the structure carry the image dimensions for validation? - * - * @return bool: True or false for success or failure - */ -pmFringeStats *pmFringeStatsMeasure( - pmFringeRegions *fringe, ///< fringe regions - pmReadout *readout, ///< measure fringes on this readout - psMaskType maskVal ///< Mask value for statistics -); +/// Measure the fringe statistics for an image +/// +/// Given an input image and fringe regions at which to measure, measures the median and stdev at each of the +/// fringe points. If the fringe points are undefined, they are generated. +pmFringeStats *pmFringeStatsMeasure(pmFringeRegions *fringe, ///< Fringe regions at which to measure + const pmReadout *readout, ///< Readout for which to measure + psMaskType maskVal ///< Mask value for image + ); -// Write the fringe stats for an image to a FITS table -bool pmFringeStatsWriteFits(psFits *fits, // FITS file to which to write - psMetadata *header, // Header to write, or NULL - const pmFringeStats *fringe, // Fringe statistics to be written - const char *extname // Extension name for table +/// Write the fringe stats for an image to a FITS table +/// +/// The fringe measurements are written to the FITS file with the given extension name. The median and stdev +/// measurements are written as a FITS table (as f and df). +bool pmFringeStatsWriteFits(psFits *fits, ///< FITS file to which to write + psMetadata *header, ///< Additional headers to write, or NULL + const pmFringeStats *fringe, ///< Fringe statistics to be written + const char *extname ///< Extension name for table ); -// Read the fringe stats for an image from a FITS table -pmFringeStats *pmFringeStatsReadFits(psMetadata *header, // Header to read, or NULL - const psFits *fits, // FITS file from which to read - const char *extname, // Extension name to read - pmFringeRegions *regions // Corresponding regions for fringe measurements +/// Read the fringe stats for an image from a FITS table +/// +/// The fringe measurements are read from the FITS file, at the given extension name. The table provides the +/// median and stdev measurements. It is assumed that the fringe measurements correspond to the regions +/// provided. +pmFringeStats *pmFringeStatsReadFits(psMetadata *header, ///< Header to read, or NULL + const psFits *fits, ///< FITS file from which to read + const char *extname, ///< Extension name to read + pmFringeRegions *regions ///< Corresponding regions ); -// Concatenate the fringe stats for several readouts into a single fringe stats. The idea is that each -// readout of each chip should be measured separately (so as to avoid any gaps, as in the case for GPC), but -// then perform the fit to all the readouts belonging to a chip. To do so, we need to concatenate. -pmFringeStats *pmFringeStatsConcatenate(const psArray *fringes, // Array of pmFringeStats for the readouts - const psVector *x0, // Offset in x for the readout - const psVector *y0 // Offset in y for the readout +/// Concatenate the fringe stats for several readouts into a single fringe stats. +/// +/// Each readout of each chip must be measured separately (so as to avoid any gaps between the cells, as in +/// the case for GPC). But the fit must be performed with all the readouts belonging to a chip (in order to +/// get a secure measurement of the fringe amplitudes). To do so, we need to concatenate the fringe +/// measurements for each of the chip components. This function generates a new pmFringeStats from +/// concatenating those in the array. The corresponding pmFringeRegions is also generated. +pmFringeStats *pmFringeStatsConcatenate(const psArray *fringes, ///< Array of pmFringeStats for the readouts + const psVector *x0, ///< Offset in x for the readout + const psVector *y0 ///< Offset in y for the readout ); @@ -123,31 +145,27 @@ ////////////////////////////////////////////////////////////////////////////////////////////////////////////// -/** the pmFringeScale structure defines the relationship between two fringe measurements - */ +/// The fringe correction solution typedef struct { - int nFringeFrames; - psVector *coeff; - psVector *coeffErr; + int nFringeFrames; ///< Number of fringe frames + psVector *coeff; ///< Fringe coefficients; size = nFringeFrames + psVector *coeffErr; ///< Error in fringe coefficients; size = nFringeFrames } pmFringeScale; -/** Determine the scales for the fringe correction - * - * Given an input fringe measurement, and an array of template fringe measurements, measure the contribution - * of each of the templates to the input. Rejection is performed on the fringe regions, to weed out stars - * etc. - * - * @return pmFringeScale* - */ -pmFringeScale *pmFringeScaleMeasure(pmFringeStats *science, // Fringe measurements from science image - psArray *fringes, // Array of fringe measurements from templates - float rej, // Rejection threshold (in standard deviations) - unsigned int nIter, // Maximum number of iterations - float keepFrac // Minimum fraction of regions to keep +/// Measure the scales for the fringe correction +/// +/// Given a fringe measurement for a science image, and an array of template fringe measurements, this +/// function measures the contribution of each of the templates to the input. Rejection is performed on the +/// fringe regions, to weed out stars etc. +pmFringeScale *pmFringeScaleMeasure(pmFringeStats *science, ///< Fringe measurements from science image + psArray *fringes, ///< Array of fringe measurements from templates + float rej, ///< Rejection threshold (in standard deviations) + unsigned int nIter, ///< Maximum number of iterations + float keepFrac ///< Minimum fraction of regions to keep ); /// Allocate fringe scales -pmFringeScale *pmFringeScaleAlloc(int nFringeFrames // Number of fringe frames +pmFringeScale *pmFringeScaleAlloc(int nFringeFrames ///< Number of fringe frames ); @@ -157,21 +175,19 @@ ////////////////////////////////////////////////////////////////////////////////////////////////////////////// -/** Fringe correct the science image - * - * Given a science image, a set of fringe stats and a matched set of fringe images, correct the science image - * for the fringe images. - * - * @return psImage: summed fringe image - */ -psImage *pmFringeCorrect(pmReadout *in, // place info about results here - pmFringeRegions *fringes, // The fringe regions used - psArray *fringeImages, // fringe images to use in correction - psArray *fringeStats, // fringe stats to use in correction - psMaskType maskVal, // Value to mask - float rej, // Rejection threshold, for pmFringeScaleMeasure - unsigned int nIter, // Maximum number of iterations, for pmFringeScaleMeasure - float keepFrac // Minimum fraction of regions to keep, for pmFringeScaleMeasure +/// Solve for and apply the fringe correction +/// +/// This is a wrapper around each of the fringe correction components to measure the fringe points, solve for +/// the fringe correction, and apply the fringe correction. The input fringe images are modified (scaled by +/// the solution coefficients in order to correct the science image). Returns the summed fringe image. +psImage *pmFringeCorrect(pmReadout *in, ///< Input science image + pmFringeRegions *fringes, ///< The fringe regions used + psArray *fringeImages, ///< Fringe template images to use in correction + psArray *fringeStats, ///< Fringe stats (for templates) to use in correction + psMaskType maskVal, ///< Value to mask for science image + float rej, ///< Rejection threshold, for pmFringeScaleMeasure + unsigned int nIter, ///< Maximum number of iterations, for pmFringeScaleMeasure + float keepFrac ///< Minimum fraction of regions to keep, for pmFringeScaleMeasure ); -# endif +#endif