idlastro / FITS Astrometry and Calibration: SOLVE_ASTRO

[Source code]

NAME
SOLVE_ASTRO
PURPOSE
Solve for an TANgent-plane astrometric plate solution with optional 
distortion terms
EXPLANATION
SOLVE_ASTRO takes an input matched xpixel/ypixel/ra/dec list, and returns
an IDL astrometry structure containing the astrometric
solution. Optional sigma clipping on the fit. Similar in
principle to IRAF's ccmap.
CALLING SEQUENCE
astr  = SOLVE_ASTRO( ra_degrees, dec_degrees, xpixel, ypixel,
[XIORDER=, ETAORDER=, XTERMS= DISTORT=, CRVAL= NITER=, REJECT=,
XIRMS=, ETARMS= SUCCESS=,VERBOSE= NORTERMS= NREJ=, N_TPVTERMS=,
XIRESID=, ETARESID=, WFIT= ])
INPUT ARGUMENT
ra_degrees  - the right ascensions in degrees of the matched objects
dec_degrees - the declinations in degrees
xpixel      - the x pixel values
ypixel      - the y pixel values
RETURNS
astr        - an IDL astrometric structure containing the plate solution
OPTIONAL INPUT KEYWORDS
distort     - type of distortion to fit. Options: 'none': just
              fit the linear solution, 'tpv' fit the TPV
              convention, 'tnx': fit the iraf tnx
              convention. default: 'none'. See:
              http://iraf.noao.edu/projects/ccdmosaic/tnx.html
              for TNX
              http://iraf.noao.edu/projects/ccdmosaic/tpv.html
              for TPV
crval       - the ra/dec of the reference pixel in
              degrees. Default is mean of the input coordinates
nrej        - Number of rejection iterations
reject      - the sigma of the rejection (input to RESISTANT_MEAN)
etaorder    - The order of the TNX coefficients in eta
xiorder     - The order of the TNX coefficients in xi
xterms      - TNX cross-terms type (0: none, 1: full, 2: half)
n_tpvterms  - Number of TPV coefficients to include. Always
              includes rterms even if /NORTERMS is passed. Useful
              values include: 7 (quadratic), 12 (cubic), 17
              (quartic).
norterms    - Do not fit the "r" terms if using a TPV distortion
naxis1      - xpixel size of image being fit. If passed this is
              inserted into the final astrometry structure, but
              are not required.
naxis2      - ypixel size of image being fit. If passed this is
              inserted into the final astrometry structure, but
              are not required.
verbose     - Give verbose output
OPTIONAL OUTPUT KEYWORD
xirms       - the xi fit rms in arcseconds
etarms      - the eta fit rms in arcseconds
xiresid     - Residuals of each point in xi entering the final
              (fit indices of input points given by wfit).
etaresid    - Residuals of each point in eta entering the final
              (fit indices of input points given by wfit).
wfit        - index of input datapoints that were used in the
              final fit
success     - Did the code run successfully?
NOTES
The implmentation is slightly limited. It can only fit the
polynomial terms in TNX and not the legendre or chebyshev. The x/y
pixels must be previously matched with the ra/decs. The use of
MPFIT2DFUN is probably not needed and could be re-written to run
faster with LAPACK libraries. For tnx projections, orders in eta and xi cannot currently
be specified separately.
There is code duplication between tpv_eval, tnx_eval and this routine
Input/Output is always assumed to be FK5/equinox 2000. Could be changed!
PROCEDURES USED
STRN() - in astrolib
RESISTANT_MEAN - in astrolib
MPFIT2DFUN(), MPFIT - in MPFIT library, can be downloaded from either
        from   http://cow.physics.wisc.edu/~craigm/idl/fitting.html
        or     http://idlastro.gsfc.nasa.gov/ftp/pro/markwardt/
LA_LEAST_SQUARES() - IDL built-in
REVISION HISTORY
Written, M. Sullivan, March 2014
Modified to better handle fields that straddle RA=0
Modified to populate final astrometry structure with naxis1/2
  if these are passed