REFERENCES · SEE_ALSO
treqxy -- Translate right ascension and declination to distorted 2-D image pixel coordinates.
treqxy input "ra dec" treqxy input coords.txt
This task converts one or more points on the celestial sphere (specified by right ascension and declination) into pixel locations in an image. The coords parameter value may be the right ascension and declination, or it may be the name of a text file containing ra and dec for one or more objects.
The equatorial coordinates will first be converted to pixel coordinates using the FITS keywords (e.g. CTYPEi, CRVALi, CRPIXi, CDi_j) in the image header. Then the geometric distortion will normally be applied to the pixel coordinates, as defined by an IDC table, so the resulting values will be the coordinates in the image (i.e. the flt or crj image) that has not been resampled to correct for the distortion. Applying the distortion can be disabled by the user by setting the idctab parameter to "none". It will be disabled by the task if the primary header of the image file contains a GEOCORR keyword and its value is "COMPLETE", or if there is no IDCTAB header keyword (and idctab is null). In these cases, the task will print "# Note: no geometric correction" (possibly followed by further explantion) before printing the results.
Four numbers will be printed to the standard output for each pixel location: the input equatorial coordinates (as specified by the user) and the geometrically distorted pixel coordinates.
- input [string]
- Input image name.
Wildcards are not supported;
the task reads just one image at a time.
For a FITS file, the extension must be specified explicitly, unless the image is in the primary header/data unit and there are no extensions.
- coords [string]
- This may be either a pair of numbers or the name of a text file.
If it is a pair of numbers (separated by one or more blanks),
they will be interpreted as the right ascension and declination.
If it is a text file,
it should contain two columns separated by whitespace;
the first column should be the right ascension,
and the second column should be the declination.
(Comma and semicolon are also allowed as separators.)
The right ascension may be given either in hours, minutes and seconds or in decimal degrees (not decimal hours). These two cases are distinguished by the presence or absence of a colon in the right ascension. For example, if the right ascension were given as 18:43:11.807 it would be interpreted to be hours, minutes, and seconds, while 280.79919583333 would be read as decimal degrees (and 18:43.1967833 would be hours and minutes). The declination may be given either in degrees, minutes and seconds or in decimal degrees.
- (idctab = "") [string]
- The name of a table of image distortion coefficients.
If idctab is null (the default), the task will read the IDCTAB keyword in the primary header and use that table for the distortion coefficients. If there is no IDCTAB keyword in the primary header, no correction for geometric distortion will be applied. idctab may be used to override the value in the header or to specify a table for an image that lacks this keyword. A pixel offset will be added so that when the idctab distortion correction is applied, the distortion will be zero at the reference pixel (CRPIX1,CRPIX2). See the description of select for the row selection criteria. See ISR ACS 2001-08 for a description of the format of this reference table.
If idctab = "none", no IDC table will be used, and no geometric distortion will be applied to the pixel coordinates.
- (select = "filter") [string]
- Row selection column.
The IDC table may contain more than one row. The row to use will be selected by the value in the DIRECTION column; DIRECTION must be "INVERSE". A second column, as given by the select parameter, can be used as an additional selection criterion. If select is not null, both an image header keyword and an IDC table column with that name must exist; the header and column values will be compared (case insensitive) and used in addition to DIRECTION to select the table row. The header and column values of select are expected to be strings.
- (decimals = 4) [int]
- This parameter gives the number of decimal places to be printed for the pixel coordinates, if verbose = yes.
- (verbose = yes) [boolean]
- Print output? If verbose = no, the task runs silently; this option may be useful in scripts when processing one point per call to treqxy. Note that the task parameters x and y will be updated with the X and Y pixel coordinates respectively, regardless of the value of verbose.
- (x) [string]
- The output X pixel coordinate. If coords is a file name and the file contains more than one pair of pixel coordinates, x and y will be assigned the pixel coordinates corresponding to the last location read from coords.
- (y) [string]
- The output Y pixel coordinate.
1. Calculate equatorial coordinates of a pixel in the first extension:
st> # hh:mm:ss.d dd:mm:ss.d format st> treqxy o5ja06010_crj.fits "18:43:11.42528 -32:17:40.5448" 18:43:11.42528 -32:17:40.5448 755.0012 863.9987 st> # decimal degrees st> treqxy o5ja06010_crj.fits "280.79760533333 -32.294595777778" 280.79760533333 -32.294595777778 755.0012 863.9987 xs> trxyeq o5ja06010_crj.fits "755 864" 755.000 864.000 754.7548 864.1740 18:43:11.42528 -32:17:40.5448
2. As in example 1, but omit the geometric correction:
xs> treqxy o5ja06010_crj.fits "18:43:11.42528 -32:17:40.5448" idctab=none # Note: no geometric correction 18:43:11.42528 -32:17:40.5448 754.7548 864.1729
3. Calculate equatorial coordinates at the corner pixels of the image, with equatorial coordinates specified in the file "coo.lis" (obtained by running trxyeq):
xs> treqxy o5ja06010_crj.fits coo.lis 18:43:14.45129 -32:16:56.8438 1.0002 1.0020 18:43:10.39901 -32:17:03.6795 1.0006 1023.9973 18:43:14.99293 -32:17:48.2482 1023.9981 1.0004 18:43:10.93125 -32:17:55.0981 1024.0001 1024.0015
ISR ACS 2001-08, W. Hack and C. Cox, "Revised IDCTAB Definition: Application to HST Data."
The treqxy task was written by Phil Hodge.