Index: trunk/psphot/src/pmObjects_EAM.h =================================================================== --- trunk/psphot/src/pmObjects_EAM.h (revision 4949) +++ trunk/psphot/src/pmObjects_EAM.h (revision 4954) @@ -1,3 +1,101 @@ - +/** @file pmObjects.h + * + * This file will ... + * + * @author GLG, MHPCC + * + * @version $Revision: 1.2 $ $Name: not supported by cvs2svn $ + * @date $Date: 2005-09-07 03:33:01 $ + * + * Copyright 2004 Maui High Performance Computing Center, University of Hawaii + * + */ + +#if !defined(PM_OBJECTS_H) +#define PM_OBJECTS_H + +#if HAVE_CONFIG_H +#include +#endif + +#include +#include +#include "pslib.h" + +// XXX EAM : this function should be added to psLib +int psImageCountPixelMask (psImage *mask, psU8 value); + +// XXX EAM : bug : missing from psLib/*.h +bool psMinimizeGaussNewtonDelta (psVector *delta, + const psVector *params, + const psVector *paramMask, + const psArray *x, + const psVector *y, + const psVector *yErr, + psMinimizeLMChi2Func func); + +// XXX EAM : switch to psPoly when ready +psF64 Polynomial2DEval(const psPolynomial2D* myPoly, psF64 x, psF64 y); + +// XXX EAM : psEllipse needs to be be included in psLib +# include "psEllipse.h" + +/** pmPeakType + * + * A peak pixel may have several features which may be determined when the + * peak is found or measured. These are specified by the pmPeakType enum. + * PM_PEAK_LONE represents a single pixel which is higher than its 8 immediate + * neighbors. The PM_PEAK_EDGE represents a peak pixel which touching the image + * edge. The PM_PEAK_FLAT represents a peak pixel which has more than a specific + * number of neighbors at the same value, within some tolarence: + * + */ +typedef enum { + PM_PEAK_LONE, ///< Isolated peak. + PM_PEAK_EDGE, ///< Peak on edge. + PM_PEAK_FLAT, ///< Peak has equal-value neighbors. + PM_PEAK_UNDEF ///< Undefined. +} pmPeakType; + +/** pmPeak data structure + * + * + * + */ +typedef struct +{ + int x; ///< X-coordinate of peak pixel. + int y; ///< Y-coordinate of peak pixel. + float counts; ///< Value of peak pixel (above sky?). + pmPeakType class; ///< Description of peak. +} +pmPeak; + +/** pmMoments data structure + * + * + * + */ +typedef struct +{ + float x; ///< X-coord of centroid. + float y; ///< Y-coord of centroid. + float Sx; ///< x-second moment. + float Sy; ///< y-second moment. + float Sxy; ///< xy cross moment. + float Sum; ///< Pixel sum above sky (background). + float Peak; ///< Peak counts above sky. + float Sky; ///< Sky level (background). + float SN; ///< approx signal-to-noise + int nPixels; ///< Number of pixels used. +} pmMoments; + +typedef int pmModelType; + +/** pmPSFClump data structure + * + * + * + */ typedef struct { @@ -8,33 +106,26 @@ } pmPSFClump; -typedef struct -{ - float x; ///< X-coord of centroid. - float y; ///< Y-coord of centroid. - float Sx; ///< x-second moment. - float Sy; ///< y-second moment. - float Sxy; ///< xy cross moment. - float Sum; ///< Pixel sum above sky (background). - float Peak; ///< Peak counts above sky. - float Sky; ///< Sky level (background). - float SN; - int nPixels; ///< Number of pixels used. -} -pmMoments; - -typedef psS32 pmModelType; - -typedef struct -{ - pmModelType type; ///< Model to be used. - psVector *params; ///< Paramater values. - psVector *dparams; ///< Parameter errors. - float radius; ///< fit radius actually used - float chisq; ///< Fit chi-squared. - int nDOF; ///< number of degrees of freedom - int nIter; ///< number of iterations to reach min +/** pmModel data structure + * + * + * + */ +typedef struct +{ + pmModelType type; ///< Model to be used. + psVector *params; ///< Paramater values. + psVector *dparams; ///< Parameter errors. + float chisq; ///< Fit chi-squared. + int nDOF; ///< number of degrees of freedom + int nIter; ///< number of iterations to reach min + float radius; ///< fit radius actually used } pmModel; +/** pmSourceType enumeration + * + * + * + */ typedef enum { PS_SOURCE_DEFECT, @@ -58,97 +149,267 @@ } pmSourceType; -typedef struct -{ - pmPeak *peak; ///< Description of peak pixel. - psImage *pixels; ///< Rectangular region including object pixels. - psImage *noise; ///< Mask which marks pixels associated with objects. - psImage *mask; ///< Mask which marks pixels associated with objects. - pmMoments *moments; ///< Basic moments measure for the object. - pmModel *modelPSF; ///< PSF Model fit (parameters and type) - pmModel *modelFLT; ///< FLT Model fit (parameters and type). - pmSourceType type; ///< Best identification of object. +/** pmSource data structure + * + * This source has the capacity for several types of measurements. The + * simplest measurement of a source is the location and flux of the peak pixel + * associated with the source: + * + */ +typedef struct +{ + pmPeak *peak; ///< Description of peak pixel. + psImage *pixels; ///< Rectangular region including object pixels. + psImage *noise; ///< Mask which marks pixels associated with objects. + psImage *mask; ///< Mask which marks pixels associated with objects. + pmMoments *moments; ///< Basic moments measure for the object. + pmModel *modelPSF; ///< PSF Model fit (parameters and type) + pmModel *modelFLT; ///< FLT Model fit (parameters and type). + pmSourceType type; ///< Best identification of object. } pmSource; -// XXX EAM function to return pmModel -typedef psMinimizeLMChi2Func pmModelFunc; -typedef psF64 (*pmModelFlux)(const psVector *params); -typedef bool (*pmModelGuessFunc)(pmModel *model, pmSource *source); -typedef bool (*pmModelFromPSFFunc)(pmModel *modelPSF, pmModel *modelFLT, pmPSF *psf); -typedef psF64 (*pmModelRadius)(const psVector *params, double flux); - -typedef bool (*pmModelLimits)(psVector **beta_lim, psVector **params_min, psVector **params_max); -typedef bool (*pmModelFitStatusFunc)(pmModel *model); - -// XXX EAM structure to carry model options -typedef struct { - char *name; - int nParams; - pmModelFunc modelFunc; - pmModelFlux modelFlux; - pmModelRadius modelRadius; - pmModelLimits modelLimits; - pmModelGuessFunc modelGuessFunc; - pmModelFromPSFFunc modelFromPSFFunc; - pmModelFitStatusFunc modelFitStatusFunc; -} pmModelGroup; - -// XXX EAM : strucures to define elliptical shape parameters -typedef struct { - double major; - double minor; - double theta; -} EllipseAxes; - -typedef struct { - double x2; - double y2; - double xy; -} EllipseMoments; - -typedef struct { - double sx; - double sy; - double sxy; -} EllipseShape; - -EllipseAxes EllipseMomentsToAxes (EllipseMoments moments); -EllipseShape EllipseAxesToShape (EllipseAxes axes); -EllipseAxes EllipseShapeToAxes (EllipseShape shape); +/** pmPSF data structure + * + * + * + */ +typedef struct +{ + pmModelType type; ///< PSF Model in use + psArray *params; ///< Model parameters (psPolynomial2D) + float chisq; ///< PSF goodness statistic + int nPSFstars; ///< number of stars used to measure PSF +} +pmPSF; + +pmPeak *pmPeakAlloc( + int x, ///< Row-coordinate in image space + int y, ///< Col-coordinate in image space + float counts, ///< The value of the peak pixel + pmPeakType class ///< The type of peak pixel +); + +pmMoments *pmMomentsAlloc(); +pmModel *pmModelAlloc(pmModelType type); +pmSource *pmSourceAlloc(); + +/****************************************************************************** +pmFindVectorPeaks(vector, threshold): Find all local peaks in the given vector +above the given threshold. Returns a vector of type PS_TYPE_U32 containing +the location (x value) of all peaks. +*****************************************************************************/ +psVector *pmFindVectorPeaks( + const psVector *vector, ///< The input vector (float) + float threshold ///< Threshold above which to find a peak +); + +/****************************************************************************** +pmFindImagePeaks(image, threshold): Find all local peaks in the given psImage +above the given threshold. Returns a psList containing the location (x/y +value) of all peaks. +*****************************************************************************/ +psArray *pmFindImagePeaks( + const psImage *image, ///< The input image where peaks will be found (float) + float threshold ///< Threshold above which to find a peak +); + +/****************************************************************************** +pmCullPeaks(peaks, maxValue, valid): eliminate peaks from the psList that have +a peak value above the given maximum, or fall outside the valid region. +*****************************************************************************/ +psList *pmCullPeaks( + psList *peaks, ///< The psList of peaks to be culled + float maxValue, ///< Cull peaks above this value + const psRegion *valid ///< Cull peaks otside this psRegion +); + +/****************************************************************************** +pmSource *pmSourceLocalSky(image, peak, innerRadius, outerRadius): + +*****************************************************************************/ +pmSource *pmSourceLocalSky( + const psImage *image, ///< The input image (float) + const pmPeak *peak, ///< The peak for which the pmSource struct is created. + psStatsOptions statsOptions, ///< The statistic used in calculating the background sky + float innerRadius, ///< The inner radius of the suqare annulus for calculating sky + float outerRadius ///< The outer radius of the suqare annulus for calculating sky +); + +/****************************************************************************** + *****************************************************************************/ +bool pmSourceMoments( + pmSource *source, ///< The input pmSource for which moments will be computed + float radius ///< Use a circle of pixels around the peak +); /****************************************************************************** pmSourcePSFClump(pmArray *source, psMetaDeta *metadata): find the source PSF clump - *****************************************************************************/ -pmPSFClump pmSourcePSFClump(psArray *source, ///< The input psSource - psMetadata *metadata ///< Contains classification parameters - ); +*****************************************************************************/ +pmPSFClump pmSourcePSFClump( + psArray *source, ///< The input pmSource + psMetadata *metadata ///< Contains classification parameters +); /****************************************************************************** pmSourceRoughClass(pmArray *source, psMetaDeta *metadata): make a guess at the source classification. - *****************************************************************************/ -bool pmSourceRoughClass(psArray *source, ///< The input psSource - psMetadata *metadata, ///< Contains classification parameters - pmPSFClump clump ///< Statistics about the PSF clump - ); - -pmModel *pmSourceModelGuess(pmSource *source, ///< The input psSource - pmModelType model ///< The type of model to be created. - ); - -// XXX EAM : added utility functions -pmModelType pmModelSetType (char *name); -pmModelFunc pmModelFunc_GetFunction (pmModelType type); -pmModelFlux pmModelFlux_GetFunction (pmModelType type); -pmModelGuessFunc pmModelGuessFunc_GetFunction (pmModelType type); -pmModelFromPSFFunc pmModelFromPSFFunc_GetFunction (pmModelType type); -pmModelRadius pmModelRadius_GetFunction (pmModelType type); -char *pmModelGetType (pmModelType type); -psS32 pmModelParameterCount (pmModelType type); -pmModelLimits pmModelLimits_GetFunction (pmModelType type); -pmModelFitStatusFunc pmModelFitStatusFunc_GetFunction (pmModelType type); -int pmCountSatPixels (psImage *image); - -pmMoments *pmMomentsAlloc(); -pmModel *pmModelAlloc(pmModelType type); -pmSource *pmSourceAlloc(); +*****************************************************************************/ +bool pmSourceRoughClass( + psArray *source, ///< The input pmSource + psMetadata *metadata, ///< Contains classification parameters + pmPSFClump clump ///< Statistics about the PSF clump +); + +/****************************************************************************** +pmSourceSetPixelCircle(source, image, radius) +*****************************************************************************/ +bool pmSourceSetPixelsCircle( + pmSource *source, ///< The input pmSource + const psImage *image, ///< The input image (float) + float radius ///< The radius of the circle +); + +/****************************************************************************** + *****************************************************************************/ +pmModel *pmSourceModelGuess( + pmSource *source, ///< The input pmSource + pmModelType model ///< The type of model to be created. +); + +/****************************************************************************** + *****************************************************************************/ +typedef enum { + PS_CONTOUR_CRUDE, +} pmContourType; + +psArray *pmSourceContour( + pmSource *source, ///< The input pmSource + const psImage *image, ///< The input image (float) (this arg should be removed) + float level, ///< The level of the contour + pmContourType mode ///< Currently this must be PS_CONTOUR_CRUDE +); + +/****************************************************************************** + *****************************************************************************/ +bool pmSourceFitModel( + pmSource *source, ///< The input pmSource + pmModel *model, ///< model to be fitted + const bool PSF ///< Treat model as PSF or FLT? +); + +/****************************************************************************** + *****************************************************************************/ +bool pmSourceAddModel( + psImage *image, ///< The output image (float) + psImage *mask, ///< The image pixel mask (valid == 0) + pmModel *model, ///< The input pmModel + bool center ///< A boolean flag that determines whether pixels are centered +); + +/****************************************************************************** + *****************************************************************************/ +bool pmSourceSubModel( + psImage *image, ///< The output image (float) + psImage *mask, ///< The image pixel mask (valid == 0) + pmModel *model, ///< The input pmModel + bool center ///< A boolean flag that determines whether pixels are centered +); + +/** + * + * The object model functions are defined to allow for the flexible addition + * of new object models. Every object model, with parameters represented by + * 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. + * + */ + +/** + * + * This function is the model chi-square minimization function for this model. + * + */ +typedef psMinimizeLMChi2Func pmModelFunc; + + +/** + * + * This function returns the integrated flux for the given model parameters. + */ +typedef psF64 (*pmModelFlux)(const psVector *params); + + +/** + * + * This function returns the radius at which the given model and parameters + * achieves the given flux. + * + */ +typedef psF64 (*pmModelRadius)(const psVector *params, double flux); + +/** + * + * This function sets the model parameter limits vectors for the given model + * + */ +typedef bool (*pmModelLimits)(psVector **beta_lim, psVector **params_min, psVector **params_max); + +/** + * + * This function provides the model guess parameters based on the details of + * the given source. + * + */ +typedef bool (*pmModelGuessFunc)(pmModel *model, pmSource *source); + + +/** + * + * This function constructs the PSF model for the given source based on the + * supplied psf and the FLT model for the object. + * + */ +typedef bool (*pmModelFromPSFFunc)(pmModel *modelPSF, pmModel *modelFLT, pmPSF *psf); + + +/** + * + * This function returns the success / failure status of the given model fit + * + */ +typedef bool (*pmModelFitStatusFunc)(pmModel *model); + +/** + * + * Each of the function types above has a corresponding function which returns + * the function given the model type: + * + */ +pmModelFunc pmModelFunc_GetFunction (pmModelType type); +pmModelFlux pmModelFlux_GetFunction (pmModelType type); +pmModelRadius pmModelRadius_GetFunction (pmModelType type); +pmModelLimits pmModelLimits_GetFunction (pmModelType type); +pmModelGuessFunc pmModelGuessFunc_GetFunction (pmModelType type); +pmModelFromPSFFunc pmModelFromPSFFunc_GetFunction (pmModelType type); +pmModelFitStatusFunc pmModelFitStatusFunc_GetFunction (pmModelType type); + +// pmModelGroup utility functions +int pmModelParameterCount (pmModelType type); +char *pmModelGetType (pmModelType type); +pmModelType pmModelSetType (char *name); + +// structure to carry model group functions +typedef struct { + char *name; + int nParams; + pmModelFunc modelFunc; + pmModelFlux modelFlux; + pmModelRadius modelRadius; + pmModelLimits modelLimits; + pmModelGuessFunc modelGuessFunc; + pmModelFromPSFFunc modelFromPSFFunc; + pmModelFitStatusFunc modelFitStatusFunc; +} pmModelGroup; + +#endif