ccsetwcs

ccsetwcs

images.imcoords

ccsetwcs

NAME · USAGE · PARAMETERS · DESCRIPTION · REFERENCES · EXAMPLES
BUGS · SEE_ALSO

NAME

ccsetwcs -- create an image wcs from a plate solution

PARAMETERS

images: The input images for which the wcs is to be created.

database: The text database file written by the ccmap task containing the plate solutions. If database is undefined ccsetwcs computes the image wcs using the xref, yref, xmag, ymag, xrotation, yrotation, lngref, latref, lngrefunits, latrefunits, and projection parameters.

solutions: The list of plate solutions. The number of plate solutions must be one or equal to the number of input images. Solutions is either a user name supplied to the ccmap task, or the name of the ccmap task input image for which the plate solution is valid, or the name of the coordinate file that the ccmap task used to compute the plate solution. The quantities stored in transform always supersede the values of the xref, yref, xmag, ymag, xrotation, yrotation, lngref, latref, lnrefunits, latrefunits, and projection parameters.

xref = INDEF, yref = INDEF: The x and y pixel coordinates of the sky projection reference point. If database is undefined then xref and yref default to the center of the image in pixel coordinates, otherwise these parameters are ignored.

xmag = INDEF, ymag = INDEF: The x and y scale factors in arcseconds per pixel. If database is undefined xmag and ymag default to 1.0 and 1.0 " / pixel, otherwise these parameters are ignored.

xrotation = INDEF, yrotation = INDEF: The x and y rotation angles in degrees measured counter-clockwise with respect to the x and y axes. Xrotation and yrotation are interpreted as the rotation of the coordinates with respect to the x and y axes and default 0.0 and 0.0 degrees. For example xrotation and yrotation values of 30.0 and 30.0 will rotate a point 30 degrees counter-clockwise with respect to the x and y axes. To flip the x axis coordinates in this case either set the angles to 210.0 and 30.0 degrees or leave the angles set to 30.0 and 30.0 and set the xmag parameter to a negative value. To set east to the up, down, left, and right directions, set xrotation to 90, 270, 180, and 0 respectively. To set north to the up, down, left, and right directions, set yrotation to 0, 180, 90, and 270 degrees respectively. Any global rotation must be added to both the xrotation and yrotation values.

lngref = INDEF, latref = INDEF: The celestial coordinates of the sky projection reference point, e.g. the ra and dec of the reference point for equatorial systems. If database is undefined lngref and latref default to 0.0 and 0.0, otherwise these parameters are ignored.

lngunits = "", latunits = "": The units of the lngref and latref parameters. The options are "hours", "degrees", "radians" for the ra / longitude coordinates, and "degrees" and "radians" for the dec / latitude coordinates. If database is undefined then lngunits and latunits default to the preferred units for the celestial coordinate system defined by the coosystem parameter, otherwise these parameters are ignored.

transpose = no: Transpose the newly created image wcs ?

projection = "tan": The sky projection geometry. The most commonly used projections in astronomy are "tan", "arc", "sin", and "lin". Other supported projections are "ait", "car", "csc", "gls", "mer", "mol", "par", "pco", "qsc", "stg", "tsc", and "zea".

coosystem = "j2000"

The celestial coordinate system. 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 listed below. The celestial coordinate system sets the preferred units for the lngref and latref parameters and the correct values of the image wcs header keywords CTYPE, RADECSYS, EQUINOX, and MJD-WCS if the image header wcs is updated. If database is undefined the coosystem parameter is used, otherwise this parameter is ignored.

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 icrs, fk5, galactic, and supergalactic coordinate systems is required only if the input coordinates are in the equatorial fk4, noefk4, fk5, or icrs systems and proper motions are defined.

update = yes: Update the world coordinate system in the input image headers ? The 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 coosystem parameters if database is undefined, otherwise projection and coosystem are read from the plate solution. 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 ignored. Any existing image wcs represented by the above keywords is overwritten during the update.

pixsystem = "logical"

The 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. This option is useful for users working on images that are pieces of a larger mosaic.

The pixsystem parameter is only used if no database solution is specified. Otherwise pixsystem is read from the database file.

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

DESCRIPTION

CCSETWCS creates an image world coordinate system from the plate solution computed by the CCMAP task or supplied by the user, and writes it to the headers of the input images images if the update parameter is yes.

The plate solution can either be read from record solutions in the database file database written by CCMAP, or specified by the user via the xref , yref , xmag , ymag , xrotation , yrotation , lngref , latref , lngunits , latunits , transpose , projection , coosystem and pixsystem parameters.

The plate solution computed by CCMAP has the following form where x and y are the image pixel coordinates and xi and eta are the corresponding standard coordinates in arcseconds per pixel. The standard coordinates are computed by applying the appropriate sky projection to the celestial coordinates.

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

The functions f and g are either power series, Legendre, or Chebyshev polynomials whose order and region of validity were set by the user when CCMAP was run. The computed plate solution is somewhat arbitrary and does not correspond to any physically meaningful model. However the linear component of the plate solution can be given the simple geometrical interpretation shown below.

	  xi = a + b * x + c * y
	 eta = d + e * x + f * y
	   b = xmag * cos (xrotation)
	   c = ymag * sin (yrotation)
	   e = -xmag * sin (xrotation)
	   f = ymag * cos (yrotation)
	   a = xi0 - b * xref - c * yref = xshift
	   d = eta0 - e * xref - f * yref = yshift
	   xi0 = 0.0
	   eta0 = 0.0

xref, yref, xi0, and eta0 are the origins of the pixel and standard coordinate systems respectively. xmag and ymag are the x and y scale factors in " / pixel and xrotation and yrotation are the rotation angles measured counter-clockwise of the x and y axes.

If the CCMAP database is undefined then CCSETWCS computes a linear plate solution using the the parameters xref , yref , xmag , ymag , xrotation , yrotation , lngref , latref , lngunits , latunits , transpose , and projection as shown below. Note that in this case xrotation and yrotation are interpreted as the rotation of the coordinates themselves not the coordinate axes.

	  xi = a + b * x + c * y
	 eta = d + e * x + f * y
	   b = xmag * cos (xrotation)
	   c = -ymag * sin (yrotation)
	   e = xmag * sin (xrotation)
	   f = ymag * cos (yrotation)
	   a = xi0 - b * xref - c * yref = xshift
	   d = eta0 - e * xref - f * yref = yshift
	   xi0 = 0.0
	   eta0 = 0.0

The transpose parameter can be used to transpose the newly created image wcs.

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 pixel coordinate system pixsystem read from the database or set by the user. The FITS keywords which define the image celestial coordinate system CTYPE, RADECSYS, EQUINOX, and MJD-WCS are set by the coosystem 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. 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.

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 and ICRS 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.

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 solution for an image with the ccmap task and then use the ccsetwcs task to create the image wcs. Check the results with the imheader and skyctran tasks.

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> ccmap coords coords.db image=pix 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
    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)

cl> type coords.db
# Mon 15:10:37 13-May-96
begin   coords
        xrefmean        318.7460000000001
        yrefmean        273.9320000000001
        lngmean         13.49670238888889
        latmean         47.19815944444444
        coosystem       j2000
        projection      tan
        lngref          13.49670238888889
        latref          47.19815944444444
        lngunits        hours
        latunits        degrees
        xpixref         318.7352667484295
        ypixref         273.9002619912411
        geometry        general
        function        polynomial
        xishift         247.3577084680361
        etashift        -206.1795977453246
        xmag            0.7641733802338992
        ymag            0.7666917500560622
        xrotation       179.1101291109185
        yrotation       358.9582148846163
        wcsxirms        0.2288984454992771
        wcsetarms       0.2411034140453112
        xirms           0.2288984454992771
        etarms          0.2411034140453112
        surface1        11
                        3.      3.
                        2.      2.
                        2.      2.
                        0.      0.
                        134.3700000000001       134.3700000000001
                        465.5000000000002       465.5000000000002
                        62.1    62.1
                        410.3800000000001       410.3800000000001
                        247.3577084680361       -206.1795977453246
                        -0.7640812161068504     -0.011868034832272
                        -0.01393966623835092    0.7665650170136847
        surface2        0



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> ccsetwcs pix coords.db pix 
Image: pix  Database: coords.db  Record: pix
Coordinate mapping parameters
    Sky projection geometry: tan
    Reference point: 13:29:48.129  47:11:53.37  (hours   degrees)
    Ra/Dec logical image axes: 1  2
    Reference point: 318.735  273.900  (pixels  pixels)
    X and Y scale: 0.764  0.767  (arcsec/pixel  arcsec/pixel)
    X and Y coordinate rotation: 179.110  358.958  (degrees  degrees)
Updating image header wcs

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.450535833334
CRVAL2  =     47.1981594444445
CRPIX1  =     318.735266748429
CRPIX2  =     273.900261991241
CD1_1   =  -2.1224478225190E-4
CD1_2   =  -3.8721295106530E-6
CD2_1   =  -3.2966763422978E-6
CD2_2   =  2.12934726948246E-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

The skyctran task is used to test that the input image wcs is indeed correct. Columns 1 and 2 contain the original ra and dec values and columns 3 and 4 contain the transformed values. The second imheader listing shows what the image wcs looks like.

2. Repeat the previous example but enter the plate solution parameters by hand.

cl> ccsetwcs pix "" xref=318.735 yref=273.900 lngref=13:29:48.129 \
latref=47:11:53.37 xmag=.764 ymag=.767 xrot=180.890 yrot=1.042
Image: pix
Coordinate mapping parameters
    Sky projection geometry: tan
    Reference point: 13:29:48.129  47:11:53.37  (hours   degrees)
    Ra/Dec logical image axes: 1  2
    Reference point: 318.735  273.900  (pixels  pixels)
    X and Y scale: 0.764  0.767  (arcsec/pixel  arcsec/pixel)
    X and Y coordinate rotation: 180.890  1.042  (degrees  degrees)
Updating image header wcs


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.285 47:13:37.93
13:29:37.406  47:09:09.18 13:29:37.428 47:09:09.17
13:29:38.700  47:13:36.23 13:29:38.698 47:13:35.99
13:29:55.424  47:10:05.15 13:29:55.395 47:10:05.04
13:30:01.816  47:12:58.79 13:30:01.839 47:12:58.72

Note that there are minor differences between the results of examples 1 and 2 due to precision differences in the input. Note also the difference in the way the xrotation and yrotation angles are defined between examples 1 and 2. In example 2 the rotations are defined as coordinate rotations, whereas in example one they are described as axis rotations.