Repatch (from linux) of OSX IRAF

1 files changed, 228 insertions, 0 deletions

diff --git a/pkg/dataio/doc/rfits.hlp b/pkg/dataio/doc/rfits.hlp
new file mode 100644
index 00000000..d28690c1
--- /dev/null
+++ b/pkg/dataio/doc/rfits.hlp
@@ -0,0 +1,228 @@
+.help rfits May97 dataio
+.ih
+NAME
+rfits -- convert image data in FITS files to individual IRAF images 
+.ih
+USAGE
+rfits fits_file file_list iraf_file
+.ih
+PARAMETERS
+.ls fits_file
+The FITS data source.  Fits_file is either a list of disk files or a tape
+device specification of the form mt[*][n], where mt is the mag tape
+device (e.g. mta), * is an optional density (e.g. 1600), and [n] is an
+optional tape file number. If n is specified then only image data in the
+nth tape file is read.
+.le
+.ls file_list
+The list of FITS extensions to be read from each disk file or from a single
+tape file, or the list of tape files AND FITS extensions to be read from
+an entire tape.  FITS extensions are numbered from 0 to n, tape files are
+numbered from 1 to n. If file_list is "", only the 0th extension is read
+from each disk file or from a single tape file, but all the files and
+extensions are read from an entire tape. Legal file lists are composed
+of a series of file numbers and / or file ranges separated by commas
+or whitespace.  For example the string
+
+	"1-3,4-8"
+
+will convert ALL the FITS extensions in files 1 through 8 on tape,
+but only FITS extensions 1 through 8 from a disk file or a single tape file.
+For the case of disk input, the same FITS extensions must be read from
+each input file.  For the case of tape input the FITS extensions to be
+read from each file must be specified separately. For example the following
+string
+
+	"1-10[2-4],15-21[1-10]"
+
+tells rfits to convert extensions 2 through 4 in tape files 1 through 10
+and extensions 1 through 10 in tape files 15 through 21. Rfits will only
+convert extensions which contain image data. Other types of fits data
+such as tables will not be converted.
+.le
+.ls iraf_file
+The IRAF file which will receive the FITS image data if the make_image parameter
+switch is set.  Iraf_file may be a template of output image names or
+a single root output image name. In the former case one output image name
+must be specified for every input file. In the latter case iraf_file is
+a root output image name to which the input file sequence number or tape
+file number is appended if the number of input files > 1. For example
+reading files 1 and 3 from a FITS tape with a value of iraf_file of "data"
+will produce the files data0001 and data0003, whereas reading the same
+two files with a value of iraf_file of "data1,data2" will produce the files
+data1 and data2. Extension numbers will be appended to the root output
+names if appropriate.
+.le
+.ls make_image = yes
+If make_images is "yes" convert the FITS image data to IRAF image data,
+otherwise simply print the header information using the long_header or
+short_header switches.
+.le
+.ls long_header = no
+If long_header is "yes" the full FITS header is printed on the standard output.
+.le
+.ls short_header = yes
+If short_header is "yes" and long_header is "no", only the output filename,
+the title string, and the image dimensions are printed on the standard output.
+.le
+.ls datatype
+The output image data type. Datatype may be s (short integer), i (integer),
+u (unsigned integer), l (long integer), r (real), or d (double).  Data
+truncation may occur if an inappropriate data type is specified. If an
+unsupported data type or a null string is supplied then a default data
+type is selected based on the value of the fits bitpix, bscale, and bzero
+parameters.  If the bscale and bzero parameters in the FITS header are
+undefined or equal to 1.0 and 0.0 respectively, rfits selects datatype
+s or l depending on bitpix. If bscale and bzero are set to 1.0 and 32768.0,
+rfits selects datatype, otherwise rfits selects datatype r.
+.le
+.ls blank = 0.
+The IRAF image value assigned to a FITS blank pixel.
+.le
+.ls scale = yes
+If scale is "no" then the data values are read directly from the FITS image
+without conversion.  Otherwise rfits scales the data before output using
+the values of bscale and bzero.
+.le
+.ls oldirafname = no
+If the oldirafname switch is set rfits will attempt to restore the image to
+disk with the filename defined by the IRAFNAME parameter in the FITS header.
+.le
+.ls offset = 0
+An integer parameter specifying the offset to the current tape file
+number. For example if offset = 100, iraf_file = "fits" and file_list = "1-3"
+then the output file names will be "fits0101", "fits0102" and "fits0103"
+respectively rather than "fits0001", "fits0002" and "fits0003".
+.le
+.ih
+DESCRIPTION
+FITS data is read from the specified source; either disk or
+magnetic tape.  The FITS header may optionally be printed on the standard
+output as either a full listing or a short description.
+The FITS long blocks option is supported. 
+
+At present non-standard FITS files (SIMPLE = F) and files containing
+group data are skipped and a warning message is issued.
+Image stored in the FITS standard extension IMAGE can be read.
+Other standard extensions such as TABLE and BINTABLE are currently ignored.
+
+A warning message will be issued if the default user area allocated in
+memory is too small
+to hold all the FITS parameter cards being read in by RFITS.
+Since the default user area is 64000
+characters and a single card image is 81 characters long, the normal
+user area will hold ~800 complete card images. RFITS will not permit
+partial cards to be written. The user can override the default user area
+length by setting the environment variable min_lenuserarea (see example
+below).
+.ih
+EXAMPLES
+1. Convert all the image data  on a mag tape to individual IRAF
+images. Allow rfits to select the output datatype  and set blanks
+to zero.
+
+.nf
+	cl> rfits mtb1600 "" images
+
+	      or alternatively
+
+	cl> rfits mtb1600 * images
+.fi
+
+2. Convert FITS files on disk to IRAF images. In the first example case the
+files specified by fits* are written to images images0001, images0002, etc.
+In the second example the fits disk files listed one per line in the text
+file fitslist are written to the output images listed one per line in
+the file imlist. Note that by using 0 or "" for the file_list parameter
+the user has told rfits to read only the primary fits data unit.
+
+.nf
+	cl> rfits fits* "" images
+
+	      or alternatively
+
+	cl> rfits fits* 0 images
+
+
+	cl> rfits @fitslist "" @imlist
+
+	      or alternatively
+
+	cl> rfits @fitslist 0 @imlist
+.fi
+
+3. List the contents of a FITS tape on the standard output without creating
+any image files.
+
+.nf
+	cl> rfits mtb1600 "" images ma-
+.fi
+
+4. Convert FITS files on tape directly to IRAF images without scaling.
+
+.nf
+	cl> rfits mtb1600 "" images scal-
+.fi
+
+5. Convert the first three FITS files on tape to IRAF image converting FITS
+blank values to  -1 in the process. Note that the user will not get what
+he or she expects if the output data type is ushort.
+
+.nf
+	cl> rfits mta 1-3 images blank=-1
+.fi
+
+6. Read in a disk FITS file with a header roughly twice the usual IRAF length
+of 64000 characters.
+
+.nf
+	cl> set min_lenuserarea = 128000
+	cl> rfits fitsimage "" image
+.fi
+
+7. Read a FITS tape which has 5 normal fits records (2880 bytes) to a tape
+record.  Notice that no hidden rfits parameters are required to do this.
+
+.nf
+	cl> rfits mta * images
+.fi
+
+8. Convert only the zeroth FITS extension in each of the first 100 files on a
+magnetic tape and try to restore the original IRAF image name in the process.
+
+.nf
+	cl> rfits mta 1-100[0] images old+
+.fi
+
+9. Convert the second, third, and fourth FITS extensions in the first 100
+files of a FITS tape and try to restore the original IRAF name in the process.
+
+.nf
+	cl> rfits mta "1-100[2-4]" images old+
+.fi
+
+10. Convert the second, third, and fourth FITS extensions in each of a list of
+disk files and restore the original IRAF name in the process.
+
+.nf
+	cl> rfits @fitslist "2-4" images old+
+.fi
+
+11. Convert the second, third, and fourth FITS extensions in the fifth
+mag tape file and try to restore the original IRAF name in the process.
+
+.nf
+	cl> rfits mta[5] "2-4" images old+
+.fi
+
+.ih
+BUGS
+Blank pixels are counted and set to a user determined value, but they are not
+records in the output image header.
+
+Rfits can read image data only. Other FITS data types such as ASCII and
+binary tables are skipped.
+.ih
+SEE ALSO
+wfits, reblock, t2d, fits kernel
+.endhelp