/** @file  pmPSF.h
 *
 * This file contains typedefs for the Point-Spread Function and prototypes
 * for functions that calculate the PSF.
 *
 *  @author EAM, IfA
 *
 *  @version $Revision: 1.1 $ $Name: not supported by cvs2svn $
 *  @date $Date: 2005-10-10 19:53:40 $
 *
 *  Copyright 2004 Maui High Performance Computing Center, University of Hawaii
 *
 */

# ifndef PM_PSF_H
# define PM_PSF_H


/** pmPSF data structure
 * 
 * It is useful to generate a model to define the point-spread-function which
 * describes the flux distribution for unresolved sources in an image. In
 * general, the PSF varies with position in the image. We allow any of the source
 * models defined for the pmModel to represent the PSF. For a given source model,
 * the 2D spatial variation of all of the source parameters, except the first
 * four PSF-independent parameters, are represented as polynomial, stored in a
 * psArray. The other elements of the structure define the quality of the PSF
 * determination.
 * 
 */
typedef struct
{
    pmModelType type;   ///< PSF Model in use
    psArray *params;   ///< Model parameters (psPolynomial2D)
    float chisq;   ///< PSF goodness statistic
    float ApResid;                      ///< ???
    float dApResid;                     ///< ???
    float skyBias;                      ///< ???
    int nPSFstars;   ///< number of stars used to measure PSF
}
pmPSF;


/**
 * 
 * Allocator for the pmPSF structure.
 * 
 */
pmPSF *pmPSFAlloc(
    pmModelType type                    ///< Add comment
);


/**
 * 
 * This function takes a collection of pmModel fitted models from across a
 * single image and builds a pmPSF representation of the PSF. The input array of
 * model fits may consist of entries to be ignored (noted by a non-zero mask
 * entry). The analysis of the models fits a 2D polynomial for each parameter to
 * the collection of model parameters as a function of position (and
 * normalization?). In this process, some of the input models may be marked as
 * outliers and excluded from the fit. These elements will be marked with a
 * specific mask value (1 == PSFTRY_MASK_OUTLIER).
 * 
 */
bool pmPSFFromModels(
    pmPSF *psf,                         ///< Add comment
    psArray *models,                    ///< Add comment
    psVector *mask                      ///< Add comment
);


/**
 * 
 * This function constructs a pmModel instance based on the pmPSF description
 * of the PSF. The input is a pmModel with at least the values of the centroid
 * coordinates (possibly normalization if this is needed) defined. The values of
 * the PSF-dependent parameters are specified for the specific realization based
 * on the coordinates of the object.
 * 
 */
pmModel *pmModelFromPSF(
    pmModel *model,                     ///< Add comment
    pmPSF *psf                          ///< Add comment
);

# endif
