STScI Logo

ccmap images.imcoords


NAME · USAGE · PARAMETERS · DESCRIPTION · REFERENCES · EXAMPLES
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


Source Code · Search Form · STSDAS