BUGS · SEE_ALSO

## NAME

ccmap -- compute plate solutions using matched pixel and celestial coordinate lists

## USAGE

`ccmap input database`

## PARAMETERS

- input
- The input text files containing the pixel and celestial coordinates of
points in the input images. The coordinates are listed one per line with x, y,
ra / longitude, and dec / latitude in the columns specified by the
*xcolumn*,*ycolumn*,*lngcolumn*, and*latcolumn*parameters respectively.

- database
- The text database file where the computed plate solutions are stored.

- solutions = ""
- An optional list of plate solution names. If no names are supplied then
the database records are assigned the names of the input
images
*images*, or the names of the coordinate files*input*.

- images = ""
- The images associated with the input coordinate files. The number of images
must be zero or equal to the number of input coordinate files. If an input
image exists and the
*update*parameter is enabled, the image wcs will be created from the linear component of the computed plate solution and written to the image header.

- results = ""
- Optional output files containing a summary of the results including a description of the plate geometry and a listing of the input coordinates, the fitted coordinates, and the fit residuals. The number of results files must be one or equal to the number of input files. If results is "STDOUT" the results summary is printed on the standard output.

- xcolumn = 1, ycolumn = 2, lngcolumn = 3, latcolumn = 4
- The input coordinate file columns containing the x, y, ra / longitude and dec / latitude values.

- xmin = INDEF, xmax = INDEF, ymin = INDEF, ymax = INDEF
- The range of x and y pixel coordinates over which the computed coordinate
transformation is valid. These limits should be left at INDEF or set to
the values of the column and row limits of the input images, e.g xmin = 1.0,
xmax = 512, ymin= 1.0, ymax = 512 for a 512 x 512 image. If xmin, xmax, ymin,
or ymax are undefined, they are set to the minimum and maximum x and y
pixels values in
*input*.

- lngunits = "", latunits = ""
- The units of the input ra / longitude and dec / latitude coordinates. The
options are "hours", "degrees", and "radians" for ra / longitude, and
"degrees" and "radians" for dec / latitude. If the lngunits and latunits
are undefined they default to the preferred units for the coordinate system
specified by
*insystem*, e.g. "hours" and "degrees" for equatorial systems, and "degrees" and "degrees" for ecliptic, galactic, and supergalactic systems.

- insystem = "j2000"
- The input celestial coordinate system. The
*insystem*parameter sets the preferred units for the input celestial coordinates, tells CCMAP how to transform the celestial coordinates of the reference point from the reference point coordinate system to the input coordinate system, and sets the correct values of the image header keywords CTYPE, RADECSYS, EQUINOX, and MJD-WCS if the image header wcs is updated. The systems of most interest to users are "icrs", "j2000", and "b1950" which stand for the ICRS J2000.0, FK5 J2000.0 and FK4 B1950.0 celestial coordinate systems respectively. The full set of options are the following:- equinox [epoch]
- The equatorial mean place post-IAU 1976 (FK5) system if equinox is a Julian epoch, e.g. J2000.0 or 2000.0, or the equatorial mean place pre-IAU 1976 system (FK4) if equinox is a Besselian epoch, e.g. B1950.0 or 1950.0. Julian equinoxes are prefixed by a J or j, Besselian equinoxes by a B or b. Equinoxes without the J / j or B / b prefix are treated as Besselian epochs if they are < 1984.0, Julian epochs if they are >= 1984.0. Epoch is the epoch of the observation and may be a Julian epoch, a Besselian epoch, or a Julian date. Julian epochs are prefixed by a J or j, Besselian epochs by a B or b. Epochs without the J / j or B / b prefix default to the epoch type of equinox if the epoch value <= 3000.0, otherwise epoch is interpreted as a Julian date. If undefined epoch defaults to equinox.

- icrs [equinox] [epoch]
- The Internaltion Celestial Refernce System where equinox is a Julian or Besselian epoch e.g. J2000.0 or B1980.0. Equinoxes without the J / j or B / b prefix are treated as Julian epochs. The default value of equinox is J2000.0. Epoch is a Besselian epoch, a Julian epoch, or a Julian date. Julian epochs are prefixed by a J or j, Besselian epochs by a B or b. Epochs without the J / j or B / b prefix default to Julian epochs if the epoch value <= 3000.0, otherwise epoch is interpreted as a Julian date. If undefined epoch defaults to equinox.

- fk[equinox] [epoch]
- The equatorial mean place post-IAU 1976 (FK5) system where equinox is a Julian or Besselian epoch e.g. J2000.0 or B1980.0. Equinoxes without the J / j or B / b prefix are treated as Julian epochs. The default value of equinox is J2000.0. Epoch is a Besselian epoch, a Julian epoch, or a Julian date. Julian epochs are prefixed by a J or j, Besselian epochs by a B or b. Epochs without the J / j or B / b prefix default to Julian epochs if the epoch value <= 3000.0, otherwise epoch is interpreted as a Julian date. If undefined epoch defaults to equinox.

- fk[equinox] [epoch]
- The equatorial mean place pre-IAU 1976 (FK4) system where equinox is a Besselian or Julian epoch e.g. B1950.0 or J2000.0, and epoch is the Besselian epoch, the Julian epoch, or the Julian date of the observation. Equinoxes without the J / j or B / b prefix are treated as Besselian epochs. The default value of equinox is B1950.0. Epoch is a Besselian epoch, a Julian epoch, or a Julian date. Julian epochs are prefixed by a J or j, Besselian epochs by a B or b. Epochs without the J / j or B / b prefix default to Besselian epochs if the epoch value <= 3000.0, otherwise epoch is interpreted as a Julian date. If undefined epoch defaults to equinox.

- noefk[equinox] [epoch]
- The equatorial mean place pre-IAU 1976 (FK4) system but without the E-terms where equinox is a Besselian or Julian epoch e.g. B1950.0 or J2000.0, and epoch is the Besselian epoch, the Julian epoch, or the Julian date of the observation. Equinoxes without the J / j or B / b prefix are treated as Besselian epochs. The default value of equinox is B1950.0. Epoch is a Besselian epoch, a Julian epoch, or a Julian date. Julian epochs are prefixed by a J or j, Besselian epochs by a B or b. Epochs without the J / j or B / b prefix default to Besselian epochs if the epoch value <= 3000.0, otherwise epoch is interpreted as a Julian day. If undefined epoch defaults to equinox.

- apparent epoch
- The equatorial geocentric apparent place post-IAU 1976 system where epoch is the epoch of observation. Epoch is a Besselian epoch, a Julian epoch or a Julian date. Julian epochs are prefixed by a J or j, Besselian epochs by a B or b. Epochs without the J / j or B / b prefix default to Besselian epochs if the epoch value < 1984.0, Julian epochs if the epoch value <= 3000.0, otherwise epoch is interpreted as a Julian date.

- ecliptic epoch
- The ecliptic coordinate system where epoch is the epoch of observation. Epoch is a Besselian epoch, a Julian epoch, or a Julian date. Julian epochs are prefixed by a J or j, Besselian epochs by a B or b. Epochs without the J / j or B / b prefix default to Besselian epochs if the epoch values < 1984.0, Julian epochs if the epoch value <= 3000.0, otherwise epoch is interpreted as a Julian day.

- galactic [epoch]
- The IAU 1958 galactic coordinate system. Epoch is a Besselian epoch, a Julian epoch or a Julian date. Julian epochs are prefixed by a J or j, Besselian epochs by a B or b. Epochs without the J / j or B / b prefix default to Besselian epochs if the epoch value < 1984.0, Julian epochs if the epoch value <= 3000.0, otherwise epoch is interpreted as a Julian date. The default value of epoch is B1950.0.

- supergalactic [epoch]
- The deVaucouleurs supergalactic coordinate system. Epoch is a Besselian epoch, a Julian epoch or a Julian date. Julian epochs are prefixed by a J or j, Besselian epochs by a B or b. Epochs without the J / j or B / b prefix default to Besselian epochs if the epoch value < 1984.0, Julian epochs if the epoch value <= 3000.0, otherwise epoch is interpreted as a Julian date. The default value of epoch is B1950.0.

In all the above cases fields in [] are optional with the defaults as described. The epoch field for the icrs, fk5, galactic, and supergalactic coordinate systems is only used if the input coordinates are in the equatorial fk4, noefk4, fk5, or icrs systems and proper motions are supplied. Since CCMAP does not currently support proper motions these fields are not required.

- refpoint = "coords"
- The definition of the sky projection reference point in celestial coordinates,
e.g. the tangent point in the case of the usual tangent plane projection.
The options are:
- coords
- The celestial coordinates of the reference point are set to the mean of the input celestial coordinates, e.g. the mean of ra / longitude and dec / latitude coordinates. If the true tangent point is reasonably close to the center of the input coordinate distribution and the input is not too large, this approximation is reasonably accurate.

- user
- The values of the keywords
*lngref*,*latref*,*refsystem*,*lngrefunits*, and*latrefunits*are used to determine the celestial coordinates of the reference point.

- lngref = "INDEF", latref = "INDEF"
- The ra / longitude and dec / latitude of the reference point. Lngref and latref may be numbers, e.g 13:20:42.3 and -33:41:26 or keywords for the appropriate parameters in the image header, e.g. RA and DEC for NOAO image data. If lngref and latref are undefined then the position of the reference point defaults to the mean of the input coordinates.

- refsystem = "INDEF"
- The celestial coordinate system of the reference point. Refsystem may
be any one of the options listed under the
*insystem*parameter, e.g. "b1950", or an image header keyword containing the epoch of the observation in years, e.g. EPOCH for NOAO data. In the latter case the coordinate system is assumed to be equatorial FK4 at equinox EPOCH. If refsystem is undefined the celestial coordinate system of the reference point defaults to the celestial coordinate system of the input coordinates*insystem*.

- lngrefunits = "", latrefunits = ""
- The units of the reference point celestial coordinates. The options are "hours", "degrees", and "radians" for the ra / longitude coordinates, and "degrees" and "radians" for the dec /latitude coordinates. If lngunits and latunits are undefined they default to the units of the input coordinate system.

- projection = "tan"
- The sky projection geometry. The most commonly used projections in astronomy are "tan", "arc", "sin", and "lin". Other supported standard projections are "ait", "car","csc", "gls", "mer", "mol", "par", "pco", "qsc", "stg", "tsc", and "zea". A new experimental function "tnx", a combination of the tangent plate projection and polynomials, is also available.

- fitgeometry = "general"
- The plate solution geometry to be used. The options are the following, where
xi and eta refer to the usual standard coordinates used in astrometry.
- shift
- Xi and eta shifts only are fit.

- xyscale
- Xi and eta shifts and x and y magnification factors in " / pixel are fit. Axis flips are allowed for.

- rotate
- Xi and eta shifts and a rotation angle are fit. Axis flips are allowed for.

- rscale
- Xi and eta shifts, a magnification factor in " / pixel assumed to be the same in x and y, and a rotation angle are fit. Axis flips are allowed for.

- rxyscale
- Xi and eta shifts, x and y magnifications factors in " / pixel, and a rotation angle are fit. Axis flips are allowed for.

- general
- A polynomial of arbitrary order in x and y is fit. A linear term and a distortion term are computed separately. The linear term includes a xi and eta shift, an x and y scale factor in " / pixel, a rotation and a skew. Axis flips are also allowed for in the linear portion of the fit. The distortion term consists of a polynomial fit to the residuals of the linear term. By default the distortion term is set to zero.

For all the fitting geometries except "general" no distortion term is fit, i.e. the x and y polynomial orders are assumed to be 2 and the cross term switches are assumed to be set to "none", regardless of the values of the

*xxorder*,*xyorder*,*xxterms*,*yxorder*,*yyorder*and*yxterms*parameters set by the user.

- function = "polynomial"
- The type of analytic coordinate surface to be fit. The options are the
following.
- legendre
- Legendre polynomials in x and y.

- chebyshev
- Chebyshev polynomials in x and y.

- polynomial
- Power series polynomials in x and y.

- xxorder = 2, xyorder = 2, yxorder = 2, yyorder = 2
- The order of the polynomials in x and y for the xi and eta fits respectively.
The default order and cross term settings define the linear term in x
and y, where the 6 coefficients can be interpreted in terms of an xi and eta
shift, an x and y scaling in " / pixel, and rotations of the x and y axes.
The "shift", "xyscale", "rotation", "rscale", and "rxyscale", fitting geometries
assume that the polynomial order parameters are 2 regardless of the values
set by the user. If any of the order parameters are higher than 2 and
*fitgeometry*is "general", then a distortion surface is fit to the residuals from the linear portion of the fit.

- xxterms = "half", yxterms = "half"
- The options are:
- none
- The individual polynomial terms contain powers of x or powers of y but not powers of both.

- half
- The individual polynomial terms contain powers of x and powers of y, whose maximum combined power is MAX (xxorder - 1, xyorder - 1) for the xi fit and MAX (yxorder - 1, yyorder - 1) for the eta fit. This is the recommended option for higher order plate solutions.

- full
- The individual polynomial terms contain powers of x and powers of y, whose maximum combined power is MAX (xxorder - 1 + xyorder - 1) for the xi fit and MAX (yxorder - 1 + yyorder - 1) for the eta fit.

The "shift", "xyscale", "rotation", "rscale", and "rxyscale" fitting geometries, assume that the cross term switches are set to "none" regardless of the values set by the user. If either of the cross-terms parameters is set to "half" or "full" and

*fitgeometry*is "general" then a distortion surface is fit to the residuals from the linear portion of the fit.

- maxiter = 0
- The maximum number of rejection iterations. The default is no rejection.

- reject = INDEF
- The rejection limit in units of sigma.

- update = no
- Update the world coordinate system in the input image headers ?
The required numerical quantities represented by the keywords CRPIX,
CRVAL, and CD are computed from the linear portion of the plate solution,
The values of the keywords CTYPE, RADECSYS, EQUINOX, and MJD-WCS
are set by the
*projection*and*insystem*parameters. As there is currently no standard mechanism for storing the higher order plate solution terms if any in the image header wcs, these terms are currently ignored unless the projection function is the experimental function "tnx". The "tnx" function is not FITS compatable and can only be understood by IRAF. Any existing image wcs represented by the above keywords is overwritten during the update.

- pixsystem = "logical"
- The input pixel coordinate system. The options are:
- logical
- The logical pixel coordinate system is the coordinate system of the image pixels on disk. Since most users measure the pixel coordinates of objects in this system, "logical" is the system of choice for most applications.

- physical
- The physical coordinate system is the pixel coordinate system of the parent image if any. This option may be useful for users working on images that are pieces of a larger mosaic.

The choice of pixsystem has no affect on the fitting process, but does determine how the image header wcs is updated.

- verbose = yes
- Print detailed messages about the progress of the task on the standard output ?

- interactive = yes
- Compute the plate solution interactively ? In interactive mode the user may interact with the fitting process, e.g. change the order of the fit, reject points, display the data and refit, etc.

- graphics = "stdgraph"
- The graphics device.

- cursor = ""
- The graphics cursor.

## DESCRIPTION

CCMAP computes the plate solution for an image using a list of matched pixel
and celestial coordinates. The celestial coordinates are usually equatorial
coordinates, but may also be ecliptic, galactic, or supergalactic coordinates.
The input coordinate files *input*
must be text file tables whose columns
are delimited by whitespace. The pixel and celestial coordinates are listed
in input, one per line with x, y, ra / longitude, and dec / latitude in
columns *xcolumn*
, *ycolumn*
, *lngcolumn*
, and *latcolumn*
respectively.

The *xmin*
, *xmax*
, *ymin*
and *ymax*
parameters define
the region of validity of the fit in the pixel coordinate system. They should
normally either be left set to INDEF, or set to the size of input images
*images*
if any, e.g. xmin= 1.0, xmax= 512.0, ymin = 1.0, ymax = 512.0
for a 512 square image. If set these parameters are also used to reject out
of range pixel data before the actual fitting is done.

The *lngunits*
and *latunits*
parameters set the units of the input
celestial coordinates. If undefined lngunits and latunits assume sensible
defaults for the input celestial coordinate system set by the *insystem*
parameter, e.g. "hours" and "degrees" for equatorial coordinates and "degrees"
and "degrees" for galactic coordinates. The input celestial coordinate system
must be one of the following: equatorial, ecliptic, galactic, or supergalactic.
The equatorial coordinate systems must be one of: 1) FK4, the mean place
pre-IAU 1976 system, 2) FK4-NO-E, the same as FK4 but without the E-terms,
3) FK5, the mean place post-IAU 1976 system, 4) GAPPT, the geocentric apparent
place in the post-IAU 1976 system.

The plate solution computed by CCMAP has the following form, where x and y are the pixel coordinates of points in the input image and xi and eta are the corresponding standard coordinates in units of " / pixel.

xi = f (x, y) eta = g (x, y)

The standard coordinates xi and eta are computed from the input celestial
coordinates using the sky projection geometry *projection*
and
the celestial coordinates of the projection reference point set by
the user. The default projection is the tangent plane or gnomonic
projection commonly used in optical astronomy. The projections most commonly
used in astronomy are are "sin" (the orthographic projection, used in radio
aperture synthesis), "arc" (the zenithal equidistant projection, widely
used as an approximation for Schmidt telescopes), and "lin" (linear).
Other supported projections are "ait", "car", "csc", "gls", "mer", "mol",
"par", "pco", "qsc", "stg", "tsc", and "zea". The experimental projection
function "tnx" combines the "tan" projection with a polynomial fit
to the residuals can be used to represent more complicated distortion
functions.

Several polynomial cross terms options are avaible. Options "none", "half", and "full" are illustrated below for a quadratic polynomial in x and y.

xxterms = "none", xyterms = "none" xxorder = 3, xyorder = 3, yxorder = 3, yyorder = 3 xi = a11 + a21 * x + a12 * y + a31 * x ** 2 + a13 * y ** 2 eta = a11' + a21' * x + a12' * y + a31' * x ** 2 + a13' * y ** 2 xxterms = "half", xyterms = "half" xxorder = 3, xyorder = 3, yxorder = 3, yyorder = 3 xi = a11 + a21 * x + a12 * y + a31 * x ** 2 + a22 * x * y + a13 * y ** 2 eta = a11' + a21' * x + a12' * y + a31' * x ** 2 + a22' * x * y + a13' * y ** 2 xxterms = "full", xyterms = "full" xxorder = 3, xyorder = 3, yxorder = 3, yyorder = 3 xi = a11 + a21 * x + a31 * x ** 2 + a12 * y + a22 * x * y + a32 * x ** 2 * y + a13 * y ** 2 + a23 * x * y ** 2 + a33 * x ** 2 * y ** 2 eta = a11' + a21' * x + a31' * x ** 2 + a12' * y + a22' * x * y + a32' * x ** 2 * y + a13' * y ** 2 + a23' * x * y ** 2 + a33' * x ** 2 * y ** 2

If *refpoint*
is "coords", then the sky projection reference point is set
to the mean of the input celestial coordinates. For images where the true
reference point is close to the center of the input coordinate distribution,
this definition is adequate for many purposes. If *refpoint*
is "user",
the user may either set the celestial coordinates of the reference
point explicitly, e.g. *lngref*
= 13:41:02.3 and *latref*
= -33:42:20,
or point these parameters to the appropriate keywords in the input image
header, e.g. *lngref*
= RA, *latref*
= DEC for NOAO image data.
If undefined the celestial coordinate system of the reference point
*refsystem*
defaults to the celestial coordinate system of the input
coordinates, otherwise it be any of the supported celestial coordinate
systems described above. The user may also set *refsystem*
to the
image header keyword containing the epoch of the celestial reference point
coordinates in years, e.g. EPOCH for NOAO data. In this case the
reference point coordinates are assumed to be equatorial FK4 coordinates at the
epoch specified by EPOCH. The units of the reference point celestial
coordinates are specified by the *lngrefunits*
and *latrefunits*
parameters. Lngrefunits and latrefunits default to the values of the input
coordinate units if undefined by either the user or the *refsystem*
parameter. ONCE DETERMINED THE REFERENCE POINT CANNOT BE RESET DURING
THE FITTING PROCESS.

The fitting functions f and g are specified by the *function*
parameter
and may be power series polynomials, Legendre polynomials, or Chebyshev
polynomials of order *xxorder*
and *xyorder*
in x and *yxorder*
and *yyorder*
in y. Cross-terms are optional and are turned on and
off by setting the *xxterms*
and *xyterms*
parameters. If the
**fitgeometry**
parameter is anything other than "general", the order
parameters assume the value 2 and the cross-terms switches assume the value
"none", regardless of the values set by the user. All computation are done in
double precision. Automatic pixel rejection may be enabled by setting
*maxiter*
> 0 and *reject*
to a positive value, usually something
in the range 2.5-5.0.

CCMAP may be run interactively by setting *interactive*
to "yes" and
inputing commands by the use of simple keystrokes. In interactive mode the
user has the option of changing the fitting parameters and displaying the
data and fit graphically until a satisfactory fit has been achieved. The
keystroke commands are listed below.

? Print options f Fit data and graph fit with the current graph type (g,x,r,y,s) g Graph the data and the current fit x,r Graph the xi residuals versus x and y respectively y,s Graph the eta residuals versus x and y respectively d,u Delete or undelete the data point nearest the cursor o Overplot the next graph c Toggle the line of constant x and y plotting option t Plot a line of constant x and y through nearest data point l Print xishift, etashift, xscale, yscale, xrotate, yrotate q Exit the interactive fitting code

The parameters listed below can be changed interactively with simple colon commands. Typing the parameter name along will list the current value.

:show List parameters :projection Sky projection :refpoint Sky projection reference point :fit [value] Fit type (shift,xyscale,rotate,rscale,rxyscale,general) :function [value] Fitting function (chebyshev,legendre,polynomial) :xxorder [value] Xi fitting function order in x :xyorder [value] Xi fitting function order in y :yxorder [value] Eta fitting function order in x :yyorder [value] Eta fitting function order in y :xxterms [n/h/f] The xi fit cross terms type :yxterms [n/h/f] The eta fit cross terms type :maxiter [value] Maximum number of rejection iterations :reject [value] K-sigma rejection threshold

The final fit is stored in the text database file *database*
file in a
format suitable for use by the CCSETWCS and CCTRAN tasks. Each fit is
stored in a record whose name is the name of the input image *image*
if one is supplied, or the name of the input coordinate file *input*
.

If the *update*
switch is "yes" and an input image is specified,
a new image wcs is derived from the linear component of the computed plate
solution and written to the image header. The numerical components of
the new image wcs are written to the standards FITS keywords, CRPIX, CRVAL,
and CD, with the actual values depending on the input pixel coordinate
system *pixsystem*
.
The FITS keywords which define the image celestial coordinate
system CTYPE, RADECSYS, EQUINOX, and MJD-WCS are set by the *insystem*
and
*projection*
parameters.

The first four characters of the values of the ra / longitude and dec / latitude axis CTYPE keywords specify the celestial coordinate system. They are set to RA-- / DEC- for equatorial coordinate systems, ELON / ELAT for the ecliptic coordinate system, GLON / GLAT for the galactic coordinate system, and SLON / SLAT for the supergalactic coordinate system.

The second four characters of the values of the ra / longitude and dec / latitude axis CTYPE keywords specify the sky projection geometry. IRAF currently supports the TAN, SIN, ARC, AIT, CAR, CSC, GLS, MER, MOL, PAR, PCO, QSC, STG, TSC, and ZEA standard projections, in which case the second 4 characters of CTYPE are set to -TAN, -ARC, -SIN, etc. IRAF and CCMAP also support the experiment TAN plus polynomials function driver.

If the input celestial coordinate system is equatorial, the value of the RADECSYS keyword specifies the fundamental equatorial system, EQUINOX specifies the epoch of the mean place, and MJD-WCS specifies the epoch for which the mean place is correct. The permitted values of RADECSYS are FK4, FK4-NO-E, FK5, ICRS, and GAPPT. EQUINOX is entered in years and interpreted as a Besselian epoch for the FK4 system, a Julian epoch for the FK5 system. The epoch of the wcs MJD-WCS is entered as a modified Julian date. Only those keywords necessary to defined the new wcs are written. Any existing keywords which are not required to define the wcs or are redundant are removed, with the exception of DATE-OBS and EPOCH, which are left unchanged for obvious (DATE_OBS) and historical (use of EPOCH keyword at NOAO) reasons.

If *verbose*
is "yes", various pieces of useful information are
printed to the terminal as the task proceeds. If *results*
is set to a
file name then the original pixel and celestial coordinates, the fitted
celestial coordinates, and the residuals of the fit in arcseconds are written
to that file.

The transformation computed by the "general" fitting geometry is arbitrary and does not correspond to a physically meaningful model. However the computed coefficients for the linear term can be given a simple geometrical interpretation for all the fitting geometries as shown below.

fitting geometry = general (linear term) xi = a + b * x + c * y eta = d + e * x + f * y fitting geometry = shift xi = a + x eta = d + y fitting geometry = xyscale xi = a + b * x eta = d + f * y fitting geometry = rotate xi = a + b * x + c * y eta = d + e * x + f * y b * f - c * e = +/-1 b = f, c = -e or b = -f, c = e fitting geometry = rscale xi = a + b * x + c * y eta = d + e * x + f * y b * f - c * e = +/- const b = f, c = -e or b = -f, c = e fitting geometry = rxyscale xi = a + b * x + c * y eta = d + e * x + f * y b * f - c * e = +/- const

The coefficients can be interpreted as follows. X0, y0, xi0, eta0 are the origins in the reference and input frames respectively. By definition xi0 and eta0 are 0.0 and 0.0 respectively. Rotation and skew are the rotation of the x and y axes and their deviation from perpendicularity respectively. Xmag and ymag are the scaling factors in x and y in " / pixel and are assumed to be positive by definition.

general (linear term) xrotation = rotation - skew / 2 yrotation = rotation + skew / 2 b = xmag * cos (xrotation) c = ymag * sin (yrotation) e = -xmag * sin (xrotation) f = ymag * cos (yrotation) a = xi0 - b * x0 - c * y0 = xshift d = eta0 - e * x0 - f * y0 = yshift shift xrotation = 0.0, yrotation = 0.0 xmag = ymag = 1.0 b = 1.0 c = 0.0 e = 0.0 f = 1.0 a = xi0 - x0 = xshift d = eta0 - y0 = yshift xyscale xrotation 0.0 / 180.0 yrotation = 0.0 b = + /- xmag c = 0.0 e = 0.0 f = ymag a = xi0 - b * x0 = xshift d = eta0 - f * y0 = yshift rscale xrotation = rotation + 0 / 180, yrotation = rotation mag = xmag = ymag const = mag * mag b = mag * cos (xrotation) c = mag * sin (yrotation) e = -mag * sin (xrotation) f = mag * cos (yrotation) a = xi0 - b * x0 - c * y0 = xshift d = eta0 - e * x0 - f * y0 = yshift rxyscale xrotation = rotation + 0 / 180, yrotation = rotation const = xmag * ymag b = xmag * cos (xrotation) c = ymag * sin (yrotation) e = -xmag * sin (xrotation) f = ymag * cos (yrotation) a = xi0 - b * x0 - c * y0 = xshift d = eta0 - e * x0 - f * y0 = yshift

## REFERENCES

Additional information on the IRAF world coordinate systems can be found in the help pages for the WCSEDIT and WCRESET tasks. Detailed documentation for the IRAF world coordinate system interface MWCS can be found in the file "iraf$sys/mwcs/MWCS.hlp". This file can be formatted and printed with the command "help iraf$sys/mwcs/MWCS.hlp fi+ | lprint".

Details of the FITS header world coordinate system interface can be found in the draft paper "World Coordinate Systems Representations Within the FITS Format" by Hanisch and Wells, available from the iraf anonymous ftp archive and the draft paper which supersedes it "Representations of Celestial Coordinates in FITS" by Greisen and Calabretta available from the nrao anonymous ftp archives.

The spherical astronomy routines employed here are derived from the Starlink SLALIB library provided courtesy of Patrick Wallace. These routines are very well documented internally with extensive references provided where appropriate. Interested users are encouraged to examine the routines for this information. Type "help slalib" to get a listing of the SLALIB routines, "help slalib opt=sys" to get a concise summary of the library, and "help <routine>" to get a description of each routine's calling sequence, required input and output, etc. An overview of the library can be found in the paper "SLALIB - A Library of Subprograms", Starlink User Note 67.7 by P.T. Wallace, available from the Starlink archives.

## EXAMPLES

1. Compute the plate scale for the test image dev$pix given the following coordinate list. Set the tangent point to the mean of the input celestial coordinates. Compute the plate scale interactively.

cl> type coords 13:29:47.297 47:13:37.52 327.50 410.38 13:29:37.406 47:09:09.18 465.50 62.10 13:29:38.700 47:13:36.23 442.01 409.65 13:29:55.424 47:10:05.15 224.35 131.20 13:30:01.816 47:12:58.79 134.37 356.33 cl> imcopy dev$pix pix cl> hedit pix epoch 1987.26 cl> ccmap coords coords.db image=pix xcol=3 ycol=4 lngcol=1 latcol=2 ... a plot of the mapping function appears ... type ? to see the list of commands ... type x to see the xi fit residuals versus x ... type r to see the xi fit residuals versus y ... type y to see the eta fit residuals versus x ... type s to see the eta fit residuals versus y ... type g to return to the default plot ... type l to see the computed x and y scales in " / pixel ... type q to quit and save fit

2. Repeat example 2 but compute the fit non-interactively and list the fitted values of the ra and dec and their residuals on the standard output.

cl> ccmap coords coords.db image=pix results=STDOUT xcol=3 ycol=4 \ lngcol=1 latcol=2 inter- # Coords File: coords Image: pix # Database: coords.db Record: pix # Refsystem: j2000 Coordinates: equatorial FK5 # Equinox: J2000.000 Epoch: J2000.00000000 MJD: 51544.50000 # Insystem: j2000 Coordinates: equatorial FK5 # Equinox: J2000.000 Epoch: J2000.00000000 MJD: 51544.50000 # Coordinate mapping status # XI fit ok. ETA fit ok. # Ra/Dec or Long/Lat fit rms: 0.229 0.241 (arcsec arcsec) # Coordinate mapping parameters # Sky projection geometry: tan # Reference point: 13:29:48.129 47:11:53.37 (hours degrees) # Reference point: 318.735 273.900 (pixels pixels) # X and Y scale: 0.764 0.767 (arcsec/pixel arcsec/pixel) # X and Y axis rotation: 179.110 358.958 (degrees degrees) # Wcs mapping status # Ra/Dec or Long/Lat wcs rms: 0.229 0.241 (arcsec arcsec) # # Input Coordinate Listing # X Y Ra Dec Ra(fit) Dec(fit) Dra Ddec # 327.5 410.4 13:29:47.30 47:13:37.5 13:29:47.28 47:13:37.9 0.128 -0.370 465.5 62.1 13:29:37.41 47:09:09.2 13:29:37.42 47:09:09.2 -0.191 -0.062 442.0 409.6 13:29:38.70 47:13:36.2 13:29:38.70 47:13:35.9 0.040 0.282 224.3 131.2 13:29:55.42 47:10:05.2 13:29:55.40 47:10:05.1 0.289 0.059 134.4 356.3 13:30:01.82 47:12:58.8 13:30:01.84 47:12:58.7 -0.267 0.091

3. Repeat the previous example but in this case input the position of the tangent point in fk4 1950.0 coordinates.

cl> ccmap coords coords.db image=pix results=STDOUT xcol=3 ycol=4 lngcol=1 \ latcol=2 refpoint=user lngref=13:27:46.9 latref=47:27:16 refsystem=b1950.0 \ inter- # Coords File: coords Image: pix # Database: coords.db Record: pix # Refsystem: b1950.0 Coordinates: equatorial FK4 # Equinox: B1950.000 Epoch: B1950.00000000 MJD: 33281.92346 # Insystem: j2000 Coordinates: equatorial FK5 # Equinox: J2000.000 Epoch: J2000.00000000 MJD: 51544.50000 # Coordinate mapping status # XI fit ok. ETA fit ok. # Ra/Dec or Long/Lat fit rms: 0.229 0.241 (arcsec arcsec) # Coordinate mapping parameters # Sky projection geometry: tan # Reference point: 13:29:53.273 47:11:48.36 (hours degrees) # Reference point: 250.256 266.309 (pixels pixels) # X and Y scale: 0.764 0.767 (arcsec/pixel arcsec/pixel) # X and Y axis rotation: 179.126 358.974 (degrees degrees) # Wcs mapping status # Ra/Dec or Long/Lat wcs rms: 0.229 0.241 (arcsec arcsec) # # Input Coordinate Listing # X Y Ra Dec Ra(fit) Dec(fit) Dra Ddec 327.5 410.4 13:29:47.30 47:13:37.5 13:29:47.28 47:13:37.9 0.128 -0.370 465.5 62.1 13:29:37.41 47:09:09.2 13:29:37.42 47:09:09.2 -0.191 -0.062 442.0 409.6 13:29:38.70 47:13:36.2 13:29:38.70 47:13:35.9 0.040 0.282 224.3 131.2 13:29:55.42 47:10:05.2 13:29:55.40 47:10:05.1 0.289 0.059 134.4 356.3 13:30:01.82 47:12:58.8 13:30:01.84 47:12:58.7 -0.267 0.091

Note the computed image scales are identical in examples 2 and 3 but that the assumed position of the tangent point is different (the second estimate is more accurate) producing different values for the pixel and celestial coordinates of the reference point and small differences in the computed rotation angles.

4. Repeat the previous example but in this case extract the position of the tangent point in from the image header keywords RA, DEC, and EPOCH.

cl> imheader pix l+ ... DATE-OBS= '05/04/87' / DATE DD/MM/YY RA = '13:29:24.00' / RIGHT ASCENSION DEC = '47:15:34.00' / DECLINATION EPOCH = 1987.26 / EPOCH OF RA AND DEC ... cl> ccmap coords coords.db image=pix results=STDOUT xcol=3 ycol=4 \ lngcol=1 latcol=2 refpoint=user lngref=RA latref=DEC refsystem=EPOCH \ inter- # Coords File: coords Image: pix # Database: coords.db Record: pix # Refsystem: fk4 b1987.26 Coordinates: equatorial FK4 # Equinox: B1987.260 Epoch: B1987.26000000 MJD: 46890.84779 # Insystem: j2000 Coordinates: equatorial FK5 # Equinox: J2000.000 Epoch: J2000.00000000 MJD: 51544.50000 # Coordinate mapping status # XI fit ok. ETA fit ok. # Ra/Dec or Long/Lat fit rms: 0.229 0.241 (arcsec arcsec) # Coordinate mapping parameters # Sky projection geometry: tan # Reference point: 13:29:56.232 47:11:38.19 (hours degrees) # Reference point: 211.035 252.447 (pixels pixels) # X and Y scale: 0.764 0.767 (arcsec/pixel arcsec/pixel) # X and Y axis rotation: 179.135 358.983 (degrees degrees) # Wcs mapping status # Ra/Dec or Long/Lat wcs rms: 0.229 0.241 (arcsec arcsec) # # Input Coordinate Listing # X Y Ra Dec Ra(fit) Dec(fit) Dra Ddec 327.5 410.4 13:29:47.30 47:13:37.5 13:29:47.28 47:13:37.9 0.128 -0.370 465.5 62.1 13:29:37.41 47:09:09.2 13:29:37.42 47:09:09.2 -0.191 -0.062 442.0 409.6 13:29:38.70 47:13:36.2 13:29:38.70 47:13:35.9 0.040 0.282 224.3 131.2 13:29:55.42 47:10:05.2 13:29:55.40 47:10:05.1 0.289 0.059 134.4 356.3 13:30:01.82 47:12:58.8 13:30:01.84 47:12:58.7 -0.267 0.091

Note that the position of the tangent point is slightly different again but that this does not have much affect on the fitted coordinates for this image.

5. Repeat the third example but this time store the computed world coordinate system in the image header and check the header update with the imheader and skyctran tasks.

cl> imheader pix l+ ... DATE-OBS= '05/04/87' / DATE DD/MM/YY RA = '13:29:24.00' / RIGHT ASCENSION DEC = '47:15:34.00' / DECLINATION EPOCH = 1987.26 / EPOCH OF RA AND DEC ... cl> ccmap coords coords.db image=pix results=STDOUT xcol=3 ycol=4 \ lngcol=1 latcol=2 refpoint=user lngref=13:27:46.9 latref=47:27:16 \ refsystem=b1950.0 inter- update+ # Coords File: coords Image: pix # Database: coords.db Record: pix # Refsystem: b1950.0 Coordinates: equatorial FK4 # Equinox: B1950.000 Epoch: B1950.00000000 MJD: 33281.92346 # Insystem: j2000 Coordinates: equatorial FK5 # Equinox: J2000.000 Epoch: J2000.00000000 MJD: 51544.50000 # Coordinate mapping status # Coordinate mapping status # XI fit ok. ETA fit ok. # Ra/Dec or Long/Lat fit rms: 0.229 0.241 (arcsec arcsec) # Coordinate mapping parameters # Sky projection geometry: tan # Reference point: 13:29:53.273 47:11:48.36 (hours degrees) # Reference point: 250.256 266.309 (pixels pixels) # X and Y scale: 0.764 0.767 (arcsec/pixel arcsec/pixel) # X and Y axis rotation: 179.126 358.974 (degrees degrees) # Wcs mapping status # Ra/Dec or Long/Lat wcs rms: 0.229 0.241 (arcsec arcsec) # Updating image header wcs # # # Input Coordinate Listing # X Y Ra Dec Ra(fit) Dec(fit) Dra Ddec 327.5 410.4 13:29:47.30 47:13:37.5 13:29:47.28 47:13:37.9 0.128 -0.370 465.5 62.1 13:29:37.41 47:09:09.2 13:29:37.42 47:09:09.2 -0.191 -0.062 442.0 409.6 13:29:38.70 47:13:36.2 13:29:38.70 47:13:35.9 0.040 0.282 224.3 131.2 13:29:55.42 47:10:05.2 13:29:55.40 47:10:05.1 0.289 0.059 134.4 356.3 13:30:01.82 47:12:58.8 13:30:01.84 47:12:58.7 -0.267 0.091 cl> imheader pix l+ ... DATE-OBS= '05/04/87' / DATE DD/MM/YY RA = '13:29:24.00' / RIGHT ASCENSION DEC = '47:15:34.00' / DECLINATION EPOCH = 1987.26 / EPOCH OF RA AND DEC ... RADECSYS= 'FK5 ' EQUINOX = 2000. MJD-WCS = 51544.5 WCSDIM = 2 CTYPE1 = 'RA---TAN' CTYPE2 = 'DEC--TAN' CRVAL1 = 202.471969550729 CRVAL2 = 47.1967667056819 CRPIX1 = 250.255619786203 CRPIX2 = 266.308757328719 CD1_1 = -2.1224568721716E-4 CD1_2 = -3.8136850875221E-6 CD2_1 = -3.2384199624421E-6 CD2_2 = 2.12935798198448E-4 LTM1_1 = 1. LTM2_2 = 1. WAT0_001= 'system=image' WAT1_001= 'wtype=tan axtype=ra' WAT2_001= 'wtype=tan axtype=dec' ... cl> skyctran coords STDOUT "pix log" "pix world" lngcol=3 latcol=4 trans+ # Insystem: pix logical Projection: TAN Ra/Dec axes: 1/2 # Coordinates: equatorial FK5 Equinox: J2000.000 # Epoch: J2000.00000000 MJD: 51544.50000 # Outsystem: pix world Projection: TAN Ra/Dec axes: 1/2 # Coordinates: equatorial FK5 Equinox: J2000.000 # Epoch: J2000.00000000 MJD: 51544.50000 # Input file: incoords Output file: STDOUT 13:29:47.297 47:13:37.52 13:29:47.284 47:13:37.89 13:29:37.406 47:09:09.18 13:29:37.425 47:09:09.24 13:29:38.700 47:13:36.23 13:29:38.696 47:13:35.95 13:29:55.424 47:10:05.15 13:29:55.396 47:10:05.09 13:30:01.816 47:12:58.79 13:30:01.842 47:12:58.70

Note that two versions of the rms values are printed, one for the fit and one for the wcs fit. For the default fitting parameters these two estimates should be identical. If a non-linear high order plate solution is requested however, the image wcs will have lower precision than the than the full plate solution, because only the linear component of the plate solution is preserved in the wcs.

## BUGS

## SEE ALSO

cctran,ccsetwcs,skyctran,imctran,finder.tfinder,finder.tastrom