| imcctran | images.imcoords | imcctran |
imcctran -- convert between image celestial coordinate systems
imcctran image outsystem
In all the above cases fields in [] are optional with the defaults as described. The epoch field for the fk5, icrs, 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.
IMCCTRAN converts the celestial coordinate system stored in the headers of the input images image to the celestial coordinate system specified by outsystem , and updates the input image header appropriately. The input and output celestial coordinate systems 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), ICRS, the International Celestial Reference System, 5) GAPPT, the geocentric apparent place in the post-IAU 1976 system.
The input celestial coordinate system is read from the input image header. IMCCTRAN assumes that the celestial coordinate system is specified by the FITS keywords CTYPE, CRPIX, CRVAL, CD (or alternatively CDELT / CROTA), RADECSYS, EQUINOX (or EPOCH), MJD-WCS (or MJD-OBS, or DATE-OBS). USERS SHOULD TAKE NOTE THAT MJD-WCS IS CURRENTLY NEITHER A STANDARD OR A PROPOSED FITS STANDARD KEYWORD. HOWEVER IT OR SOMETHING SIMILAR, IS REQUIRED TO SPECIFY THE EPOCH OF THE COORDINATE SYSTEM WHICH MAY BE DIFFERENT FROM THE EPOCH OF THE OBSERVATION.
The first four characters of the values of the ra / longitude and dec / latitude axis CTYPE keywords specify the celestial coordinate system. The currently permitted values of CTYPE[1:4] are 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 AIT, ARC, CAR, CSC, GLS, MER, PAR, PCO, QSC, SIN, STG, TAN, TSC, and ZEA geometries as well as two internal projection geomemtries TNX, and ZPX. Consequently the currently permitted values of CTYPE[5:8] are -AIT, -ARC, -CAR, -CSC, -GLS, -MER, -PAR, -PCO, -QSC, -SIN, -STG, -TAN, -TSC, -ZEA as well as -ZPX and -TNX.
If the input image celestial coordinate system is equatorial, the value of the RADECSYS keyword specifies which fundamental equatorial system is to be considered. The permitted values of RADECSYS are FK4, FK4-NO-E, FK5, ICRS, and GAPPT. If the RADECSYS keyword is not present in the image header, the values of the EQUINOX / EPOCH keywords (in that order of precedence) are used to determine the fundamental equatorial coordinate system. EQUINOX or EPOCH contain the epoch of the mean place and equinox for the FK4, FK4-NO-E, FK5, and ICRS systems (e.g 1950.0 or 2000.0). The default equatorial system is FK4 if EQUINOX or EPOCH < 1984.0, FK5 if EQUINOX or EPOCH >= 1984.0, and FK5 if RADECSYS, EQUINOX, and EPOCH are undefined. If RADECSYS is defined but EQUINOX and EPOCH are not, the equinox defaults to 1950.0 for the FK4 and FK4-NO-E systems, and 2000.0 for the FK5 and ICRS systems. The equinox value is interpreted as a Besselian epoch for the FK4 and FK4-NO-E systems, and as a Julian epoch for the FK5 and ICRS systems. Users are strongly urged to use the EQUINOX keyword in preference to the EPOCH keyword, if they must enter their own equinox values into the image header. The FK4 and FK4-NO-E systems are not inertial and therefore also require the epoch of the observation (the time when the mean place was correct), in addition to the equinox. The epoch is specified, in order of precedence, by the values of the keywords MJD-WCS or MJD-OBS (which contain the modified Julian date, JD - 2400000.5, of the coordinate system), or the DATE-OBS keyword (which contains the date of the observation in the form DD/MM/YY, CCYY-MM-DD, or CCYY-MM-DDTHH:MM:SS.S). As the latter quantity may only be accurate to a day, the MJD-WCS or MJD-OBS specification is preferred. If all 3 keywords are absent the epoch defaults to the value of equinox. Equatorial coordinates in the GAPPT system require only the specification of the epoch of observation which is supplied via the MJD-WCS, MJD-OBS, or DATE-OBS keywords (in that order of precedence) as for the FK4 and FK4-NO-E system.
If the input image celestial coordinate system is ecliptic the mean ecliptic and equinox of date are required. These are supplied via the MJD-WCS, MJD-OBS, or DATE-OBS keywords (in that order or precedence) as for the equatorial FK4, FK4-NO-E, and GAPPT systems.
The output coordinate system is specified by the outsystem parameter as described in the PARAMETERS section.
If an error is encountered when decoding the input or output world coordinate systems, an error message is printed on the standard output (if verbose is "yes"), and the input image left unmodified.
If the input projection is one of the zenithal projections TAN, SIN, STG, ARC, or ZEA, then the header coordinate tranformation can be preformed by transforming the CRVAL parameters and rotating the CD matrix as described in detail below. Otherwise the CRVAL values are transformed, the CD matrix is left unmodified, and the LONGPOLE and LATPOLE parameters required to perform the rotation are computed. If longpole is yes then the zenithal coordinate systems will also be transformed using LONGPOLE and LATPOLE. At present IRAF looks for longpole and latpole parameters in the approriate WATN_* keywords. If these are undefined the appropriate default values for each projection are assumed and new values are written to the WATN_* keywords.
The new image celestial coordinate system is computed as follows. First a grid of nx by ny pixel and celestial coordinates, evenly spaced over the input image, is generated using the input image celestial coordinate system. Next these input celestial coordinates are transformed to coordinates in the output celestial coordinate system. Next the input celestial coordinates of the reference point (stored in degrees in the input image CRVAL keywords) are transformed to coordinates in the output celestial coordinate system, and new x and y pixel coordinates are computed using the transformed reference point coordinates but the original input CD matrix. The differences between the predicted and initial x and y pixel coordinates are used to compute the x and y axis rotation angles and the x and y magnification factors required to transform the original CD matrix to the correct new CD matrix. The process is shown schematically below.
1. x,y(input grid) -> ra,dec(input grid) 2. ra,dec(input grid) -> ra,dec(output grid) 3. ra_ref,dec_ref(input) -> ra_ref,dec_ref(output) 4. ra,dec(output grid) -> x,y(predicted grid) 5. x,y(input grid) -> F -> x,y(predicted grid) 6. cd matrix(input) -> F -> cd matrix(output)
F is the fitted function of the x and y axis rotation angles and the x and y scaling factors required to match the input x and y values to the predicted x and y values.
For most celestial coordinate transformations the fitted x and y scale factors will be very close to 1.0 and the x and y rotation angles will be almost identical. However small deviations from unity scale factors and identical x and y axis rotation angles do occur when transforming coordinates systems with the skewed axes.
The precision of the transformations is usually very high, on the order of 10E-10 to 10E-11 in most cases. However conversions to and from the FK4 equatorial system are less precise as these transformations involve the addition and subtraction of the elliptical aberration or E-terms. In this case the x and y scale factors correct for the first order E-terms and do significantly improve the precision of the coordinate transformation. The quadratic terms, i.e. terms in xy, x**2, and y**2 however are not corrected for, and their absence does diminish the precision of the transformation coordinate transformation. For most practical purposes this loss of precision is insignificant.
After the fit is completed, the celestial coordinates of the reference point in dd:mm:ss.s in the old and new systems, the rotation angle in degrees, the x and y scaling factors, and an estimate of the rms error of the x and y coordinate transformation are printed on the standard output.
If update is yes, then the image header parameters CRVAL, CD, CTYPE, RADECSYS, EQUINOX, EPOCH, and MJD-WCS are modified, deleted, or added as appropriate. The position of the reference pixel in the image (stored in the CRPIX keywords), and the sky projection geometry, e.g. TAN, SIN, ARC, ETC are unchanged.
USERS NEED TO BE AWARE THAT THE IRAF IMAGE WORLD COORDINATE SYSTEM CURRENTLY (IRAF VERSIONS 2.10.4 PATCH 2 AND EARLIER) SUPPORTS ONLY THE EQUATORIAL SYSTEM (CTYPE (ra axis) = "RA--XXXX" CTYPE (dec axis) = "DEC-XXXX") WHERE XXXX IS THE PROJECTION TYPE, EVEN THOUGH THE IMCCTRAN TASK SUPPORTS GALACTIC, ECLIPTIC, AND SUPERGALACTIC COORDINATES. IMCCTRAN will update the image correctly for non-equatorial systems, but IRAF will not be able to read these transformed image coordinate systems correctly.
USERS SHOULD ALSO REALIZE THAT IMAGE WORLD COORDINATE SYSTEM REPRESENTATION IN FITS IS STILL IN THE DRAFT STAGE. ALTHOUGH IMCCTRAN TRIES TO CONFORM TO THE CURRENT DRAFT PROPOSAL AS MUCH AS POSSIBLE, WHERE NO ADOPTED STANDARDS CURRENTLY EXIST, THE FINAL FITS STANDARD MAY DIFFER FROM THE ONE ADOPTED HERE.
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.
[1]. Precess the equatorial FK5 J2000 celestial coordinate system of the input 512 by 512 pixel square input image to J1975.0.
cl> imcctran image j1975.0
INPUT IMAGE: image
Insystem: image logical Projection: TAN Ra/Dec axes: 1/2
Coordinates: equatorial FK5 Equinox: J2000.000
Epoch: J1987.25667351 MJD: 46890.00000
Outsystem: j1975 Coordinates: equatorial FK5
Equinox: J1975.000 Epoch: J1975.00000000 MJD: 42413.25000
Crval1,2: 201:56:43.5, 47:27:16.0 -> 201:40:53.8, 47:35:01.2 dd:mm:ss.s
Scaling: Xmag: 1.000000 Ymag: 1.000000 Xrot: 359.923 Yrot: 359.923 degrees
Rms: X fit: 8.465123E-11 pixels Y fit: 5.204446E-11 pixels
Before the transformation the image coordinate system looked like the following.
...
EPOCH = 2000
DATE-OBS= '05/04/87'
CRPIX1 = 257.75
CRPIX2 = 258.93
CRVAL1 = 201.94541667302
CRVAL2 = 47.45444
CDELT1 = -2.1277777E-4
CDELT2 = 2.1277777E-4
CTYPE1 = 'RA---TAN'
CTYPE2 = 'DEC--TAN'
...
After the transformation the header looks like the following.
...
DATE-OBS= '05/04/87'
CRPIX1 = 257.75
CRPIX2 = 258.93
CRVAL1 = 201.681616387759
CRVAL2 = 47.583668865029
CTYPE1 = 'RA---TAN'
CTYPE2 = 'DEC--TAN'
RADECSYS= 'FK5 '
EQUINOX = 1975.
MJD-WCS = 42413.25
WCSDIM = 2
CD1_1 = -2.1277757990523E-4
CD1_2 = 2.84421945372844E-7
CD2_1 = 2.84421945363011E-7
CD2_2 = 2.12777579905235E-4
LTM1_1 = 1.
LTM2_2 = 1.
WAT0_001= 'system=image'
WAT1_001= 'wtype=tan axtype=ra'
WAT2_001= 'wtype=tan axtype=dec'
...
Note the the rms of the x and y fits is on the order 10.0e-10 to 10.0e-11 which is the expected numerical precision of the transformation.
[2]. Convert the input image used in example 1 to the BFK4 1950.0 system.
cl> imcctran image B1950.0
INPUT IMAGE: image
Insystem: image logical Projection: TAN Ra/Dec axes: 1/2
Coordinates: equatorial FK5 Equinox: J2000.000
Epoch: J1987.25667351 MJD: 46890.00000
Outsystem: B1950 Coordinates: equatorial FK4
Equinox: B1950.000 Epoch: B1950.00000000 MJD: 33281.92346
Crval1,2: 201:56:43.5, 47:27:16.0 -> 201:25:02.3, 47:42:47.1 dd:mm:ss.s
Scaling: Xmag: 0.999999 Ymag: 0.999999 Xrot: 359.848 Yrot: 359.848 degrees
Rms: X fit: 1.302837E-7 pixels Y fit: 8.545616E-8 pixels
Note that precision of the transformation is still good but is significantly less that the precision of the previous example. This is due to the fact that the quadratic terms in the E-term computation are not included in the transformation.
The transformed image header in this case looks like the following.
...
DATE-OBS= '05/04/87'
CRPIX1 = 257.75
CRPIX2 = 258.93
CRVAL1 = 201.417300629944
CRVAL2 = 47.7130749603847
CTYPE1 = 'RA---TAN'
CTYPE2 = 'DEC--TAN'
RADECSYS= 'FK4 '
EQUINOX = 1950.
MJD-WCS = 33281.92345905
WCSDIM = 2
CD1_1 = -2.1277680505752E-4
CD1_2 = 5.66226465943254E-7
CD2_1 = 5.66226470798410E-7
CD2_2 = 2.12776805056766E-4
LTM1_1 = 1.
LTM2_2 = 1.
WAT0_001= 'system=image'
WAT1_001= 'wtype=tan axtype=ra'
WAT2_001= 'wtype=tan axtype=dec'
...
[3]. Transform the celestial coordinate system of the input image used in examples 1 and 2 to the galactic coordinate system.
cl> imcctran image galactic
INPUT IMAGE: image
Insystem: image logical Projection: TAN Ra/Dec axes: 1/2
Coordinates: equatorial FK5 Equinox: J2000.000
Epoch: J1987.25667351 MJD: 46890.00000
Outsystem: galactic Coordinates: galactic
MJD: 33281.92346 Epoch: J1949.99979044 B1950.00000000
rval1,2: 201:56:43.5, 47:27:16.0 -> 106:01:19.4, 68:27:46.1 dd:mm:ss.s
Scaling: Xmag: 1.000000 Ymag: 1.000000 Xrot: 202.510 Yrot: 202.510 degrees
Rms: X fit: 9.087450E-11 pixels Y fit: 3.815443E-11 pixels
The transformed header looks like the following.
...
DATE-OBS= '05/04/87'
CRPIX1 = 257.75
CRPIX2 = 258.93
CRVAL1 = 106.022047915293
CRVAL2 = 68.4627934475432
CTYPE1 = 'GLON-TAN'
CTYPE2 = 'GLAT-TAN'
MJD-WCS = 33281.92345905
WCSDIM = 2
CD1_1 = 1.96567112095654E-4
CD1_2 = 8.14601120181094E-5
CD2_1 = 8.14601120174619E-5
CD2_2 = -1.9656711209802E-4
LTM1_1 = 1.
LTM2_2 = 1.
WAT0_001= 'system=image'
WAT1_001= 'wtype=tan axtype=glon'
WAT2_001= 'wtype=tan axtype=glat'
...
Users should not that although imcctran can write a legal galactic coordinate system to the image header, it and other iraf tasks cannot currently read this coordinate system.
[4]. Repeat the previous example but don't update the image header.
cl> imcctran image galactic update-
INPUT IMAGE: image
Insystem: image logical Projection: TAN Ra/Dec axes: 1/2
Coordinates: equatorial FK5 Equinox: J2000.000
Epoch: J1987.25667351 MJD: 46890.00000
Outsystem: galactic Coordinates: galactic
MJD: 33281.92346 Epoch: J1949.99979044 B1950.00000000
Current wcs
Axis 1 2
Crval 201.9454 47.4544
Crpix 257.75 258.93
Cd 1 -2.128E-4 0.
Cd 2 0. 2.128E-4
New wcs
Axis 1 2
Crval 106.0220 68.4628
Crpix 257.75 258.93
Cd 1 1.966E-4 8.146E-5
Cd 2 8.146E-5 -1.966E-4
Crval1,2: 201:56:43.5, 47:27:16.0 -> 106:01:19.4, 68:27:46.1 dd:mm:ss.s
Scaling: Xmag: 1.000000 Ymag: 1.000000 Xrot: 202.510 Yrot: 202.510 degrees
Rms: X fit: 9.087450E-11 pixels Y fit: 3.815443E-11 pixels
[5]. Repeat example 1 and check the accuracy of the results by using the skyctran task on the original image and on the transformed image.
cl> type coords
1.0 1.0
512.0 1.0
512.0 512.0
1.0 512.0
cl> skyctran coords STDOUT "image logical" J1975.0
Insystem: image logical Projection: TAN Ra/Dec axes: 1/2
Coordinates: equatorial FK5 Equinox: J2000.000
Epoch: J1987.25667351 MJD: 46890.00000
Outsystem: j1975 Coordinates: equatorial FK5
Equinox: J1975.000 Epoch: J1975.00000000 MJD: 42413.25000
Input file: coords Output file: STDOUT
1.0 1.0 13:27:02.9797 47:31:43.269
512.0 1.0 13:26:24.3330 47:31:43.793
512.0 512.0 13:26:24.3448 47:38:15.219
1.0 512.0 13:27:03.0718 47:38:14.693
cl> imcctran image j1975.0
cl> skyctran coords STDOUT "image logical" "image world"
Insystem: image logical Projection: TAN Ra/Dec axes: 1/2
Coordinates: equatorial FK5 Equinox: J1975.000
Epoch: J1975.00000000 MJD: 42413.25000
Outsystem: image world Projection: TAN Ra/Dec axes: 1/2
Coordinates: equatorial FK5 Equinox: J1975.000
Epoch: J1975.00000000 MJD: 42413.25000
Input file: coords Output file: STDOUT
1.0 1.0 13:27:02.9797 47:31:43.269
512.0 1.0 13:26:24.3330 47:31:43.793
512.0 512.0 13:26:24.3448 47:38:15.219
1.0 512.0 13:27:03.0718 47:38:14.693
At present IRAF requires that the LONGPOLE and or LATPOLE keywords be defined in the appropriate WAT_* keywords, e.g. WAT1_* and WAT2_* for a 2D image. If these are not present then default values are assumed. The new values are computed and added to the WAT1_* and WAT2_* keywords.
At present the experimental TNX and ZPX projections cannot be transformed with precision. Users should use the SKYCTRAN task to transfrom individual coordinate pairs.
setjd,precess,galactic,xray.xspatial.skypix,stsdas.toolbox.tools.tprecess