Changeset 6545 for branches/rel10_ifa/psModules/src/objects/pmObjects.h
- Timestamp:
- Mar 8, 2006, 8:01:07 AM (20 years ago)
- File:
-
- 1 edited
Legend:
- Unmodified
- Added
- Removed
-
branches/rel10_ifa/psModules/src/objects/pmObjects.h
r6448 r6545 10 10 * @author GLG, MHPCC 11 11 * 12 * @version $Revision: 1.5.4. 1$ $Name: not supported by cvs2svn $13 * @date $Date: 2006-0 2-17 17:13:42$12 * @version $Revision: 1.5.4.2 $ $Name: not supported by cvs2svn $ 13 * @date $Date: 2006-03-08 18:01:07 $ 14 14 * 15 15 * Copyright 2004 Maui High Performance Computing Center, University of Hawaii … … 28 28 #include "pslib.h" 29 29 #include "pmFPA.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 type; ///< 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 dSky; ///< local Sky variance99 float SN; ///< approx signal-to-noise100 int nPixels; ///< Number of pixels used.101 }102 pmMoments;103 104 105 /** pmPSFClump data structure106 *107 * A collection of object moment measurements can be used to determine108 * approximate object classes. The key to this analysis is the location and109 * statistics (in the second-moment plane,110 *111 */112 typedef struct113 {114 float X;115 float dX;116 float Y;117 float dY;118 }119 pmPSFClump;120 121 // type of model carried by the pmModel structure122 typedef int pmModelType;123 124 typedef enum {125 PM_MODEL_UNTRIED, ///< model fit not yet attempted126 PM_MODEL_SUCCESS, ///< model fit succeeded127 PM_MODEL_NONCONVERGE, ///< model fit did not converge128 PM_MODEL_OFFIMAGE, ///< model fit drove out of range129 PM_MODEL_BADARGS ///< model fit called with invalid args130 } pmModelStatus;131 132 /** pmModel data structure133 *134 * Every source may have two types of models: a PSF model and a EXT (extended-source)135 * model. The PSF model represents the best fit of the image PSF to the specific136 * object. In this case, the PSF-dependent parameters are specified for the137 * object by the PSF, not by the fit. The EXT model represents the best fit of138 * the given model to the object, with all shape parameters floating in the fit.139 *140 */141 typedef struct142 {143 pmModelType type; ///< Model to be used.144 psVector *params; ///< Paramater values.145 psVector *dparams; ///< Parameter errors.146 float chisq; ///< Fit chi-squared.147 int nDOF; ///< number of degrees of freedom148 int nIter; ///< number of iterations to reach min149 pmModelStatus status; ///< fit status150 float radius; ///< fit radius actually used151 }152 pmModel;153 154 /** pmSourceType enumeration155 *156 * A given source may be identified as most-likely to be one of several source157 * types. The pmSource entry pmSourceType defines the current best-guess for this158 * source.159 *160 * XXX: The values given below are currently illustrative and will require161 * some modification as the source classification code is developed. (TBD)162 *163 */164 typedef enum {165 PM_SOURCE_UNKNOWN, ///< a cosmic-ray166 PM_SOURCE_DEFECT, ///< a cosmic-ray167 PM_SOURCE_SATURATED, ///< random saturated pixels168 PM_SOURCE_STAR, ///< a good-quality star169 PM_SOURCE_EXTENDED, ///< an extended object (eg, galaxy)170 } pmSourceType;171 172 typedef enum {173 PM_SOURCE_DEFAULT = 0x0000, ///<174 PM_SOURCE_PSFMODEL = 0x0001, ///<175 PM_SOURCE_EXTMODEL = 0x0002, ///<176 PM_SOURCE_SUBTRACTED = 0x0004, ///<177 PM_SOURCE_FITTED = 0x0008, ///<178 PM_SOURCE_FAIL = 0x0010, ///<179 PM_SOURCE_POOR = 0x0020, ///<180 PM_SOURCE_PAIR = 0x0040, ///<181 PM_SOURCE_PSFSTAR = 0x0080, ///<182 PM_SOURCE_SATSTAR = 0x0100, ///<183 PM_SOURCE_BLEND = 0x0200, ///<184 PM_SOURCE_LINEAR = 0x0400, ///<185 PM_SOURCE_TEMPSUB = 0x0800, ///< XXX get me a better name!186 } pmSourceMode;187 188 /** pmSource data structure189 *190 * This source has the capacity for several types of measurements. The191 * simplest measurement of a source is the location and flux of the peak pixel192 * associated with the source:193 *194 */195 typedef struct196 {197 pmPeak *peak; ///< Description of peak pixel.198 psImage *pixels; ///< Rectangular region including object pixels.199 psImage *weight; ///< Image variance.200 psImage *mask; ///< Mask which marks pixels associated with objects.201 pmMoments *moments; ///< Basic moments measure for the object.202 pmModel *modelPSF; ///< PSF Model fit (parameters and type)203 pmModel *modelEXT; ///< EXT (floating) Model fit (parameters and type).204 pmSourceType type; ///< Best identification of object.205 pmSourceMode mode; ///< Best identification of object.206 psArray *blends;207 float apMag;208 float fitMag;209 psRegion region; // area on image covered by selected pixels210 }211 pmSource;212 213 214 /** pmPeakAlloc()215 *216 * @return pmPeak* newly allocated pmPeak with all internal pointers set to NULL217 */218 pmPeak *pmPeakAlloc(219 int x, ///< Row-coordinate in image space220 int y, ///< Col-coordinate in image space221 float counts, ///< The value of the peak pixel222 pmPeakType type ///< The type of peak pixel223 );224 225 226 /** pmMomentsAlloc()227 *228 */229 pmMoments *pmMomentsAlloc();230 231 232 /** pmModelAlloc()233 *234 */235 pmModel *pmModelAlloc(pmModelType type);236 237 238 /** pmSourceAlloc()239 *240 */241 pmSource *pmSourceAlloc();242 243 244 /** pmFindVectorPeaks()245 *246 * Find all local peaks in the given vector above the given threshold. A peak247 * is defined as any element with a value greater than its two neighbors and with248 * a value above the threshold. Two types of special cases must be addressed.249 * Equal value elements: If an element has the same value as the following250 * element, it is not considered a peak. If an element has the same value as the251 * preceding element (but not the following), then it is considered a peak. Note252 * that this rule (arbitrarily) identifies flat regions by their trailing edge.253 * Edge cases: At start of the vector, the element must be higher than its254 * neighbor. At the end of the vector, the element must be higher or equal to its255 * neighbor. These two rules again places the peak associated with a flat region256 * which touches the image edge at the image edge. The result of this function is257 * a vector containing the coordinates (element number) of the detected peaks258 * (type psU32).259 *260 */261 psVector *pmFindVectorPeaks(262 const psVector *vector, ///< The input vector (float)263 float threshold ///< Threshold above which to find a peak264 );265 266 267 /** pmFindImagePeaks()268 *269 * Find all local peaks in the given image above the given threshold. This270 * function should find all row peaks using pmFindVectorPeaks, then test each row271 * peak and exclude peaks which are not local peaks. A peak is a local peak if it272 * has a higher value than all 8 neighbors. If the peak has the same value as its273 * +y neighbor or +x neighbor, it is NOT a local peak. If any other neighbors274 * have an equal value, the peak is considered a valid peak. Note two points:275 * first, the +x neighbor condition is already enforced by pmFindVectorPeaks.276 * Second, these rules have the effect of making flat-topped regions have single277 * peaks at the (+x,+y) corner. When selecting the peaks, their type must also be278 * set. The result of this function is an array of pmPeak entries.279 *280 */281 psArray *pmFindImagePeaks(282 const psImage *image, ///< The input image where peaks will be found (float)283 float threshold ///< Threshold above which to find a peak284 );285 286 287 /** pmCullPeaks()288 *289 * Eliminate peaks from the psList that have a peak value above the given290 * maximum, or fall outside the valid region.291 *292 */293 psList *pmCullPeaks(294 psList *peaks, ///< The psList of peaks to be culled295 float maxValue, ///< Cull peaks above this value296 const psRegion valid ///< Cull peaks otside this psRegion297 );298 299 300 /** pmPeaksSubset()301 *302 * Create a new peaks array, removing certain types of peaks from the input303 * array of peaks based on the given criteria. Peaks should be eliminated if they304 * have a peak value above the given maximum value limit or if the fall outside305 * the valid region. The result of the function is a new array with a reduced306 * number of peaks.307 *308 */309 psArray *pmPeaksSubset(310 psArray *peaks, ///< Add comment.311 float maxvalue, ///< Add comment.312 const psRegion valid ///< Add comment.313 );314 315 316 /** pmSourceDefinePixels()317 *318 * Define psImage subarrays for the source located at coordinates x,y on the319 * image set defined by readout. The pixels defined by this operation consist of320 * a square window (of full width 2Radius+1) centered on the pixel which contains321 * the given coordinate, in the frame of the readout. The window is defined to322 * have limits which are valid within the boundary of the readout image, thus if323 * the radius would fall outside the image pixels, the subimage is truncated to324 * only consist of valid pixels. If readout->mask or readout->weight are not325 * NULL, matching subimages are defined for those images as well. This function326 * fails if no valid pixels can be defined (x or y less than Radius, for327 * example). This function should be used to define a region of interest around a328 * source, including both source and sky pixels.329 *330 * XXX: must code this.331 *332 */333 // XXX: Uncommenting the pmReadout causes compile errors.334 bool pmSourceDefinePixels(335 pmSource *mySource, ///< Add comment.336 pmReadout *readout, ///< Add comment.337 psF32 x, ///< Add comment.338 psF32 y, ///< Add comment.339 psF32 Radius ///< Add comment.340 );341 342 343 /** pmSourceLocalSky()344 *345 * Measure the local sky in the vicinity of the given source. The Radius346 * defines the square aperture in which the moments will be measured. This347 * function assumes the source pixels have been defined, and that the value of348 * Radius here is smaller than the value of Radius used to define the pixels. The349 * annular region not contained within the radius defined here is used to measure350 * the local background in the vicinity of the source. The local background351 * measurement uses the specified statistic passed in via the statsOptions entry.352 * This function allocates the pmMoments structure. The resulting sky is used to353 * set the value of the pmMoments.sky element of the provided pmSource structure.354 *355 */356 bool pmSourceLocalSky(357 pmSource *source, ///< The input image (float)358 psStatsOptions statsOptions, ///< The statistic used in calculating the background sky359 float Radius ///< The inner radius of the square annulus to exclude360 );361 362 363 // A complementary function to pmSourceLocalSky: calculate the local sky variance364 bool pmSourceLocalSkyVariance(365 pmSource *source, ///< The input image (float)366 psStatsOptions statsOptions, ///< The statistic used in calculating the background sky367 float Radius ///< The inner radius of the square annulus to exclude368 );369 370 /** pmSourceMoments()371 *372 * Measure source moments for the given source, using the value of373 * source.moments.sky provided as the local background value and the peak374 * coordinates as the initial source location. The resulting moment values are375 * applied to the source.moments entry, and the source is returned. The moments376 * are measured within the given circular radius of the source.peak coordinates.377 * The return value indicates the success (TRUE) of the operation.378 *379 */380 bool pmSourceMoments(381 pmSource *source, ///< The input pmSource for which moments will be computed382 float radius ///< Use a circle of pixels around the peak383 );384 385 386 /** pmSourcePSFClump()387 *388 * We use the source moments to make an initial, approximate source389 * classification, and as part of the information needed to build a PSF model for390 * the image. As long as the PSF shape does not vary excessively across the391 * image, the sources which are represented by a PSF (the start) will have very392 * similar second moments. The function pmSourcePSFClump searches a collection of393 * sources with measured moments for a group with moments which are all very394 * similar. The function returns a pmPSFClump structure, representing the395 * centroid and size of the clump in the sigma_x, sigma_y second-moment plane.396 *397 * The goal is to identify and characterize the stellar clump within the398 * sigma_x, sigma_y second-moment plane. To do this, an image is constructed to399 * represent this plane. The units of sigma_x and sigma_y are in image pixels. A400 * pixel in this analysis image represents 0.1 pixels in the input image. The401 * dimensions of the image need only be 10 pixels. The peak pixel in this image402 * (above a threshold of half of the image maximum) is found. The coordinates of403 * this peak pixel represent the 2D mode of the sigma_x, sigma_y distribution.404 * The sources with sigma_x, sigma_y within 0.2 pixels of this value are then405 * * used to calculate the median and standard deviation of the sigma_x, sigma_y406 * values. These resulting values are returned via the pmPSFClump structure.407 *408 * The return value indicates the success (TRUE) of the operation.409 *410 * XXX: Limit the S/N of the candidate sources (part of Metadata)? (TBD).411 * XXX: Save the clump parameters on the Metadata (TBD)412 *413 */414 pmPSFClump pmSourcePSFClump(415 psArray *source, ///< The input pmSource416 psMetadata *metadata ///< Contains classification parameters417 );418 419 420 /** pmSourceRoughClass()421 *422 * Based on the specified data values, make a guess at the source423 * classification. The sources are provides as a psArray of pmSource entries.424 * Definable parameters needed to make the classification are provided to the425 * routine with the psMetadata structure. The rules (in SDRS) refer to values which426 * can be extracted from the metadata using the given keywords. Except as noted,427 * the data type for these parameters are psF32.428 *429 */430 bool pmSourceRoughClass(431 psArray *source, ///< The input pmSource432 psMetadata *metadata, ///< Contains classification parameters433 pmPSFClump clump ///< Statistics about the PSF clump434 );435 436 437 /** pmSourceModelGuess()438 *439 * Convert available data to an initial guess for the given model. This440 * function allocates a pmModel entry for the pmSource structure based on the441 * provided model selection. The method of defining the model parameter guesses442 * are specified for each model below. The guess values are placed in the model443 * parameters. The function returns TRUE on success or FALSE on failure.444 *445 */446 pmModel *pmSourceModelGuess(447 pmSource *source, ///< The input pmSource448 pmModelType model ///< The type of model to be created.449 );450 451 452 /** pmContourType453 *454 * Only one type is defined at present.455 *456 */457 typedef enum {458 PS_CONTOUR_CRUDE,459 PS_CONTOUR_UNKNOWN01,460 PS_CONTOUR_UNKNOWN02461 } pmContourType;462 463 464 /** pmSourceContour()465 *466 * Find points in a contour for the given source at the given level. If type467 * is PM_CONTOUR_CRUDE, the contour is found by starting at the source peak,468 * running along each pixel row until the level is crossed, then interpolating to469 * the level coordinate for that row. This is done for each row, with the470 * starting point determined by the midpoint of the previous row, until the471 * starting point has a value below the contour level. The returned contour472 * consists of two vectors giving the x and y coordinates of the contour levels.473 * This function may be used as part of the model guess inputs. Other contour474 * types may be specified in the future for more refined contours (TBD)475 *476 */477 psArray *pmSourceContour(478 pmSource *source, ///< The input pmSource479 const psImage *image, ///< The input image (float) (this arg should be removed)480 float level, ///< The level of the contour481 pmContourType mode ///< Currently this must be PS_CONTOUR_CRUDE482 );483 484 485 bool pmSourceFitModelInit(486 float nIter, ///< max number of allowed iterations487 float tol ///< convergence criterion488 );489 490 /** pmSourceFitModel()491 *492 * Fit the requested model to the specified source. The starting guess for the493 * model is given by the input source.model parameter values. The pixels of494 * interest are specified by the source.pixelsand source.maskentries. This495 * function calls psMinimizeLMChi2() on the image data. The function returns TRUE496 * on success or FALSE on failure.497 *498 */499 bool pmSourceFitModel(500 pmSource *source, ///< The input pmSource501 pmModel *model, ///< model to be fitted502 const bool PSF ///< Treat model as PSF or EXT?503 );504 505 506 /** pmModelFitStatus()507 *508 * This function wraps the call to the model-specific function returned by509 * pmModelFitStatusFunc_GetFunction. The model-specific function examines the510 * model parameters, parameter errors, Chisq, S/N, and other parameters available511 * from model to decide if the particular fit was successful or not.512 *513 * XXX: Must code this.514 *515 */516 bool pmModelFitStatus(517 pmModel *model ///< Add comment.518 );519 520 521 /** pmSourceAddModel()522 *523 * Add the given source model flux to/from the provided image. The boolean524 * option center selects if the source is re-centered to the image center or if525 * it is placed at its centroid location. The boolean option sky selects if the526 * background sky is applied (TRUE) or not. The pixel range in the target image527 * is at most the pixel range specified by the source.pixels image. The success528 * status is returned.529 *530 */531 bool pmSourceAddModel(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 /** pmSourceSubModel()541 *542 * Subtract the given source model flux to/from the provided image. The543 * boolean option center selects if the source is re-centered to the image center544 * or if it is placed at its centroid location. The boolean option sky selects if545 * the background sky is applied (TRUE) or not. The pixel range in the target546 * image is at most the pixel range specified by the source.pixels image. The547 * success status is returned.548 *549 */550 bool pmSourceSubModel(551 psImage *image, ///< The output image (float)552 psImage *mask, ///< The image pixel mask (valid == 0)553 pmModel *model, ///< The input pmModel554 bool center, ///< A boolean flag that determines whether pixels are centered555 bool sky ///< A boolean flag that determines if the sky is subtracted556 );557 558 559 /**560 *561 * The function returns both the magnitude of the fit, defined as -2.5log(flux),562 * where the flux is integrated under the model, theoretically from a radius of 0563 * to infinity. In practice, we integrate the model beyond 50sigma. The aperture magnitude is564 * defined as -2.5log(flux) , where the flux is summed for all pixels which are565 * not excluded by the aperture mask. The model flux is calculated by calling the566 * model-specific function provided by pmModelFlux_GetFunction.567 *568 * XXX: must code this.569 *570 */571 bool pmSourcePhotometry(572 float *fitMag, ///< integrated fit magnitude573 float *obsMag, ///< aperture flux magnitude574 pmModel *model, ///< model used for photometry575 psImage *image, ///< image pixels to be used576 psImage *mask ///< mask of pixels to ignore577 );578 579 30 580 31 /** … … 618 69 ); 619 70 620 /** pmSourceFitModel_v5()621 *622 * Fit the requested model to the specified source. The starting guess for the623 * model is given by the input source.model parameter values. The pixels of624 * interest are specified by the source.pixelsand source.maskentries. This625 * function calls psMinimizeLMChi2() on the image data. The function returns TRUE626 * on success or FALSE on failure.627 *628 */629 bool pmSourceFitModel_v5(630 pmSource *source, ///< The input pmSource631 pmModel *model, ///< model to be fitted632 const bool PSF ///< Treat model as PSF or EXT?633 );634 635 636 /** pmSourceFitModel_v7()637 *638 * Fit the requested model to the specified source. The starting guess for the639 * model is given by the input source.model parameter values. The pixels of640 * interest are specified by the source.pixelsand source.maskentries. This641 * function calls psMinimizeLMChi2() on the image data. The function returns TRUE642 * on success or FALSE on failure.643 *644 */645 bool pmSourceFitModel_v7(646 pmSource *source, ///< The input pmSource647 pmModel *model, ///< model to be fitted648 const bool PSF ///< Treat model as PSF or EXT?649 );650 651 652 /** pmSourcePhotometry()653 *654 * XXX: Need descriptions655 *656 */657 bool pmSourcePhotometry(658 float *fitMag,659 float *obsMag,660 pmModel *model,661 psImage *image,662 psImage *mask663 );664 665 /** pmModelEval()666 *667 * XXX: Need descriptions668 *669 */670 psF32 pmModelEval(671 pmModel *model,672 psImage *image,673 psS32 col,674 psS32 row675 );676 71 677 72 #endif
Note:
See TracChangeset
for help on using the changeset viewer.
