.help ccmap Jan01 images.imcoords .ih NAME ccmap -- compute plate solutions using matched pixel and celestial coordinate lists .ih USAGE ccmap input database .ih PARAMETERS .ls 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 \fIxcolumn\fR, \fIycolumn\fR, \fIlngcolumn\fR, and \fIlatcolumn\fR parameters respectively. Whether all files are combined to produce one solution or each file produces a separate solution depends on whether there is a matching list of output \fIsolutions\fR names or \fIresults\fR files. .le .ls database The text database file where the computed plate solutions are stored. .le .ls solutions = "" An optional list of plate solution names. If there are multiple input coordinate files and no name or a single name is specified then the input coordinates are combined to produce a single solution. Otherwise the list must match the number of input coordinate files. If no names are supplied then the database records are assigned the names of the input images \fIimages\fR, or the names of the coordinate files \fIinput\fR. In the case of multiple coordinate files the first image or input is used. .le .ls 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 \fIupdate\fR parameter is enabled, the image wcs will be created from the linear component of the computed plate solution and written to the image header. .le .ls 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 zero, one or equal to the number of input files. If results is "STDOUT" the results summary is printed on the standard output. If there are multiple input coordinate files and zero or one output is specified then the input coordinates are combined to produce a single solution. .le .ls xcolumn = 1, ycolumn = 2, lngcolumn = 3, latcolumn = 4 The input coordinate file columns containing the x, y, ra / longitude and dec / latitude values. .le .ls 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 \fIinput\fR. .le .ls 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 \fIinsystem\fR, e.g. "hours" and "degrees" for equatorial systems, and "degrees" and "degrees" for ecliptic, galactic, and supergalactic systems. .le .ls insystem = "j2000" The input celestial coordinate system. The \fIinsystem\fR 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: .ls 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. .le .ls icrs [equinox] [epoch] The International Celestial Reference 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. .le .ls fk5 [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. .le .ls fk4 [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. .le .ls noefk4 [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. .le .ls 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. .le .ls 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. .le .ls 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. .le .ls 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. .le 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. .le .ls 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: .ls 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. .le .ls user The values of the keywords \fIlngref\fR, \fIlatref\fR, \fIrefsystem\fR, \fIlngrefunits\fR, and \fIlatrefunits\fR are used to determine the celestial coordinates of the reference point. .le .le .ls xref = "INDEF", yref = "INDEF" The reference pixel may be specified as a value or image header keyword. In the latter case a reference image must be specified. By specifying the reference pixel the solution will be constrained to putting the reference coordinate at that point. .le .ls lngref = "INDEF", latref = "INDEF" The ra / longitude and dec / latitude of the reference point(s). 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/DEC or CRVAL1/CRVAL2. Each parameter may be a list to apply different reference points to each input coordinate list. If lngref and latref are undefined then the position of the reference point defaults to the mean of the input coordinates. .le .ls refsystem = "INDEF" The celestial coordinate system of the reference point. Refsystem may be any one of the options listed under the \fIinsystem\fR 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 \fIinsystem\fR. .le .ls 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. .le .ls 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. .le .ls 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. .ls shift Xi and eta shifts only are fit. .le .ls xyscale Xi and eta shifts and x and y magnification factors in " / pixel are fit. Axis flips are allowed for. .le .ls rotate Xi and eta shifts and a rotation angle are fit. Axis flips are allowed for. .le .ls 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. .le .ls rxyscale Xi and eta shifts, x and y magnifications factors in " / pixel, and a rotation angle are fit. Axis flips are allowed for. .le .ls 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. .le 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 \fIxxorder\fR, \fIxyorder\fR, \fIxxterms\fR, \fIyxorder\fR, \fIyyorder\fR and \fIyxterms\fR parameters set by the user. .le .ls function = "polynomial" The type of analytic coordinate surface to be fit. The options are the following. .ls legendre Legendre polynomials in x and y. .le .ls chebyshev Chebyshev polynomials in x and y. .le .ls polynomial Power series polynomials in x and y. .le .le .ls 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 \fIfitgeometry\fR is "general", then a distortion surface is fit to the residuals from the linear portion of the fit. .le .ls xxterms = "half", yxterms = "half" The options are: .ls none The individual polynomial terms contain powers of x or powers of y but not powers of both. .le .ls 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. .le .ls 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. .le 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 \fIfitgeometry\fR is "general" then a distortion surface is fit to the residuals from the linear portion of the fit. .le .ls maxiter = 0 The maximum number of rejection iterations. The default is no rejection. .le .ls reject = INDEF The rejection limit in units of sigma. .le .ls 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 \fIprojection\fR and \fIinsystem\fR 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 compatible and can only be understood by IRAF. Any existing image wcs represented by the above keywords is overwritten during the update. .le .ls pixsystem = "logical" The input pixel coordinate system. The options are: .ls 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. .le .ls 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. .le The choice of pixsystem has no affect on the fitting process, but does determine how the image header wcs is updated. .le .ls verbose = yes Print detailed messages about the progress of the task on the standard output ? .le .ls 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. .le .ls graphics = "stdgraph" The graphics device. .le .ls cursor = "" The graphics cursor. .le .ih DESCRIPTION CCMAP computes the plate solution for an image or set of images using lists 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 \fIinput\fR 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 \fIxcolumn\fR, \fIycolumn\fR, \fIlngcolumn\fR, and \fIlatcolumn\fR respectively. The \fIxmin\fR, \fIxmax\fR, \fIymin\fR and \fIymax\fR 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 \fIimages\fR 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 \fIlngunits\fR and \fIlatunits\fR 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 \fIinsystem\fR 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. .nf xi = f (x, y) eta = g (x, y) .fi The standard coordinates xi and eta are computed from the input celestial coordinates using the sky projection geometry \fIprojection\fR 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 "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. There are two modes in which this task works with multiple input coordinate lists. In one case each input list and possible associated image is treated independently and produce separate solutions. To select this option requires specifying a matching list of solution names or output results files. Note that this can also be simply done by running the task multiple times with a single input list each time. In the second mode data from multiple input lists are combined to produce a single solution. This is useful when multiple exposures are taken to define a higher quality astrometric solution. This mode is selected when there are multiple input lists, and possibly associated images, and no solution name or a single solution name is specified. When combining input data each set of coordinates may have different reference points which can be specified either as a list or by reference to image header keywords. The different reference points are used to convert each set of coordinates to the same coordinate frame. Typically this occurs when a set of exposures, each with the same coordinate reference pixel, has slightly different pointing as defined by the coordinate reference value. These different points result from a dither and can be useful to more completely sample the image pixel space. In other words, astrometric reference stars can be moved around the images to produce many more fitting points than occur with a single exposure. The key point to this process is that the shifts are mapped by the reference points of the pointing and the standard coordinates are independent of the pointing. A particular feature primarily intending for combining multiple exposures, but applies to single exposures as well, is an adjustment to the specified tangent point value based on the image WCS. When images, reference pixels, and reference coordinates are all defined and the images contain a celestial WCS the following computation is performed. The reference information replaces the WCS tangent point values, though typically the initial reference information is specified as the tangent point, and the updated WCS is used to evaluate celestial coordinates from the input pixel coordinates. The average difference between the WCS evaluated coordinates and the input celestial coordinates is computed. This difference is applied to the reference point prior to the standard coordinate plate solution calculation. In other words, the reference point is tweaked in the initial image WCS to make it agree on average with the input reference coordinates. If one updates the WCS of the images by the plate solution and the repeats the plate solution, particularly when using multiple exposures, an iterative convergence to a self-consistent WCS of both the tangent point and plate solution can be obtained. Several polynomial cross terms options are available. Options "none", "half", and "full" are illustrated below for a quadratic polynomial in x and y. .nf 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 .fi If \fIrefpoint\fR 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 \fIrefpoint\fR is "user", the user may either set the celestial coordinates of the reference point explicitly, e.g. \fIlngref\fR = 13:41:02.3 and \fIlatref\fR = -33:42:20, or point these parameters to the appropriate keywords in the input image header, e.g. \fIlngref\fR = RA, \fIlatref\fR = DEC for NOAO image data. If undefined the celestial coordinate system of the reference point \fIrefsystem\fR 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 \fIrefsystem\fR 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 \fIlngrefunits\fR and \fIlatrefunits\fR parameters. Lngrefunits and latrefunits default to the values of the input coordinate units if undefined by either the user or the \fIrefsystem\fR parameter. ONCE DETERMINED THE REFERENCE POINT CANNOT BE RESET DURING THE FITTING PROCESS. The \fIxref\fR and \fIyref\fR parameters may be used to constrain the solution to putting the reference coordinate at the reference pixel. Effectively what this does is fix the zero-th order coefficient in the linear part of the solution. If a reference pixel is not specified the solution will produce a point determined from the zero-th order constant coefficient. This may not be what is expected based on the specified reference celestial coordinate. The fitting functions f and g are specified by the \fIfunction\fR parameter and may be power series polynomials, Legendre polynomials, or Chebyshev polynomials of order \fIxxorder\fR and \fIxyorder\fR in x and \fIyxorder\fR and \fIyyorder\fR in y. Cross-terms are optional and are turned on and off by setting the \fIxxterms\fR and \fIxyterms\fR parameters. If the \fBfitgeometry\fR 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 \fImaxiter\fR > 0 and \fIreject\fR to a positive value, usually something in the range 2.5-5.0. CCMAP may be run interactively by setting \fIinteractive\fR to "yes" and inputting 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. .nf ? 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 .fi The parameters listed below can be changed interactively with simple colon commands. Typing the parameter name along will list the current value. .nf :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 .fi The final fit is stored in the text database file \fIdatabase\fR 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 \fIimage\fR if one is supplied, or the name of the input coordinate file \fIinput\fR. If the \fIupdate\fR 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 \fIpixsystem\fR. The FITS keywords which define the image celestial coordinate system CTYPE, RADECSYS, EQUINOX, and MJD-WCS are set by the \fIinsystem\fR and \fIprojection\fR 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 \fIverbose\fR is "yes", various pieces of useful information are printed to the terminal as the task proceeds. If \fIresults\fR 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. .nf 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 .fi 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. .nf 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 .fi .ih 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 " 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. .ih 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. .nf 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 .fi 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. .nf 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 .fi 3. Repeat the previous example but in this case input the position of the tangent point in fk4 1950.0 coordinates. .nf 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 .fi 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. .nf 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 .fi 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. .nf 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 .fi 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. .ih BUGS .ih SEE ALSO cctran,ccsetwcs,skyctran,imctran,finder.tfinder,finder.tastrom .endhelp