/** @file  pmAstrometryDistortion.h
*
*  @brief This file defines the basic types for measuring and fitting the focal-plane distortion.
*
*  @ingroup AstroImage
*
*  @author EAM, IfA
*
*  @version $Revision: 1.1 $ $Name: not supported by cvs2svn $
*  @date $Date: 2006-05-19 15:39:53 $
*
*  Copyright 2006 Institute for Astronomy, University of Hawaii
*/

#ifndef PM_ASTROMETRY_DISTORTION_H
#define PM_ASTROMETRY_DISTORTION_H

/* The following data structure carries the information about the residual
 * gradient of source positions in the tangent plane (pmAstromObj.TP) as a
 * function of position in the focal plane (pmAstromObj.FP).
 */
typedef struct
{
    psPlane FP;
    psPlane dTPdL;
    psPlane dTPdM;
}
pmAstromGradient;

pmAstromGradient *pmAstromGradientAlloc ();

/* The following function determines the position residual, in the tangent
 * plane, as a function of position in the focal plane, for a collection of raw
 * measurements and matched reference stars. The configuration data must include
 * the bin size over which the gradient is measured (keyword: ASTROM.GRAD.BOX).
 * The function returns an array of pmAstromGradient structures, defined below.
 */
psArray *pmAstromMeasureGradients(
    psArray *gradients,
    psArray *rawstars,
    psArray *refstars,
    psArray *matches,
    psMetadata *config
);

/* The gradient set measured above can be fitted with a pair of 2D
 * polynomials. The resulting fits can then be related back to the implied
 * polynomials which represent the distortion. The following function performs
 * the fit and applies the result to the distortion transformation of the
 * supplied pmFPA structure. The configuration variable supplies the polynomial
 * order (keyword: ASTROM.DISTORT.ORDER).
 */
bool pmAstromFitDistortion(
    pmFPA *fpa,
    psArray *gradients,
    psMetadata *config);

#endif // PM_ASTROMETRY_DISTORTION_H
