Merge commit '339420dd5dd874c41f6bab5808291fb4036dd022' as 'funtools'

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