diff options
Diffstat (limited to 'funtools/doc/pod/funsky.pod')
-rw-r--r-- | funtools/doc/pod/funsky.pod | 260 |
1 files changed, 260 insertions, 0 deletions
diff --git a/funtools/doc/pod/funsky.pod b/funtools/doc/pod/funsky.pod new file mode 100644 index 0000000..421d5d7 --- /dev/null +++ b/funtools/doc/pod/funsky.pod @@ -0,0 +1,260 @@ +=pod + +=head1 NAME + + + +B<funsky - convert between image and sky coordinates> + + + +=head1 SYNOPSIS + + + + + + funsky iname[ext] # RA,Dec (deg) or image pix from stdin + funsky iname[ext] [lname] # RA, Dec (deg) or image pix from list + funsky iname[ext] [col1] [col2] # named cols:units from stdin + funsky iname[ext] [lname] [col1] [col2] # named cols:units from list + + + + + +=head1 OPTIONS + + + + + + -d # always use integer tlmin conversion (as ds9 does) + -r # convert x,y to RA,Dec (default: convert RA,Dec to x,y) + -o # include offset from the nominal target position (in arcsec) + -v # display input values also (default: display output only) + -T # output display in rdb format (w/header,tab delimiters) + + + + +=head1 DESCRIPTION + + + + +Funsky converts input sky coordinates (RA, Dec) to image coordinates (or vice +versa) using the WCS information contained in the specified FITS file. Several +calling sequences are supported in order to make it easy to specify +coordinate positions in different ways. + + +The first required argument is always the input FITS file (or +extension) containing the WCS information in an extension header. Note +that the data from this file is not used. By default, the program +converts input RA and Dec values to X and Y using this WCS +information. If the WCS is associated with a FITS image, then the X,Y +values are image values. If the WCS is associated with a binary table, +then the X, Y values are physical values. To convert X,Y to RA and +Dec, use the B<-r> (reverse) switch. + + +If no other command arguments are supplied, then the input positions +are read from the standard input. Each line is assumed to contain a +single coordinate position consisting of an RA in degrees (or X in +pixels) followed by a Dec in degrees (or Y in pixels). The usual +delimiters are supported (spaces, commas, tabs). For example: + + # read from stdin, default column names and units + [sh] funsky snr.ev + 22.982695 58.606523 # input RA (hrs), Dec(deg) + 510.00 510.00 + 22.982127 58.607634 # input + 512.00 510.50 + 22.981700 58.614301 # input + 513.50 513.50 + ^D # end of input + + + +If a second argument is supplied, this argument is assumed to be +a file containing RA (X) and Dec (Y) positions. The file can either be +an ASCII table or a FITS binary table. The order of columns is +unimportant, if the table has a column header. In this case, the +names of the columns must be one of "RA", "DEC", or "X", "Y" for sky +to image and image to sky conversions, respectively. If the table has +no header, then once again, RA (X) is assumed to first, followed +by DEC (Y). +For example: + + # read from file, default column names and units + [sh] cat hd.in + RA DEC + --------- --------- + 22.982695 58.606523 + 22.982127 58.607634 + 22.981700 58.614301 + + [sh] funsky snr.ev hd.in + 510.00 510.00 + 512.00 510.50 + 513.50 513.50 + + + +If three arguments are supplied, then the input positions again are +read from the standard input. Each line is assumed to contain a single +coordinate position consisting of an RA (or X in pixels) followed by a +Dec (or Y in pixels), with the usual delimiters supported. However, +the second and third arguments now specify the column names and/or +sky units using a colon-delimited syntax: + + [colname]:[h|d|r] + +If the colname is omitted, the names default to "RA", "DEC", "X", "Y", +"COL1", or "COL2" as above. If the units are omitted, the default is degrees +for both RA and Dec. When the -r switch is used (convert from image +to sky) the units are applied to the output instead of the input. The following +examples will serve to illustrate the options: + + # read from stdin, specifying column names (def. units: degrees) + [sh] cat hd.in + MYRA MYDEC + --------- --------- + 22.982695 58.606523 + 22.982127 58.607634 + 22.981700 58.614301 + + [sh] funsky snr.ev MYRA MYDEC < hd.in + 510.00 510.00 + 512.00 510.50 + 513.50 513.50 + + # read from stdin, specifying column names and units + [sh] cat dd.in + MYRA MYDEC + --------- --------- + 344.740432 58.606523 + 344.731900 58.607634 + 344.725500 58.614301 + + [sh] funsky snr.ev MYRA:d MYDEC:d < dd.in + 510.00 510.00 + 512.00 510.50 + 513.50 513.50 + + # read stdin, convert image to sky, specifying output sky units + [sh] cat im.in + 510.00 510.00 + 512.00 510.50 + 513.50 513.50 + + [sh] cat im.in | funsky -r snr.ev :d :d + 344.740432 58.606523 + 344.731900 58.607634 + 344.725500 58.614301 + + + +Finally, four command arguments specify both and input file and column names +and/or units: + + [sh] cat dd.in + MYRA MYDEC + --------- --------- + 344.740432 58.606523 + 344.731900 58.607634 + 344.725500 58.614301 + + [sh] funsky snr.ev dd.in MYRA:d MYDEC:d + 510.00 510.00 + 512.00 510.50 + 513.50 513.50 + + # read file, convert image to sky, specifying output sky units + [sh] cat im.in + 510.00 510.00 + 512.00 510.50 + 513.50 513.50 + + [sh] funsky -r snr.ev im.in :d :d + 344.740432 58.606523 + 344.731900 58.607634 + 344.725500 58.614301 + + + +By default, the output of funsky consists only of the converted coordinate +position(s), one per output line. This makes parsing in shell scripts easy. +Use the B<-v> (verbose) switch to specify that the input +coordinates should be pre-pended to each line. For example: + + [sh] cat dd.in + MYRA MYDEC + --------- --------- + 344.740432 58.606523 + 344.731900 58.607634 + 344.725500 58.614301 + + [sh] funsky snr.ev dd.in MYRA:d MYDEC:d + 510.00 510.00 + 512.00 510.50 + 513.50 513.50 + + [sh] funsky -v snr.ev dd.in MYRA:d MYDEC:d + 344.740432 58.606523 510.00 510.00 + 344.731900 58.607634 512.00 510.50 + 344.725500 58.614301 513.50 513.50 + + + +In addition, a full starbase table can be output using the B<-T> +(table) switch. This switch can be used with or without the -v +switch. If the -T and -v are both specified, then a descriptive header +parameters are output before the table (mainly to remind you of the +sky units): + + # output table in non-verbose mode + [sh] funsky -T snr.ev dd.in MYRA:d MYDEC:d + X Y + ------------ ------------ + 510.00 510.00 + 512.00 510.50 + 513.50 513.50 + + # output table in verbose mode + [sh] funsky -T -v snr.ev dd.in MYRA:d MYDEC:d + # IFILE = /Users/eric/data/snr.ev + # ICOL1 = MYRA + # ICOL2 = MYDEC + # IUNITS1 = d + # IUNITS2 = d + # OCOL1 = X + # OCOL2 = Y + + MYRA MYDEC X Y + ------------ ------------ ------------ ------------ + 344.740432 58.606523 510.00 510.00 + 344.731900 58.607634 512.00 510.50 + 344.725500 58.614301 513.50 513.50 + + + +Finally, the B<-d> (ds9) switch mimicks ds9's use of integer TLMIN +and TLMAX values for all coordinate transformations. FITS conventions +seem to call for use of floating point TLMIN and TLMAX when the data are +floats. This convention is followed by funsky but results in a +small discrepancy with ds9's converted values for floating point +data. We will remedy this conflict in the future, maybe. + + + + +=head1 SEE ALSO + + + +See funtools(n) for a list of Funtools help pages + + +=cut |