.help cctran Dec96 images.imcoords .ih NAME cctran -- transform from pixel to celestial coordinates and vice versa using the computed plate solution .ih USAGE cctran input output database solutions .ih PARAMETERS .ls input The coordinate files to be transformed. .le .ls output The output coordinate files. The number of output files must be one or equal to the number of input files. .le .ls database The text database file written by the ccmap task containing the desired plate solution. If database is undefined cctran computes a linear plate solution using the current values of the xref, yref, xmag ymag, xrotation, yrotation, lngref, latref, and projection parameters. .le .ls solutions The database record containing the desired plate solution. The number of records must be one or equal to the number of input coordinate files. Solutions is either a user name supplied to ccmap, 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 solutions always supersede the values of xref, yref, xmag, ymag, xrotation, yrotation, lngref, latref, and projection. .le .ls geometry = "geometric" The type of geometric transformation. The geometry parameter is only requested if database is defined. The options are: .ls linear Transform the coordinates using only the linear part of the plate solution. .le .ls geometric Transform the coordinates using the full plate solution. .le .le .ls forward = yes Transform from pixel to celestial coordinates ? If forward is "no" then the plate solution is inverted and celestial coordinates are transformed to pixel coordinates. .le .ls xref = INDEF, yref = INDEF The x and y pixel coordinates of the reference point. If database is undefined then xref and yref default to 0.0 and 0.0, otherwise these parameters are ignored. .le .ls 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 arcseconds per pixel, otherwise these parameters are ignored. .le .ls 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 to 0.0 and 0.0 degrees. For example xrotation and yrotation values of 30.0 and 30.0 degrees 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 at 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. .le .ls lngref = INDEF, latref = INDEF The celestial coordinates of the reference point, e.g. the ra and dec of the reference point for equatorial systems, galactic longitude and latitude for galactic systems. If database is undefined lngref and latred default to 0.0 and 0.0, otherwise these parameters are ignored. .le .ls lngunits = "", latunits = "" The units of the input or output ra / longitude and dec / latitude coordinates. The options are "hours", "degrees", "radians" for ra / longitude coordinates, and "degrees" and "radians" for dec / latitude systems. If lngunits and latunits are undefined they default to the values in the database records. If database is undefined then lngunits and latunits default to "hours" and "degrees" respectively. .le .ls 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". .le .ls xcolumn = 1, ycolumn = 2 The columns in the input coordinate file containing the x and y coordinates if the \fIforward\fR parameter is "yes", the celestial ra / longitude and dec / latitude if the forward parameter is "no". .le .ls lngformat = "", latformat = "" The format of the output coordinates. The defaults are "%10.3f" for output coordinates in pixels, "%12.2h" for coordinates in hours, "%11.1h" for coordinates in degrees, and "%13.7g" for coordinates in radians. .le .ls min_sigdigits = 7 The minimum precision of the output coordinates. .le .ih DESCRIPTION CCTRAN applies the plate solution to a list of pixel or celestial coordinates in the text file \fIinput\fR and writes the transformed coordinates to the text file \fIoutput\fR. The input coordinates are read from and the output coordinates written to, the columns \fIxcolumn\fR and \fIycolumn\fR in the input and output files. The format of the output coordinates can be specified using the \fIlngformat\fR and \fIlatformat\fR parameters. If the output formats are unspecified the coordinates are written out with reasonable default precisions, e.g. "%10.3f" for pixel coordinates, "%12.2h" and "11.1h" for coordinates in hours or degrees, and "%13.7g" for coordinates in radians. All the remaining fields in the input file are copied to the output file without modification. Blank lines and comment lines are also passed to the output file unaltered. The plate solution is either read from record \fIsolutions\fR in the database file \fIdatabase\fR written by CCMAP, or specified by the user via the \fIxref\fR, \fIyref\fR, \fIxmag\fR, \fIymag\fR, \fIxrotation\fR, \fIyrotation\fR, \fIlngref\fR, \fIlatref\fR, and \fIprojection\fR parameters. If \fILngunits\fR and \fIlatunits\fR are undefined they default to the values in the database or to the quantities "hours" and "degrees" respectively. If the \fIforward\fR parameter is "yes", the input coordinates are assumed to be pixel coordinates and are transformed to celestial coordinates. If \fIforward\fR is "no", then the input coordinates are assumed to be celestial coordinates and are transformed to pixel coordinates. The transformation computed by CCMAP has the following form where x and y are the 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. .nf xi = f (x, y) eta = g (x, y) .fi 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 plate solution is arbitrary and does not correspond to any physically meaningful model. However the first order terms can be given the simple geometrical interpretation shown below. .nf 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 .fi xref, yref, xi0, and eta0 are the origins of the reference and output coordinate systems respectively. xi0 and eta0 are both 0.0 by default. xmag and ymag are the x and y scales in " / pixel, and xrotation and yrotation are the x and y axes rotation angles measured counter-clockwise from original x and y axes. If the CCMAP database is undefined then CCTRAN computes a linear plate solution using the parameters \fIxref\fR, \fIyref\fR, \fIxmag\fR, \fIymag\fR, \fIxrotation\fR, \fIyrotation\fR, \fIlngref\fR, \fIlatref\fR, \fIlngunits\fR, \fIlatunits\fR and \fIprojection\fR as shown below. Note that in this case xrotation and yrotation are interpreted as the rotation of the coordinates not the rotation of the coordinate axes. .nf 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 .fi Linear plate solutions are evaluated in the forward and reverse sense using the appropriate IRAF mwcs system routines. Higher order plate solutions are evaluated in the forward sense using straight-forward evaluation of the polynomial terms, in the reverse sense by applying Newton's method to the plate solution. .ih FORMATS A format specification has the form "%w.dCn", where w is the field width, d is the number of decimal places or the number of digits of precision, C is the format code, and n is radix character for format code "r" only. The w and d fields are optional. The format codes C are as follows: .nf b boolean (YES or NO) c single character (c or '\c' or '\0nnn') d decimal integer e exponential format (D specifies the precision) f fixed format (D specifies the number of decimal places) g general format (D specifies the precision) h hms format (hh:mm:ss.ss, D = no. decimal places) m minutes, seconds (or hours, minutes) (mm:ss.ss) o octal integer rN convert integer in any radix N s string (D field specifies max chars to print) t advance To column given as field W u unsigned decimal integer w output the number of spaces given by field W x hexadecimal integer z complex format (r,r) (D = precision) Conventions for w (field width) specification: W = n right justify in field of N characters, blank fill -n left justify in field of N characters, blank fill 0n zero fill at left (only if right justified) absent, 0 use as much space as needed (D field sets precision) Escape sequences (e.g. "\n" for newline): \b backspace (not implemented) \f formfeed \n newline (crlf) \r carriage return \t tab \" string delimiter character \' character constant delimiter character \\ backslash character \nnn octal value of character Examples %s format a string using as much space as required %-10s left justify a string in a field of 10 characters %-10.10s left justify and truncate a string in a field of 10 characters %10s right justify a string in a field of 10 characters %10.10s right justify and truncate a string in a field of 10 characters %7.3f print a real number right justified in floating point format %-7.3f same as above but left justified %15.7e print a real number right justified in exponential format %-15.7e same as above but left justified %12.5g print a real number right justified in general format %-12.5g same as above but left justified %h format as nn:nn:nn.n %15h right justify nn:nn:nn.n in field of 15 characters %-15h left justify nn:nn:nn.n in a field of 15 characters %12.2h right justify nn:nn:nn.nn %-12.2h left justify nn:nn:nn.nn %H / by 15 and format as nn:nn:nn.n %15H / by 15 and right justify nn:nn:nn.n in field of 15 characters %-15H / by 15 and left justify nn:nn:nn.n in field of 15 characters %12.2H / by 15 and right justify nn:nn:nn.nn %-12.2H / by 15 and left justify nn:nn:nn.nn \n insert a newline .fi .ih EXAMPLES 1. Compute the plate solution and evaluate the forward transformation for the following input coordinate list. .nf 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 xcol=3 ycol=4 lngcol=1 latcol=2 inter- Coords File: coords Image: Database: coords.db Record: coords 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) 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> cctran coords STDOUT coords.db coords xcol=3 ycol=4 lngformat=%0.3h \ latformat=%0.2h 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 cl> cctran coords STDOUT coords.db coords xcol=1 ycol=2 forward- 327.341 409.894 327.50 410.38 465.751 62.023 465.50 62.10 441.951 410.017 442.01 409.65 223.970 131.272 224.35 131.20 134.717 356.454 134.37 356.33 .fi Note that for the forward transformation the original ras and decs are in columns 1 and 2 and the computed ras and decs are in columns 3 and 4, but for the reverse transformation the original x and y values are in columns 3 and 4 and the computed values are in columns 1 and 2. 2. Use the previous plate solution to transform x and y values to ra and dec values and vice versa but enter the plate solution by hand. .nf cl> cctran coords STDOUT "" xcol=3 ycol=4 lngformat=%0.3h latformat=%0.2h \ 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 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 cl> cctran coords STDOUT "" xcol=1 ycol=2 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 forward- 327.347 409.845 327.50 410.38 465.790 62.113 465.50 62.10 441.983 409.968 442.01 409.65 223.954 131.334 224.35 131.20 134.680 356.426 134.37 356.33 .fi Note that there are minor differences between examples 1 and 2 due to precision differences in the input, and that the angles input to cctran in example 2 are the coordinate rotation angles not the axes rotation angles as printed by ccmap. The different is exactly 180 degrees in both cases. .ih BUGS .ih SEE ALSO ccmap, ccsetwcs, finder.tastrom, skyctran .endhelp