BUGS · SEE_ALSO

## NAME

ccsetwcs -- create an image wcs from a plate solution

## USAGE

`ccsetwcs image database solutions`

## 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 arcsec / 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.

## BUGS

## SEE ALSO

ccmap, cctran, skyctran, imctran