IPP Software Navigation Tools IPP Links Communication Pan-STARRS Links

Ignore:
Timestamp:
Oct 10, 2005, 9:53:54 AM (21 years ago)
Author:
gusciora
Message:

A fairly large check-in. This incorporates must of Eugene's mods to
the object detection routines.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/psModules/src/objects/pmObjects.h

    r5170 r5255  
    11/** @file  pmObjects.h
    22 *
    3  *  This file will ...
     3 * The process of finding, measuring, and classifying astronomical sources on
     4 * images is one of the critical tasks of the IPP or any astronomical software
     5 * system. This file will define structures and functions related to the task
     6 * of source detection and measurement. The elements defined in this section
     7 * are generally low-level components which can be connected together to
     8 * construct a complete object measurement suite.
    49 *
    510 *  @author GLG, MHPCC
    611 *
    7  *  @version $Revision: 1.1 $ $Name: not supported by cvs2svn $
    8  *  @date $Date: 2005-09-28 20:43:52 $
     12 *  @version $Revision: 1.2 $ $Name: not supported by cvs2svn $
     13 *  @date $Date: 2005-10-10 19:53:40 $
    914 *
    1015 *  Copyright 2004 Maui High Performance Computing Center, University of Hawaii
    … …  
    1924#endif
    2025
    21 #include<stdio.h>
    22 #include<math.h>
     26#include <stdio.h>
     27#include <math.h>
    2328#include "pslib.h"
     29#include "pmAstrometry.h"
     30/**
     31 * In the object analysis process, we will use specific mask values to mark the
     32 * image pixels. The following structure defines the relevant mask values.
     33 *
     34 * XXX: This is probably a bad solution: we will want to set mask values
     35 * outside of the PSPHOT code.  Perhaps we can set up a registered set of mask
     36 * values with specific meanings that other functions can add to or define?
     37 */
     38enum {
     39    PSPHOT_MASK_CLEAR     = 0x00,
     40    PSPHOT_MASK_INVALID   = 0x01,
     41    PSPHOT_MASK_SATURATED = 0x02,
     42    PSPHOT_MASK_MARKED    = 0x08,
     43} psphotMaskValues;
     44
    2445
    2546/** pmPeakType
    … …  
    4061} pmPeakType;
    4162
     63
    4264/** pmPeak data structure
     65 * 
     66 *  A source has the capacity for several types of measurements. The
     67 *  simplest measurement of a source is the location and flux of the peak pixel
     68 *  associated with the source:
    4369 * 
    4470 */
    … …  
    5278pmPeak;
    5379
     80
    5481/** pmMoments data structure
     82 * 
     83 * One of the simplest measurements which can be made quickly for an object
     84 * are the object moments. We specify a structure to carry the moment information
     85 * for a specific source:
    5586 * 
    5687 */
    5788typedef struct
    5889{
    59     float x;                            ///< X-coord of centroid.
    60     float y;                            ///< Y-coord of centroid.
    61     float Sx;                           ///< x-second moment.
    62     float Sy;                           ///< y-second moment.
    63     float Sxy;                          ///< xy cross moment.
    64     float Sum;                          ///< Pixel sum above sky (background).
    65     float Peak;                         ///< Peak counts above sky.
    66     float Sky;                          ///< Sky level (background).
    67     int nPixels;                        ///< Number of pixels used.
     90    float x;    ///< X-coord of centroid.
     91    float y;    ///< Y-coord of centroid.
     92    float Sx;    ///< x-second moment.
     93    float Sy;    ///< y-second moment.
     94    float Sxy;    ///< xy cross moment.
     95    float Sum;    ///< Pixel sum above sky (background).
     96    float Peak;    ///< Peak counts above sky.
     97    float Sky;    ///< Sky level (background).
     98    float SN;    ///< approx signal-to-noise
     99    int nPixels;   ///< Number of pixels used.
    68100}
    69101pmMoments;
    70102
    71 /** pmModelType enumeration
    72  * 
    73  */
    74 typedef enum {
    75     PS_MODEL_GAUSS,                     ///< Regular 2-D Gaussian
    76     PS_MODEL_PGAUSS,                    ///< Psuedo 2-D Gaussian
    77     PS_MODEL_TWIST_GAUSS,               ///< 2-D Twisted Gaussian
    78     PS_MODEL_WAUSS,                     ///< 2-D Waussian
    79     PS_MODEL_SERSIC,                    ///< Sersic
    80     PS_MODEL_SERSIC_CORE,               ///< Sersic Core
    81     PS_MODEL_UNDEFINED                  ///< Undefined
    82 } pmModelType;
    83 
    84 /** pmModel data structure
    85  * 
    86  */
    87 // XXX: The SDRS has the "type" member of type psS32.
     103
     104/** pmPSFClump data structure
     105 *
     106 * A collection of object moment measurements can be used to determine
     107 * approximate object classes. The key to this analysis is the location and
     108 * statistics (in the second-moment plane,
     109 * 
     110 */
    88111typedef struct
    89112{
    90     pmModelType type;                   ///< Model to be used.
    91     psVector *params;                   ///< Paramater values.
    92     psVector *dparams;                  ///< Parameter errors.
    93     float chisq;                        ///< Fit chi-squared.
    94     int nDOF;                           ///< number of degrees of freedom
    95     int nIter;                          ///< number of iterations to reach min
     113    float X;
     114    float dX;
     115    float Y;
     116    float dY;
     117}
     118pmPSFClump;
     119
     120typedef int pmModelType;
     121#define PS_MODEL_GAUSS 0
     122#define PS_MODEL_PGAUSS 1
     123#define PS_MODEL_QGAUSS 2
     124#define PS_MODEL_SGAUSS 3
     125
     126
     127/** pmModel data structure
     128 *
     129 * Every source may have two types of models: a PSF model and a FLT (floating)
     130 * model. The PSF model represents the best fit of the image PSF to the specific
     131 * object. In this case, the PSF-dependent parameters are specified for the
     132 * object by the PSF, not by the fit. The FLT model represents the best fit of
     133 * the given model to the object, with all parameters floating in the fit.
     134 * 
     135 */
     136typedef struct
     137{
     138    pmModelType type;   ///< Model to be used.
     139    psVector *params;   ///< Paramater values.
     140    psVector *dparams;   ///< Parameter errors.
     141    float chisq;   ///< Fit chi-squared.
     142    int nDOF;    ///< number of degrees of freedom
     143    int nIter;    ///< number of iterations to reach min
     144    float radius;   ///< fit radius actually used
    96145}
    97146pmModel;
    98147
    99148/** pmSourceType enumeration
    100  * 
    101  * 
    102  * 
     149 *
     150 * A given source may be identified as most-likely to be one of several source
     151 * types. The pmSource entry pmSourceType defines the current best-guess for this
     152 * source.
     153 *
     154 * XXX: The values given below are currently illustrative and will require
     155 * some modification as the source classification code is developed. (TBD)
     156 *
    103157 */
    104158typedef enum {
    105     PS_SOURCE_PSFSTAR,
    106     PS_SOURCE_GALAXY,
    107     PS_SOURCE_DEFECT,
    108     PS_SOURCE_SATURATED,
    109     PS_SOURCE_SATSTAR,
    110     PS_SOURCE_FAINTSTAR,
    111     PS_SOURCE_BRIGHTSTAR,
    112     PS_SOURCE_OTHER
     159    PM_SOURCE_DEFECT,                   ///< a cosmic-ray
     160    PM_SOURCE_SATURATED,                ///< random saturated pixels
     161
     162    PM_SOURCE_SATSTAR,                  ///< a saturated star
     163    PM_SOURCE_PSFSTAR,                  ///< a PSF star
     164    PM_SOURCE_GOODSTAR,                 ///< a good-quality star
     165
     166    PM_SOURCE_POOR_FIT_PSF,             ///< poor quality PSF fit
     167    PM_SOURCE_FAIL_FIT_PSF,             ///< failed to get a good PSF fit
     168    PM_SOURCE_FAINTSTAR,                ///< below S/N cutoff
     169
     170    PM_SOURCE_GALAXY,                   ///< an extended object (galaxy)
     171    PM_SOURCE_FAINT_GALAXY,             ///< a galaxy below S/N cutoff
     172    PM_SOURCE_DROP_GALAXY,              ///< ?
     173    PM_SOURCE_FAIL_FIT_GAL,             ///< failed on the galaxy fit
     174    PM_SOURCE_POOR_FIT_GAL,             ///< poor quality galaxy fit
     175
     176    PM_SOURCE_OTHER,                    ///< unidentified
    113177} pmSourceType;
    114178
    … …  
    122186typedef struct
    123187{
    124     pmPeak *peak;                       ///< Description of peak pixel.
    125     psImage *pixels;                    ///< Rectangular region including object pixels.
    126     psImage *mask;                      ///< Mask which marks pixels associated with objects.
    127     pmMoments *moments;                 ///< Basic moments measure for the object.
    128     pmModel *modelPSF;                  ///< PSF model parameters and type
    129     pmModel *modelFLT;                  ///< FLT model parameters and type
    130     pmSourceType type;                  ///< Best identification of object.
     188    pmPeak *peak;   ///< Description of peak pixel.
     189    psImage *pixels;   ///< Rectangular region including object pixels.
     190    psImage *weight;   ///< Image variance.
     191    psImage *mask;   ///< Mask which marks pixels associated with objects.
     192    pmMoments *moments;   ///< Basic moments measure for the object.
     193    pmModel *modelPSF;   ///< PSF Model fit (parameters and type)
     194    pmModel *modelFLT;   ///< FLT (floating) Model fit (parameters and type).
     195    pmSourceType type;   ///< Best identification of object.
    131196}
    132197pmSource;
    133198
    134 /** pmPeak data structure
    135  * 
    136  * 
    137  * 
    138  */
    139 typedef struct
    140 {
    141     psS32 type;                         ///< PSF Model in use
    142     psArray *params;                    ///< Model parameters (psPolynomial2D)
    143     psF32 chisq;                        ///< PSF goodness statistic
    144     psS32 nPSFstars;                    ///< number of stars used to measure PSF
    145 }
    146 pmPSF;
    147 
    148 
    149 
     199
     200/** pmPeakAlloc()
     201 *
     202 *  @return pmPeak*    newly allocated pmPeak with all internal pointers set to NULL
     203 */
    150204pmPeak *pmPeakAlloc(
    151     int x,                              ///< Row-coordinate in image space
    152     int y,                              ///< Col-coordinate in image space
    153     float counts,                       ///< The value of the peak pixel
    154     pmPeakType class                    ///< The type of peak pixel
    155 );
    156 
     205    int x,    ///< Row-coordinate in image space
     206    int y,    ///< Col-coordinate in image space
     207    float counts,   ///< The value of the peak pixel
     208    pmPeakType class   ///< The type of peak pixel
     209);
     210
     211
     212/** pmMomentsAlloc()
     213 *
     214 */
    157215pmMoments *pmMomentsAlloc();
     216
     217
     218/** pmModelAlloc()
     219 *
     220 */
    158221pmModel *pmModelAlloc(pmModelType type);
    159 pmSource *pmSourceAlloc();
    160 
    161 /******************************************************************************
    162 pmFindVectorPeaks(vector, threshold): Find all local peaks in the given vector
    163 above the given threshold.  Returns a vector of type PS_TYPE_U32 containing
    164 the location (x value) of all peaks.
    165  *****************************************************************************/
     222
     223
     224/** pmSourceAlloc()
     225 *
     226 */
     227pmSource  *pmSourceAlloc();
     228
     229
     230/** pmFindVectorPeaks()
     231 *
     232 * Find all local peaks in the given vector above the given threshold. A peak
     233 * is defined as any element with a value greater than its two neighbors and with
     234 * a value above the threshold. Two types of special cases must be addressed.
     235 * Equal value elements: If an element has the same value as the following
     236 * element, it is not considered a peak. If an element has the same value as the
     237 * preceding element (but not the following), then it is considered a peak. Note
     238 * that this rule (arbitrarily) identifies flat regions by their trailing edge.
     239 * Edge cases: At start of the vector, the element must be higher than its
     240 * neighbor. At the end of the vector, the element must be higher or equal to its
     241 * neighbor. These two rules again places the peak associated with a flat region
     242 * which touches the image edge at the image edge. The result of this function is
     243 * a vector containing the coordinates (element number) of the detected peaks
     244 * (type psU32).
     245 *
     246 */
    166247psVector *pmFindVectorPeaks(
    167     const psVector *vector,             ///< The input vector (float)
    168     float threshold                     ///< Threshold above which to find a peak
    169 );
    170 
    171 /******************************************************************************
    172 pmFindImagePeaks(image, threshold): Find all local peaks in the given psImage
    173 above the given threshold.  Returns a psList containing the location (x/y
    174 value) of all peaks.
    175  *****************************************************************************/
     248    const psVector *vector,  ///< The input vector (float)
     249    float threshold   ///< Threshold above which to find a peak
     250);
     251
     252
     253/** pmFindImagePeaks()
     254 *
     255 * Find all local peaks in the given image above the given threshold. This
     256 * function should find all row peaks using pmFindVectorPeaks, then test each row
     257 * peak and exclude peaks which are not local peaks. A peak is a local peak if it
     258 * has a higher value than all 8 neighbors. If the peak has the same value as its
     259 * +y neighbor or +x neighbor, it is NOT a local peak. If any other neighbors
     260 * have an equal value, the peak is considered a valid peak. Note two points:
     261 * first, the +x neighbor condition is already enforced by pmFindVectorPeaks.
     262 * Second, these rules have the effect of making flat-topped regions have single
     263 * peaks at the (+x,+y) corner. When selecting the peaks, their type must also be
     264 * set. The result of this function is an array of pmPeak entries.
     265 *
     266 */
    176267psArray *pmFindImagePeaks(
    177     const psImage *image,               ///< The input image where peaks will be found (float)
    178     float threshold                     ///< Threshold above which to find a peak
    179 );
    180 
    181 /******************************************************************************
    182 psCullPeaks(peaks, maxValue, valid): eliminate peaks from the psList that have
    183 a peak value above the given maximum, or fall outside the valid region.
    184  *****************************************************************************/
     268    const psImage *image,  ///< The input image where peaks will be found (float)
     269    float threshold   ///< Threshold above which to find a peak
     270);
     271
     272
     273/** pmCullPeaks()
     274 *
     275 * Eliminate peaks from the psList that have a peak value above the given
     276 * maximum, or fall outside the valid region.
     277 *
     278 */
    185279psList *pmCullPeaks(
    186     psList *peaks,                      ///< The psList of peaks to be culled
    187     float maxValue,                     ///< Cull peaks above this value
    188     const psRegion valid               ///< Cull peaks otside this psRegion
    189 );
    190 
    191 /******************************************************************************
    192 pmSource *pmSourceLocalSky(image, peak, innerRadius, outerRadius):
    193  
    194  *****************************************************************************/
    195 pmSource *pmSourceLocalSky(
    196     const psImage *image,               ///< The input image (float)
    197     const pmPeak *peak,                 ///< The peak for which the psSource struct is created.
    198     psStatsOptions statsOptions,        ///< The statistic used in calculating the background sky
    199     float innerRadius,                  ///< The inner radius of the suqare annulus for calculating sky
    200     float outerRadius                   ///< The outer radius of the suqare annulus for calculating sky
    201 );
    202 
    203 /******************************************************************************
    204  *****************************************************************************/
    205 pmSource *pmSourceMoments(
    206     pmSource *source,                   ///< The input pmSource for which moments will be computed
    207     float radius                        ///< Use a circle of pixels around the peak
    208 );
    209 
    210 /******************************************************************************
    211 pmSourceRoughClass(pmArray *source, psMetaDeta *metadata): make a guess at the
    212 source classification.
    213  *****************************************************************************/
     280    psList *peaks,   ///< The psList of peaks to be culled
     281    float maxValue,   ///< Cull peaks above this value
     282    const psRegion valid                ///< Cull peaks otside this psRegion
     283);
     284
     285
     286/** pmPeaksSubset()
     287 *
     288 * Create a new peaks array, removing certain types of peaks from the input
     289 * array of peaks based on the given criteria. Peaks should be eliminated if they
     290 * have a peak value above the given maximum value limit or if the fall outside
     291 * the valid region.  The result of the function is a new array with a reduced
     292 * number of peaks.
     293 *
     294 */
     295psArray *pmPeaksSubset(
     296    psArray *peaks,                     ///< Add comment.
     297    float maxvalue,                     ///< Add comment.
     298    const psRegion valid                ///< Add comment.
     299);
     300
     301
     302/** pmSourceDefinePixels()
     303 *
     304 * Define psImage subarrays for the source located at coordinates x,y on the
     305 * image set defined by readout. The pixels defined by this operation consist of
     306 * a square window (of full width 2Radius+1) centered on the pixel which contains
     307 * the given coordinate, in the frame of the readout. The window is defined to
     308 * have limits which are valid within the boundary of the readout image, thus if
     309 * the radius would fall outside the image pixels, the subimage is truncated to
     310 * only consist of valid pixels. If readout->mask or readout->weight are not
     311 * NULL, matching subimages are defined for those images as well. This function
     312 * fails if no valid pixels can be defined (x or y less than Radius, for
     313 * example). This function should be used to define a region of interest around a
     314 * source, including both source and sky pixels.
     315 *
     316 * XXX: must code this.
     317 *
     318 */
     319// XXX: Uncommenting the pmReadout causes compile errors.
     320bool pmSourceDefinePixels(
     321    pmSource *mySource,                 ///< Add comment.
     322    pmReadout *readout,                 ///< Add comment.
     323    psF32 x,                            ///< Add comment.
     324    psF32 y,                            ///< Add comment.
     325    psF32 Radius                        ///< Add comment.
     326);
     327
     328
     329/** pmSourceLocalSky()
     330 *
     331 * Measure the local sky in the vicinity of the given source. The Radius
     332 * defines the square aperture in which the moments will be measured. This
     333 * function assumes the source pixels have been defined, and that the value of
     334 * Radius here is smaller than the value of Radius used to define the pixels. The
     335 * annular region not contained within the radius defined here is used to measure
     336 * the local background in the vicinity of the source. The local background
     337 * measurement uses the specified statistic passed in via the statsOptions entry.
     338 * This function allocates the pmMoments structure. The resulting sky is used to
     339 * set the value of the pmMoments.sky element of the provided pmSource structure.
     340 *
     341 */
     342bool pmSourceLocalSky(
     343    pmSource *source,   ///< The input image (float)
     344    psStatsOptions statsOptions, ///< The statistic used in calculating the background sky
     345    float Radius   ///< The inner radius of the square annulus to exclude
     346);
     347
     348
     349/** pmSourceMoments()
     350 *
     351 * Measure source moments for the given source, using the value of
     352 * source.moments.sky provided as the local background value and the peak
     353 * coordinates as the initial source location. The resulting moment values are
     354 * applied to the source.moments entry, and the source is returned. The moments
     355 * are measured within the given circular radius of the source.peak coordinates.
     356 * The return value indicates the success (TRUE) of the operation.
     357 *
     358 */
     359bool pmSourceMoments(
     360    pmSource *source,   ///< The input pmSource for which moments will be computed
     361    float radius   ///< Use a circle of pixels around the peak
     362);
     363
     364
     365/** pmSourcePSFClump()
     366 *
     367 * We use the source moments to make an initial, approximate source
     368 * classification, and as part of the information needed to build a PSF model for
     369 * the image. As long as the PSF shape does not vary excessively across the
     370 * image, the sources which are represented by a PSF (the start) will have very
     371 * similar second moments. The function pmSourcePSFClump searches a collection of
     372 * sources with measured moments for a group with moments which are all very
     373 * similar. The function returns a pmPSFClump structure, representing the
     374 * centroid and size of the clump in the sigma_x, sigma_y second-moment plane.
     375 *
     376 * The goal is to identify and characterize the stellar clump within the
     377 * sigma_x, sigma_y second-moment plane.  To do this, an image is constructed to
     378 * represent this plane.  The units of sigma_x and sigma_y are in image pixels. A
     379 * pixel in this analysis image represents 0.1 pixels in the input image. The
     380 * dimensions of the image need only be 10 pixels. The peak pixel in this image
     381 * (above a threshold of half of the image maximum) is found. The coordinates of
     382 * this peak pixel represent the 2D mode of the sigma_x, sigma_y distribution.
     383 * The sources with sigma_x, sigma_y within 0.2 pixels of this value are then
     384 *  * used to calculate the median and standard deviation of the sigma_x, sigma_y
     385 * values. These resulting values are returned via the pmPSFClump structure.
     386 *
     387 * The return value indicates the success (TRUE) of the operation.
     388 *
     389 * XXX: Limit the S/N of the candidate sources (part of Metadata)? (TBD).
     390 * XXX: Save the clump parameters on the Metadata (TBD)
     391 *
     392 */
     393pmPSFClump pmSourcePSFClump(
     394    psArray *source,   ///< The input pmSource
     395    psMetadata *metadata  ///< Contains classification parameters
     396);
     397
     398
     399/** pmSourceRoughClass()
     400 *
     401 * Based on the specified data values, make a guess at the source
     402 * classification. The sources are provides as a psArray of pmSource entries.
     403 * Definable parameters needed to make the classification are provided to the
     404 * routine with the psMetadata structure. The rules (in SDRS) refer to values which
     405 * can be extracted from the metadata using the given keywords. Except as noted,
     406 * the data type for these parameters are psF32.
     407 *
     408 */
    214409bool pmSourceRoughClass(
    215     psArray *source,                    ///< The input pmSource
    216     psMetadata *metadata                ///< Contains classification parameters
    217 );
    218 /******************************************************************************
    219 pmSourceSetPixelCircle(source, image, radius)
    220  *****************************************************************************/
    221 bool pmSourceSetPixelsCircle(
    222     pmSource *source,                   ///< The input pmSource
    223     const psImage *image,               ///< The input image (float)
    224     float radius                        ///< The radius of the circle
    225 );
    226 
    227 /******************************************************************************
    228  *****************************************************************************/
    229 bool pmSourceModelGuess(
    230     pmSource *source,                   ///< The input pmSource
    231     const psImage *image,               ///< The input image (float)
    232     pmModelType model                   ///< The type of model to be created.
    233 );
    234 
    235 /******************************************************************************
    236  *****************************************************************************/
     410    psArray *source,   ///< The input pmSource
     411    psMetadata *metadata,  ///< Contains classification parameters
     412    pmPSFClump clump   ///< Statistics about the PSF clump
     413);
     414
     415
     416/** pmSourceModelGuess()
     417 *
     418 * Convert available data to an initial guess for the given model. This
     419 * function allocates a pmModel entry for the pmSource structure based on the
     420 * provided model selection. The method of defining the model parameter guesses
     421 * are specified for each model below. The guess values are placed in the model
     422 * parameters. The function returns TRUE on success or FALSE on failure.
     423 *
     424 */
     425pmModel *pmSourceModelGuess(
     426    pmSource *source,   ///< The input pmSource
     427    pmModelType model   ///< The type of model to be created.
     428);
     429
     430
     431/** pmContourType
     432 *
     433 * Only one type is defined at present.
     434 *
     435 */
    237436typedef enum {
    238437    PS_CONTOUR_CRUDE,
     438    PS_CONTOUR_UNKNOWN01,
     439    PS_CONTOUR_UNKNOWN02
    239440} pmContourType;
    240441
     442
     443/** pmSourceContour()
     444 *
     445 * Find points in a contour for the given source at the given level. If type
     446 * is PM_CONTOUR_CRUDE, the contour is found by starting at the source peak,
     447 * running along each pixel row until the level is crossed, then interpolating to
     448 * the level coordinate for that row. This is done for each row, with the
     449 * starting point determined by the midpoint of the previous row, until the
     450 * starting point has a value below the contour level. The returned contour
     451 * consists of two vectors giving the x and y coordinates of the contour levels.
     452 * This function may be used as part of the model guess inputs.  Other contour
     453 * types may be specified in the future for more refined contours (TBD)
     454 *
     455 */
    241456psArray *pmSourceContour(
    242     pmSource *source,                   ///< The input pmSource
    243     const psImage *image,               ///< The input image (float) (this arg should be removed)
    244     float level,                        ///< The level of the contour
    245     pmContourType mode                  ///< Currently this must be PS_CONTOUR_CRUDE
    246 );
    247 
    248 /******************************************************************************
    249  *****************************************************************************/
     457    pmSource *source,   ///< The input pmSource
     458    const psImage *image,  ///< The input image (float) (this arg should be removed)
     459    float level,   ///< The level of the contour
     460    pmContourType mode   ///< Currently this must be PS_CONTOUR_CRUDE
     461);
     462
     463
     464/** pmSourceFitModel()
     465 *
     466 * Fit the requested model to the specified source. The starting guess for the
     467 * model is given by the input source.model parameter values. The pixels of
     468 * interest are specified by the source.pixelsand source.maskentries. This
     469 * function calls psMinimizeLMChi2() on the image data. The function returns TRUE
     470 * on success or FALSE on failure.
     471 *
     472 */
    250473bool pmSourceFitModel(
    251     pmSource *source,                   ///< The input pmSource
    252     const psImage *image                ///< The input image (float)
    253 );
    254 
    255 /******************************************************************************
    256  *****************************************************************************/
     474    pmSource *source,   ///< The input pmSource
     475    pmModel *model,   ///< model to be fitted
     476    const bool PSF   ///< Treat model as PSF or FLT?
     477);
     478
     479
     480/** pmModelFitStatus()
     481 *
     482 * This function wraps the call to the model-specific function returned by
     483 * pmModelFitStatusFunc_GetFunction.  The model-specific function examines the
     484 * model parameters, parameter errors, Chisq, S/N, and other parameters available
     485 * from model to decide if the particular fit was successful or not.
     486 *
     487 * XXX: Must code this.
     488 *
     489 */
     490bool pmModelFitStatus(
     491    pmModel *model                      ///< Add comment.
     492);
     493
     494
     495/** pmSourceAddModel()
     496 *
     497 * Add the given source model flux to/from the provided image. The boolean
     498 * option center selects if the source is re-centered to the image center or if
     499 * it is placed at its centroid location. The boolean option sky selects if the
     500 * background sky is applied (TRUE) or not. The pixel range in the target image
     501 * is at most the pixel range specified by the source.pixels image. The success
     502 * status is returned.
     503 *
     504 */
    257505bool pmSourceAddModel(
    258     psImage *image,                     ///< The opuut image (float)
    259     pmSource *source,                   ///< The input pmSource
    260     bool center                         ///< A boolean flag that determines whether pixels are centered
    261 );
    262 
    263 /******************************************************************************
    264  *****************************************************************************/
     506    psImage *image,   ///< The output image (float)
     507    psImage *mask,   ///< The image pixel mask (valid == 0)
     508    pmModel *model,   ///< The input pmModel
     509    bool center    ///< A boolean flag that determines whether pixels are centered
     510);
     511
     512
     513/** pmSourceSubModel()
     514 *
     515 * Subtract the given source model flux to/from the provided image. The
     516 * boolean option center selects if the source is re-centered to the image center
     517 * or if it is placed at its centroid location. The boolean option sky selects if
     518 * the background sky is applied (TRUE) or not. The pixel range in the target
     519 * image is at most the pixel range specified by the source.pixels image. The
     520 * success status is returned.
     521 *
     522 */
    265523bool pmSourceSubModel(
    266     psImage *image,                     ///< The output image (float)
    267     pmSource *source,                   ///< The input pmSource
    268     bool center                         ///< A boolean flag that determines whether pixels are centered
    269 );
    270 
    271 /******************************************************************************
    272 XXX: Why only *x argument?
    273 XXX EAM: psMinimizeLMChi2Func returns psF64, not float
    274  *****************************************************************************/
    275 float pmMinLM_Gauss2D(
    276     psVector *deriv,                    ///< A possibly-NULL structure for the output derivatives
    277     const psVector *params,             ///< A psVector which holds the parameters of this function
    278     const psVector *x                   ///< A psVector which holds the row/col coordinate
    279 );
    280 
    281 /******************************************************************************
    282  *****************************************************************************/
    283 float pmMinLM_PsuedoGauss2D(
    284     psVector *deriv,                    ///< A possibly-NULL structure for the output derivatives
    285     const psVector *params,             ///< A psVector which holds the parameters of this function
    286     const psVector *x                   ///< A psVector which holds the row/col coordinate
    287 );
    288 
    289 /******************************************************************************
    290  *****************************************************************************/
    291 float pmMinLM_Wauss2D(
    292     psVector *deriv,                    ///< A possibly-NULL structure for the output derivatives
    293     const psVector *params,             ///< A psVector which holds the parameters of this function
    294     const psVector *x                   ///< A psVector which holds the row/col coordinate
    295 );
    296 
    297 /******************************************************************************
    298  *****************************************************************************/
    299 float pmMinLM_TwistGauss2D(
    300     psVector *deriv,                    ///< A possibly-NULL structure for the output derivatives
    301     const psVector *params,             ///< A psVector which holds the parameters of this function
    302     const psVector *x                   ///< A psVector which holds the row/col coordinate
    303 );
    304 
    305 /******************************************************************************
    306  *****************************************************************************/
    307 float pmMinLM_Sersic(
    308     psVector *deriv,                    ///< A possibly-NULL structure for the output derivatives
    309     const psVector *params,             ///< A psVector which holds the parameters of this function
    310     const psVector *x                   ///< A psVector which holds the row/col coordinate
    311 );
    312 
    313 /******************************************************************************
    314  *****************************************************************************/
    315 float pmMinLM_SersicCore(
    316     psVector *deriv,                    ///< A possibly-NULL structure for the output derivatives
    317     const psVector *params,             ///< A psVector which holds the parameters of this function
    318     const psVector *x                   ///< A psVector which holds the row/col coordinate
    319 );
    320 
    321 /******************************************************************************
    322  *****************************************************************************/
    323 float pmMinLM_PsuedoSersic(
    324     psVector *deriv,                    ///< A possibly-NULL structure for the output derivatives
    325     const psVector *params,             ///< A psVector which holds the parameters of this function
    326     const psVector *x                   ///< A psVector which holds the row/col coordinate
     524    psImage *image,   ///< The output image (float)
     525    psImage *mask,   ///< The image pixel mask (valid == 0)
     526    pmModel *model,   ///< The input pmModel
     527    bool center    ///< A boolean flag that determines whether pixels are centered
    327528);
    328529
    … …  
    330531/**
    331532 *
    332  *  The object model functions are defined to allow for the flexible addition
    333  *  of new object models. Every object model, with parameters represented by
    334  *  pmModel, has an associated set of functions which provide necessary support
    335  *  operations. A set of abstract functions allow the programmer to select the
    336  *  approriate function or property for a specific named object model.
    337  *
    338  */
     533 * The function returns both the magnitude of the fit, defined as -2.5log(flux),
     534 * where the flux is integrated under the model, theoretically from a radius of 0
     535 * to infinity. In practice, we integrate the model beyond 50sigma.  The aperture magnitude is
     536 * defined as -2.5log(flux) , where the flux is summed for all pixels which are
     537 * not excluded by the aperture mask. The model flux is calculated by calling the
     538 * model-specific function provided by pmModelFlux_GetFunction.
     539 *
     540 * XXX: must code this.
     541 *
     542 */
     543bool pmSourcePhotometry(
     544    float *fitMag,                      ///< integrated fit magnitude
     545    float *obsMag,   ///< aperture flux magnitude
     546    pmModel *model,                     ///< model used for photometry
     547    psImage *image,                     ///< image pixels to be used
     548    psImage *mask                       ///< mask of pixels to ignore
     549);
     550
    339551
    340552/**
    341553 *
    342  *  This function is the model chi-square minimization function for this model.
    343  *
    344  */
    345 typedef psMinimizeLMChi2Func pmModelFunc;
    346 
    347 
    348 /**
    349  *
    350  * This function returns the integrated flux for the given model parameters.
    351  */
    352 typedef psF64 (*pmModelFlux)(const psVector *params);
    353 
    354 
    355 /**
    356  *
    357  *  This function provides the model guess parameters based on the details of
    358  *   the given source.
    359  *
    360  */
    361 typedef bool (*pmModelGuessFunc)(pmModel *model, pmSource *source);
    362 
    363 
    364 /**
    365  *
    366  *  This function constructs the PSF model for the given source based on the
    367  *  supplied psf and the FLT model for the object.
    368  *
    369  */
    370 typedef bool (*pmModelFromPSFFunc)(pmModel *modelPSF, pmModel *modelFLT, pmPSF *psf);
    371 
    372 
    373 /**
    374  *
    375  *  This function returns the radius at which the given model and parameters
    376  *  achieves the given flux.
    377  *
    378  */
    379 typedef psF64 (*pmModelRadius)(const psVector *params, double flux);
    380 
    381 
    382 /**
    383  *
    384  *  Each of the function types above has a corresponding function which returns
    385  *  the function given the model type:
    386  *
    387  */
    388 pmModelFunc pmModelFunc_GetFunction (pmModelType type);
    389 pmModelFlux pmModelFlux_GetFunction (pmModelType type);
    390 pmModelGuessFunc pmModelGuessFunc_GetFunction (pmModelType type);
    391 pmModelFromPSFFunc pmModelFromPSFFunc_GetFunction (pmModelType type);
    392 pmModelRadius pmModelRadius_GetFunction (pmModelType type);
    393 psS32 pmModelParameterCount(pmModelType type);
    394 psS32 pmModelSetType(char *name);
    395 char *pmModelGetType(pmModelType type);
     554 * This function converts the source classification into the closest available
     555 * approximation to the Dophot classification scheme:
     556 *
     557 * PM_SOURCE_DEFECT: 8
     558 * PM_SOURCE_SATURATED: 8
     559 * PM_SOURCE_SATSTAR: 10
     560 * PM_SOURCE_PSFSTAR: 1
     561 * PM_SOURCE_GOODSTAR: 1
     562 * PM_SOURCE_POOR_FIT_PSF: 7
     563 * PM_SOURCE_FAIL_FIT_PSF: 4
     564 * PM_SOURCE_FAINTSTAR: 4
     565 * PM_SOURCE_GALAXY: 2
     566 * PM_SOURCE_FAINT_GALAXY: 2
     567 * PM_SOURCE_DROP_GALAXY: 2
     568 * PM_SOURCE_FAIL_FIT_GAL: 2
     569 * PM_SOURCE_POOR_FIT_GAL: 2
     570 * PM_SOURCE_OTHER: ?
     571 *
     572 */
     573int pmSourceDophotType(
     574    pmSource *source                    ///< Add comment.
     575);
     576
     577
     578/** pmSourceSextractType()
     579 *
     580 * This function converts the source classification into the closest available
     581 * approximation to the Sextractor classification scheme. the correspondence is
     582 * not yet defined (TBD) .
     583 *
     584 * XXX: Must code this.
     585 *
     586 */
     587int pmSourceSextractType(
     588    pmSource *source                    ///< Add comment.
     589);
     590
     591/** pmSourceFitModel_v5()
     592 *
     593 * Fit the requested model to the specified source. The starting guess for the
     594 * model is given by the input source.model parameter values. The pixels of
     595 * interest are specified by the source.pixelsand source.maskentries. This
     596 * function calls psMinimizeLMChi2() on the image data. The function returns TRUE
     597 * on success or FALSE on failure.
     598 *
     599 */
     600bool pmSourceFitModel_v5(
     601    pmSource *source,   ///< The input pmSource
     602    pmModel *model,   ///< model to be fitted
     603    const bool PSF   ///< Treat model as PSF or FLT?
     604);
     605
     606
     607/** pmSourceFitModel_v7()
     608 *
     609 * Fit the requested model to the specified source. The starting guess for the
     610 * model is given by the input source.model parameter values. The pixels of
     611 * interest are specified by the source.pixelsand source.maskentries. This
     612 * function calls psMinimizeLMChi2() on the image data. The function returns TRUE
     613 * on success or FALSE on failure.
     614 *
     615 */
     616bool pmSourceFitModel_v7(
     617    pmSource *source,   ///< The input pmSource
     618    pmModel *model,   ///< model to be fitted
     619    const bool PSF   ///< Treat model as PSF or FLT?
     620);
    396621
    397622#endif
Note: See TracChangeset for help on using the changeset viewer.