Changeset 6872 for trunk/psModules/src/objects/pmObjects.h
- Timestamp:
- Apr 17, 2006, 8:01:05 AM (20 years ago)
- File:
-
- 1 edited
-
trunk/psModules/src/objects/pmObjects.h (modified) (4 diffs)
Legend:
- Unmodified
- Added
- Removed
-
trunk/psModules/src/objects/pmObjects.h
r5844 r6872 10 10 * @author GLG, MHPCC 11 11 * 12 * @version $Revision: 1. 5$ $Name: not supported by cvs2svn $13 * @date $Date: 200 5-12-24 01:24:32$12 * @version $Revision: 1.6 $ $Name: not supported by cvs2svn $ 13 * @date $Date: 2006-04-17 18:01:05 $ 14 14 * 15 15 * Copyright 2004 Maui High Performance Computing Center, University of Hawaii … … 27 27 #include <math.h> 28 28 #include "pslib.h" 29 #include "pmAstrometry.h"30 /**31 * In the object analysis process, we will use specific mask values to mark the32 * 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 values35 * outside of the PSPHOT code. Perhaps we can set up a registered set of mask36 * values with specific meanings that other functions can add to or define?37 */38 typedef enum {39 PSPHOT_MASK_CLEAR = 0x00,40 PSPHOT_MASK_INVALID = 0x01,41 PSPHOT_MASK_SATURATED = 0x02,42 PSPHOT_MASK_MARKED = 0x08,43 } psphotMaskValues;44 45 46 /** pmPeakType47 *48 * A peak pixel may have several features which may be determined when the49 * peak is found or measured. These are specified by the pmPeakType enum.50 * PM_PEAK_LONE represents a single pixel which is higher than its 8 immediate51 * neighbors. The PM_PEAK_EDGE represents a peak pixel which touching the image52 * edge. The PM_PEAK_FLAT represents a peak pixel which has more than a specific53 * number of neighbors at the same value, within some tolarence:54 *55 */56 typedef enum {57 PM_PEAK_LONE, ///< Isolated peak.58 PM_PEAK_EDGE, ///< Peak on edge.59 PM_PEAK_FLAT, ///< Peak has equal-value neighbors.60 PM_PEAK_UNDEF ///< Undefined.61 } pmPeakType;62 63 64 /** pmPeak data structure65 *66 * A source has the capacity for several types of measurements. The67 * simplest measurement of a source is the location and flux of the peak pixel68 * associated with the source:69 *70 */71 typedef struct72 {73 int x; ///< X-coordinate of peak pixel.74 int y; ///< Y-coordinate of peak pixel.75 float counts; ///< Value of peak pixel (above sky?).76 pmPeakType class; ///< Description of peak.77 }78 pmPeak;79 80 81 /** pmMoments data structure82 *83 * One of the simplest measurements which can be made quickly for an object84 * are the object moments. We specify a structure to carry the moment information85 * for a specific source:86 *87 */88 typedef struct89 {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-noise99 int nPixels; ///< Number of pixels used.100 }101 pmMoments;102 103 104 /** pmPSFClump data structure105 *106 * A collection of object moment measurements can be used to determine107 * approximate object classes. The key to this analysis is the location and108 * statistics (in the second-moment plane,109 *110 */111 typedef struct112 {113 float X;114 float dX;115 float Y;116 float dY;117 }118 pmPSFClump;119 120 // type of model carried by the pmModel structure121 typedef int pmModelType;122 123 typedef enum {124 PM_MODEL_UNTRIED, ///< model fit not yet attempted125 PM_MODEL_SUCCESS, ///< model fit succeeded126 PM_MODEL_NONCONVERGE, ///< model fit did not converge127 PM_MODEL_OFFIMAGE, ///< model fit drove out of range128 PM_MODEL_BADARGS ///< model fit called with invalid args129 } pmModelStatus;130 131 /** pmModel data structure132 *133 * Every source may have two types of models: a PSF model and a FLT (floating)134 * model. The PSF model represents the best fit of the image PSF to the specific135 * object. In this case, the PSF-dependent parameters are specified for the136 * object by the PSF, not by the fit. The FLT model represents the best fit of137 * the given model to the object, with all parameters floating in the fit.138 *139 */140 typedef struct141 {142 pmModelType type; ///< Model to be used.143 psVector *params; ///< Paramater values.144 psVector *dparams; ///< Parameter errors.145 float chisq; ///< Fit chi-squared.146 int nDOF; ///< number of degrees of freedom147 int nIter; ///< number of iterations to reach min148 int status; ///< fit status149 float radius; ///< fit radius actually used150 }151 pmModel;152 153 /** pmSourceType enumeration154 *155 * A given source may be identified as most-likely to be one of several source156 * types. The pmSource entry pmSourceType defines the current best-guess for this157 * source.158 *159 * XXX: The values given below are currently illustrative and will require160 * some modification as the source classification code is developed. (TBD)161 *162 */163 typedef enum {164 PM_SOURCE_DEFECT, ///< a cosmic-ray165 PM_SOURCE_SATURATED, ///< random saturated pixels166 167 PM_SOURCE_SATSTAR, ///< a saturated star168 PM_SOURCE_PSFSTAR, ///< a PSF star169 PM_SOURCE_GOODSTAR, ///< a good-quality star170 171 PM_SOURCE_POOR_FIT_PSF, ///< poor quality PSF fit172 PM_SOURCE_FAIL_FIT_PSF, ///< failed to get a good PSF fit173 PM_SOURCE_FAINTSTAR, ///< below S/N cutoff174 175 PM_SOURCE_GALAXY, ///< an extended object (galaxy)176 PM_SOURCE_FAINT_GALAXY, ///< a galaxy below S/N cutoff177 PM_SOURCE_DROP_GALAXY, ///< ?178 PM_SOURCE_FAIL_FIT_GAL, ///< failed on the galaxy fit179 PM_SOURCE_POOR_FIT_GAL, ///< poor quality galaxy fit180 181 PM_SOURCE_OTHER, ///< unidentified182 } pmSourceType;183 184 /** pmSource data structure185 *186 * This source has the capacity for several types of measurements. The187 * simplest measurement of a source is the location and flux of the peak pixel188 * associated with the source:189 *190 */191 typedef struct192 {193 pmPeak *peak; ///< Description of peak pixel.194 psImage *pixels; ///< Rectangular region including object pixels.195 psImage *weight; ///< Image variance.196 psImage *mask; ///< Mask which marks pixels associated with objects.197 pmMoments *moments; ///< Basic moments measure for the object.198 pmModel *modelPSF; ///< PSF Model fit (parameters and type)199 pmModel *modelFLT; ///< FLT (floating) Model fit (parameters and type).200 pmSourceType type; ///< Best identification of object.201 float apMag;202 float fitMag;203 }204 pmSource;205 206 207 /** pmPeakAlloc()208 *209 * @return pmPeak* newly allocated pmPeak with all internal pointers set to NULL210 */211 pmPeak *pmPeakAlloc(212 int x, ///< Row-coordinate in image space213 int y, ///< Col-coordinate in image space214 float counts, ///< The value of the peak pixel215 pmPeakType class ///< The type of peak pixel216 );217 218 219 /** pmMomentsAlloc()220 *221 */222 pmMoments *pmMomentsAlloc();223 224 225 /** pmModelAlloc()226 *227 */228 pmModel *pmModelAlloc(pmModelType type);229 230 231 /** pmSourceAlloc()232 *233 */234 pmSource *pmSourceAlloc();235 236 237 /** pmFindVectorPeaks()238 *239 * Find all local peaks in the given vector above the given threshold. A peak240 * is defined as any element with a value greater than its two neighbors and with241 * a value above the threshold. Two types of special cases must be addressed.242 * Equal value elements: If an element has the same value as the following243 * element, it is not considered a peak. If an element has the same value as the244 * preceding element (but not the following), then it is considered a peak. Note245 * that this rule (arbitrarily) identifies flat regions by their trailing edge.246 * Edge cases: At start of the vector, the element must be higher than its247 * neighbor. At the end of the vector, the element must be higher or equal to its248 * neighbor. These two rules again places the peak associated with a flat region249 * which touches the image edge at the image edge. The result of this function is250 * a vector containing the coordinates (element number) of the detected peaks251 * (type psU32).252 *253 */254 psVector *pmFindVectorPeaks(255 const psVector *vector, ///< The input vector (float)256 float threshold ///< Threshold above which to find a peak257 );258 259 260 /** pmFindImagePeaks()261 *262 * Find all local peaks in the given image above the given threshold. This263 * function should find all row peaks using pmFindVectorPeaks, then test each row264 * peak and exclude peaks which are not local peaks. A peak is a local peak if it265 * has a higher value than all 8 neighbors. If the peak has the same value as its266 * +y neighbor or +x neighbor, it is NOT a local peak. If any other neighbors267 * have an equal value, the peak is considered a valid peak. Note two points:268 * first, the +x neighbor condition is already enforced by pmFindVectorPeaks.269 * Second, these rules have the effect of making flat-topped regions have single270 * peaks at the (+x,+y) corner. When selecting the peaks, their type must also be271 * set. The result of this function is an array of pmPeak entries.272 *273 */274 psArray *pmFindImagePeaks(275 const psImage *image, ///< The input image where peaks will be found (float)276 float threshold ///< Threshold above which to find a peak277 );278 279 280 /** pmCullPeaks()281 *282 * Eliminate peaks from the psList that have a peak value above the given283 * maximum, or fall outside the valid region.284 *285 */286 psList *pmCullPeaks(287 psList *peaks, ///< The psList of peaks to be culled288 float maxValue, ///< Cull peaks above this value289 const psRegion valid ///< Cull peaks otside this psRegion290 );291 292 293 /** pmPeaksSubset()294 *295 * Create a new peaks array, removing certain types of peaks from the input296 * array of peaks based on the given criteria. Peaks should be eliminated if they297 * have a peak value above the given maximum value limit or if the fall outside298 * the valid region. The result of the function is a new array with a reduced299 * number of peaks.300 *301 */302 psArray *pmPeaksSubset(303 psArray *peaks, ///< Add comment.304 float maxvalue, ///< Add comment.305 const psRegion valid ///< Add comment.306 );307 308 309 /** pmSourceDefinePixels()310 *311 * Define psImage subarrays for the source located at coordinates x,y on the312 * image set defined by readout. The pixels defined by this operation consist of313 * a square window (of full width 2Radius+1) centered on the pixel which contains314 * the given coordinate, in the frame of the readout. The window is defined to315 * have limits which are valid within the boundary of the readout image, thus if316 * the radius would fall outside the image pixels, the subimage is truncated to317 * only consist of valid pixels. If readout->mask or readout->weight are not318 * NULL, matching subimages are defined for those images as well. This function319 * fails if no valid pixels can be defined (x or y less than Radius, for320 * example). This function should be used to define a region of interest around a321 * source, including both source and sky pixels.322 *323 * XXX: must code this.324 *325 */326 // XXX: Uncommenting the pmReadout causes compile errors.327 bool pmSourceDefinePixels(328 pmSource *mySource, ///< Add comment.329 pmReadout *readout, ///< Add comment.330 psF32 x, ///< Add comment.331 psF32 y, ///< Add comment.332 psF32 Radius ///< Add comment.333 );334 335 336 /** pmSourceLocalSky()337 *338 * Measure the local sky in the vicinity of the given source. The Radius339 * defines the square aperture in which the moments will be measured. This340 * function assumes the source pixels have been defined, and that the value of341 * Radius here is smaller than the value of Radius used to define the pixels. The342 * annular region not contained within the radius defined here is used to measure343 * the local background in the vicinity of the source. The local background344 * measurement uses the specified statistic passed in via the statsOptions entry.345 * This function allocates the pmMoments structure. The resulting sky is used to346 * set the value of the pmMoments.sky element of the provided pmSource structure.347 *348 */349 bool pmSourceLocalSky(350 pmSource *source, ///< The input image (float)351 psStatsOptions statsOptions, ///< The statistic used in calculating the background sky352 float Radius ///< The inner radius of the square annulus to exclude353 );354 355 356 /** pmSourceMoments()357 *358 * Measure source moments for the given source, using the value of359 * source.moments.sky provided as the local background value and the peak360 * coordinates as the initial source location. The resulting moment values are361 * applied to the source.moments entry, and the source is returned. The moments362 * are measured within the given circular radius of the source.peak coordinates.363 * The return value indicates the success (TRUE) of the operation.364 *365 */366 bool pmSourceMoments(367 pmSource *source, ///< The input pmSource for which moments will be computed368 float radius ///< Use a circle of pixels around the peak369 );370 371 372 /** pmSourcePSFClump()373 *374 * We use the source moments to make an initial, approximate source375 * classification, and as part of the information needed to build a PSF model for376 * the image. As long as the PSF shape does not vary excessively across the377 * image, the sources which are represented by a PSF (the start) will have very378 * similar second moments. The function pmSourcePSFClump searches a collection of379 * sources with measured moments for a group with moments which are all very380 * similar. The function returns a pmPSFClump structure, representing the381 * centroid and size of the clump in the sigma_x, sigma_y second-moment plane.382 *383 * The goal is to identify and characterize the stellar clump within the384 * sigma_x, sigma_y second-moment plane. To do this, an image is constructed to385 * represent this plane. The units of sigma_x and sigma_y are in image pixels. A386 * pixel in this analysis image represents 0.1 pixels in the input image. The387 * dimensions of the image need only be 10 pixels. The peak pixel in this image388 * (above a threshold of half of the image maximum) is found. The coordinates of389 * this peak pixel represent the 2D mode of the sigma_x, sigma_y distribution.390 * The sources with sigma_x, sigma_y within 0.2 pixels of this value are then391 * * used to calculate the median and standard deviation of the sigma_x, sigma_y392 * values. These resulting values are returned via the pmPSFClump structure.393 *394 * The return value indicates the success (TRUE) of the operation.395 *396 * XXX: Limit the S/N of the candidate sources (part of Metadata)? (TBD).397 * XXX: Save the clump parameters on the Metadata (TBD)398 *399 */400 pmPSFClump pmSourcePSFClump(401 psArray *source, ///< The input pmSource402 psMetadata *metadata ///< Contains classification parameters403 );404 405 406 /** pmSourceRoughClass()407 *408 * Based on the specified data values, make a guess at the source409 * classification. The sources are provides as a psArray of pmSource entries.410 * Definable parameters needed to make the classification are provided to the411 * routine with the psMetadata structure. The rules (in SDRS) refer to values which412 * can be extracted from the metadata using the given keywords. Except as noted,413 * the data type for these parameters are psF32.414 *415 */416 bool pmSourceRoughClass(417 psArray *source, ///< The input pmSource418 psMetadata *metadata, ///< Contains classification parameters419 pmPSFClump clump ///< Statistics about the PSF clump420 );421 422 423 /** pmSourceModelGuess()424 *425 * Convert available data to an initial guess for the given model. This426 * function allocates a pmModel entry for the pmSource structure based on the427 * provided model selection. The method of defining the model parameter guesses428 * are specified for each model below. The guess values are placed in the model429 * parameters. The function returns TRUE on success or FALSE on failure.430 *431 */432 pmModel *pmSourceModelGuess(433 pmSource *source, ///< The input pmSource434 pmModelType model ///< The type of model to be created.435 );436 437 438 /** pmContourType439 *440 * Only one type is defined at present.441 *442 */443 typedef enum {444 PS_CONTOUR_CRUDE,445 PS_CONTOUR_UNKNOWN01,446 PS_CONTOUR_UNKNOWN02447 } pmContourType;448 449 450 /** pmSourceContour()451 *452 * Find points in a contour for the given source at the given level. If type453 * is PM_CONTOUR_CRUDE, the contour is found by starting at the source peak,454 * running along each pixel row until the level is crossed, then interpolating to455 * the level coordinate for that row. This is done for each row, with the456 * starting point determined by the midpoint of the previous row, until the457 * starting point has a value below the contour level. The returned contour458 * consists of two vectors giving the x and y coordinates of the contour levels.459 * This function may be used as part of the model guess inputs. Other contour460 * types may be specified in the future for more refined contours (TBD)461 *462 */463 psArray *pmSourceContour(464 pmSource *source, ///< The input pmSource465 const psImage *image, ///< The input image (float) (this arg should be removed)466 float level, ///< The level of the contour467 pmContourType mode ///< Currently this must be PS_CONTOUR_CRUDE468 );469 470 471 /** pmSourceFitModel()472 *473 * Fit the requested model to the specified source. The starting guess for the474 * model is given by the input source.model parameter values. The pixels of475 * interest are specified by the source.pixelsand source.maskentries. This476 * function calls psMinimizeLMChi2() on the image data. The function returns TRUE477 * on success or FALSE on failure.478 *479 */480 bool pmSourceFitModel(481 pmSource *source, ///< The input pmSource482 pmModel *model, ///< model to be fitted483 const bool PSF ///< Treat model as PSF or FLT?484 );485 486 487 /** pmModelFitStatus()488 *489 * This function wraps the call to the model-specific function returned by490 * pmModelFitStatusFunc_GetFunction. The model-specific function examines the491 * model parameters, parameter errors, Chisq, S/N, and other parameters available492 * from model to decide if the particular fit was successful or not.493 *494 * XXX: Must code this.495 *496 */497 bool pmModelFitStatus(498 pmModel *model ///< Add comment.499 );500 501 502 /** pmSourceAddModel()503 *504 * Add the given source model flux to/from the provided image. The boolean505 * option center selects if the source is re-centered to the image center or if506 * it is placed at its centroid location. The boolean option sky selects if the507 * background sky is applied (TRUE) or not. The pixel range in the target image508 * is at most the pixel range specified by the source.pixels image. The success509 * status is returned.510 *511 */512 bool pmSourceAddModel(513 psImage *image, ///< The output image (float)514 psImage *mask, ///< The image pixel mask (valid == 0)515 pmModel *model, ///< The input pmModel516 bool center, ///< A boolean flag that determines whether pixels are centered517 bool sky ///< A boolean flag that determines if the sky is subtracted518 );519 520 521 /** pmSourceSubModel()522 *523 * Subtract the given source model flux to/from the provided image. The524 * boolean option center selects if the source is re-centered to the image center525 * or if it is placed at its centroid location. The boolean option sky selects if526 * the background sky is applied (TRUE) or not. The pixel range in the target527 * image is at most the pixel range specified by the source.pixels image. The528 * success status is returned.529 *530 */531 bool pmSourceSubModel(532 psImage *image, ///< The output image (float)533 psImage *mask, ///< The image pixel mask (valid == 0)534 pmModel *model, ///< The input pmModel535 bool center, ///< A boolean flag that determines whether pixels are centered536 bool sky ///< A boolean flag that determines if the sky is subtracted537 );538 539 540 /**541 *542 * The function returns both the magnitude of the fit, defined as -2.5log(flux),543 * where the flux is integrated under the model, theoretically from a radius of 0544 * to infinity. In practice, we integrate the model beyond 50sigma. The aperture magnitude is545 * defined as -2.5log(flux) , where the flux is summed for all pixels which are546 * not excluded by the aperture mask. The model flux is calculated by calling the547 * model-specific function provided by pmModelFlux_GetFunction.548 *549 * XXX: must code this.550 *551 */552 bool pmSourcePhotometry(553 float *fitMag, ///< integrated fit magnitude554 float *obsMag, ///< aperture flux magnitude555 pmModel *model, ///< model used for photometry556 psImage *image, ///< image pixels to be used557 psImage *mask ///< mask of pixels to ignore558 );559 560 29 561 30 /** … … 563 32 * This function converts the source classification into the closest available 564 33 * approximation to the Dophot classification scheme: 34 * XXX EAM : fix this to use current source classification scheme 565 35 * 566 36 * PM_SOURCE_DEFECT: 8 … … 598 68 ); 599 69 600 /** pmSourceFitModel_v5()601 *602 * Fit the requested model to the specified source. The starting guess for the603 * model is given by the input source.model parameter values. The pixels of604 * interest are specified by the source.pixelsand source.maskentries. This605 * function calls psMinimizeLMChi2() on the image data. The function returns TRUE606 * on success or FALSE on failure.607 *608 */609 bool pmSourceFitModel_v5(610 pmSource *source, ///< The input pmSource611 pmModel *model, ///< model to be fitted612 const bool PSF ///< Treat model as PSF or FLT?613 );614 615 616 /** pmSourceFitModel_v7()617 *618 * Fit the requested model to the specified source. The starting guess for the619 * model is given by the input source.model parameter values. The pixels of620 * interest are specified by the source.pixelsand source.maskentries. This621 * function calls psMinimizeLMChi2() on the image data. The function returns TRUE622 * on success or FALSE on failure.623 *624 */625 bool pmSourceFitModel_v7(626 pmSource *source, ///< The input pmSource627 pmModel *model, ///< model to be fitted628 const bool PSF ///< Treat model as PSF or FLT?629 );630 631 632 /** pmSourcePhotometry()633 *634 * XXX: Need descriptions635 *636 */637 bool pmSourcePhotometry(638 float *fitMag,639 float *obsMag,640 pmModel *model,641 psImage *image,642 psImage *mask643 );644 645 /** pmModelEval()646 *647 * XXX: Need descriptions648 *649 */650 psF32 pmModelEval(651 pmModel *model,652 psImage *image,653 psS32 col,654 psS32 row655 );656 70 657 71 #endif
Note:
See TracChangeset
for help on using the changeset viewer.
