ccsetwcs: Create an image celestial wcs from the ccmap plate solution
Package: imcoords
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 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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 arcsec / 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 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