Index: /branches/unlabeled-1.22.6/psModules/src/objects/pmSource.h =================================================================== --- /branches/unlabeled-1.22.6/psModules/src/objects/pmSource.h (revision 16067) +++ /branches/unlabeled-1.22.6/psModules/src/objects/pmSource.h (revision 16067) @@ -0,0 +1,239 @@ +/* @file pmSource.h + * + * @author EAM, IfA; GLG, MHPCC + * + * @version $Revision: 1.22 $ $Name: not supported by cvs2svn $ + * @date $Date: 2008-01-15 02:48:28 $ + * Copyright 2004 Maui High Performance Computing Center, University of Hawaii + */ + +# ifndef PM_SOURCE_H +# define PM_SOURCE_H + +# include "pmSourceExtendedPars.h" + +/// @addtogroup Objects Object Detection / Analysis Functions +/// @{ + +/** pmSourceType enumeration + * + * A given source may be identified as most-likely to be one of several source + * types. The pmSource entry pmSourceType defines the current best-guess for this + * source. + * + * XXX: The values given below are currently illustrative and will require + * some modification as the source classification code is developed. (TBD) + * + */ +typedef enum { + PM_SOURCE_TYPE_UNKNOWN, ///< a cosmic-ray + PM_SOURCE_TYPE_DEFECT, ///< a cosmic-ray + PM_SOURCE_TYPE_SATURATED, ///< random saturated pixels + PM_SOURCE_TYPE_STAR, ///< a good-quality star + PM_SOURCE_TYPE_EXTENDED, ///< an extended object (eg, galaxy) +} pmSourceType; + +typedef enum { + PM_SOURCE_MODE_DEFAULT = 0x0000, ///< + PM_SOURCE_MODE_PSFMODEL = 0x0001, ///< + PM_SOURCE_MODE_EXTMODEL = 0x0002, ///< + PM_SOURCE_MODE_SUBTRACTED = 0x0004, ///< + PM_SOURCE_MODE_FITTED = 0x0008, ///< + PM_SOURCE_MODE_FAIL = 0x0010, ///< + PM_SOURCE_MODE_POOR = 0x0020, ///< + PM_SOURCE_MODE_PAIR = 0x0040, ///< + PM_SOURCE_MODE_PSFSTAR = 0x0080, ///< + PM_SOURCE_MODE_SATSTAR = 0x0100, ///< + PM_SOURCE_MODE_BLEND = 0x0200, ///< + PM_SOURCE_MODE_LINEAR = 0x0400, ///< + PM_SOURCE_MODE_TEMPSUB = 0x0800, ///< XXX get me a better name! + PM_SOURCE_MODE_EXTERNAL = 0x1000, ///< XXX get me a better name! + PM_SOURCE_MODE_BADPSF = 0x2000, ///< Failed to get good estimate of object's PSF +} pmSourceMode; + +/** 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: + * + */ +struct pmSource { + const int id; ///< Unique ID for object + int seq; ///< ID for output (generated on write) + pmPeak *peak; ///< Description of peak pixel. + psImage *pixels; ///< Rectangular region including object pixels. + psImage *weight; ///< Image variance. + psImage *maskObj; ///< unique mask for this object which marks included pixels associated with objects. + psImage *maskView; ///< view into global image mask for this object region + psImage *modelFlux; ///< cached copy of the best model for this source + psImage *psfFlux; ///< cached copy of the psf model for this source + pmMoments *moments; ///< Basic moments measure for the object. + pmModel *modelPSF; ///< PSF Model fit (parameters and type) + pmModel *modelEXT; ///< EXT (floating) Model fit (parameters and type). + pmModel *modelConv; ///< PSF-Convolved Model fit (parameters and type). + pmSourceType type; ///< Best identification of object. + pmSourceMode mode; ///< Best identification of object. + psArray *blends; + float psfMag; ///< calculated from flux in modelPsf + float extMag; ///< calculated from flux in modelEXT + float errMag; ///< error in psfMag OR extMag (depending on type) + float apMag; ///< apMag corresponding to psfMag or extMag (depending on type) + float pixWeight; ///< model-weighted coverage of valid pixels + float psfChisq; ///< probability of PSF + float crNsigma; ///< Nsigma deviation from PSF to CR + float extNsigma; ///< Nsigma deviation from PSF to EXT + psRegion region; ///< area on image covered by selected pixels + float sky, skyErr; ///< The sky and its error at the center of the object + pmSourceExtendedPars *extpars; ///< extended source parameters +}; + +/** pmPSFClump data structure + * + * A collection of object moment measurements can be used to determine + * approximate object classes. The key to this analysis is the location and + * statistics (in the second-moment plane, + * + */ +typedef struct +{ + float X; + float dX; + float Y; + float dY; +} +pmPSFClump; + + +/** pmSourceAlloc() + * + */ +pmSource *pmSourceAlloc(); + +/** pmSourceCopy() + * + */ + +bool psMemCheckSource(psPtr ptr); + +pmSource *pmSourceCopy(pmSource *source); + +// free just the pixels for a source, keeping derived data +void pmSourceFreePixels(pmSource *source); + +/** pmSourceDefinePixels() + * + * Define psImage subarrays for the source located at coordinates x,y on the + * image set defined by readout. The pixels defined by this operation consist of + * a square window (of full width 2Radius+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 readout image, thus if + * the radius would fall outside the image pixels, the subimage is truncated to + * only consist of valid pixels. If readout->mask or readout->weight are not + * 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. + * + */ +bool pmSourceDefinePixels( + pmSource *mySource, ///< source to be re-defined + const pmReadout *readout, ///< base the source on this readout + psF32 x, ///< center coords of source + psF32 y, ///< center coords of source + psF32 Radius ///< size of box on source +); + +bool pmSourceRedefinePixels ( + pmSource *mySource, ///< source to be re-defined + const pmReadout *readout, ///< base the source on this readout + psF32 x, ///< center coords of source + psF32 y, ///< center coords of source + psF32 Radius ///< size of box on source +); + +/** pmSourcePSFClump() + * + * 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 pmSourcePSFClump searches a collection of + * sources with measured moments for a group with moments which are all very + * similar. The function returns a 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 second-moment 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 pmPSFClump structure. + * + * The return value indicates the success (TRUE) of the operation. + * + * XXX: Limit the S/N of the candidate sources (part of Metadata)? (TBD). + * XXX: Save the clump parameters on the Metadata (TBD) + * + */ +pmPSFClump pmSourcePSFClump( + psArray *source, ///< The input pmSource + psMetadata *metadata ///< Contains classification parameters +); + +/** pmSourceRoughClass() + * + * Based on the specified data values, make a guess at the source + * classification. The sources are provides as a psArray of pmSource entries. + * Definable parameters needed to make the classification are provided to the + * routine with the psMetadata structure. The rules (in SDRS) refer to values which + * can be extracted from the metadata using the given keywords. Except as noted, + * the data type for these parameters are psF32. + * + */ +bool pmSourceRoughClass( + psArray *source, ///< The input pmSource + psMetadata *metadata, ///< Contains classification parameters + pmPSFClump clump, ///< Statistics about the PSF clump + psMaskType maskSat ///< Mask value for saturated pixels +); + + +/** pmSourceMoments() + * + * Measure source moments for the given source, using the value of + * source.moments.sky provided as the local background value and the peak + * coordinates as the initial source location. The resulting moment values are + * applied to the source.moments entry, and the source is returned. The moments + * are measured within the given circular radius of the source.peak coordinates. + * The return value indicates the success (TRUE) of the operation. + * + */ +bool pmSourceMoments( + pmSource *source, ///< The input pmSource for which moments will be computed + float radius ///< Use a circle of pixels around the peak +); + +pmModel *pmSourceGetModel (bool *isPSF, const pmSource *source); + +bool pmSourceAdd (pmSource *source, pmModelOpMode mode, psMaskType maskVal); +bool pmSourceSub (pmSource *source, pmModelOpMode mode, psMaskType maskVal); +bool pmSourceAddWithOffset (pmSource *source, pmModelOpMode mode, psMaskType maskVal, int dx, int dy); +bool pmSourceSubWithOffset (pmSource *source, pmModelOpMode mode, psMaskType maskVal, int dx, int dy); + +bool pmSourceOp (pmSource *source, pmModelOpMode mode, bool add, psMaskType maskVal, int dx, int dy); +bool pmSourceCacheModel (pmSource *source, psMaskType maskVal); +bool pmSourceCachePSF (pmSource *source, psMaskType maskVal); + +int pmSourceSortBySN (const void **a, const void **b); +int pmSourceSortByY (const void **a, const void **b); + +pmSourceMode pmSourceModeFromString (const char *name); +char *pmSourceModeToString (const pmSourceMode mode); + +/// @} +# endif /* PM_SOURCE_H */