path: root/pkg/obsolete/doc/owfits.hlp

.help owfits Jan90 dataio
.ih
NAME
owfits -- convert IRAF image files to FITS image files
.ih
USAGE
owfits iraf_files fits_files
.ih
PARAMETERS
.ls iraf_files
String parameter specifying the input file(s), e.g. "file1" or "file*".
.le
.ls fits_files
String parameter specifying the output destination.
Magnetic tape output is assumed if the first two characters of fits_files
are "mt", otherwise the output destination defaults to disk.
Tape output will begin at the file
number specified in fits_files, e.g. file 5 if fits_files =
"mtb1600[5]". Data in file 5 and succeeding files will be overwritten.
If no tape file number is specified in fits_files, the newtape parameter
is requested. Tape output will begin at BOT (beginning of tape) if
newtape = yes, otherwise at EOT (after the double EOF).
Requesting a tape write at EOT on a blank tape may cause severe problems
like tape runaway.
In the case of disk output fits_files may be either a file name template
or a root filename. In the former case there must be an output fits file
name for every image. In the latter case the image sequence number is
appended to fits_files if the number of input images > 1.
.le
.ls newtape
Boolean parameter specifying whether an output tape is blank or contains
data. Newtape is requested only if no tape file number is specified in
fits_files, e.g. fits_files = "mtb1600".
.le
.ls bscale
The FITS bscale parameter, defined as p = i * bscale + bzero, where
p and i are the physical and tape data values respectively.
The bscale parameter is only requested if the scale switch is set
and the autoscale switch is turned off.
.le
.ls bzero
The FITS bzero parameter (see bscale for a definition).
Bzero is only requested if the scale switch is set and the autoscale
switch is turned off.
.le
.ls make_image = yes
By default owfits writes the FITS image(s) to the output destination.
If the make_image switch is turned off, owfits prints the FITS headers
on the standard output and no output file is created. In this way the
output FITS headers can be examined before actually writing a FITS tape.
.le
.ls long_header = no
If this switch is set the full FITS header will be printed on the standard
output for each IRAF image converted.
.le
.ls short_header = yes
If this switch is set only a short header, listing files processed and
their dimensions will be printed on the standard output.
The long_header switch must be turned off.
.le
.ls bitpix = 0
A bitpix of 8, 16, or 32 will produce either an unsigned byte,
twos-complement 16 bit integer, or twos-complement 32 bit integer FITS
image. If bitpix is -32 or
-64 IEEE real or double precision floating point FITS images are produced.
If bitpix is set to 0 (the default), owfits will choose one of 8,
16, 32, -32 or -64 based on the data type of the IRAF image.
For example a short integer and real image will default to bitpix 16 and 
-32 respectively.
Users should be wary or overriding the default value of bitpix as loss
of precision in their data may result. In this case owfits will issue a
warning message and an estimate of the maximum loss of precision to be
expected.
.le
.ls blocking_factor = 0
The tape blocking factor for FITS.
Wfits normally writes \fIblocking_factor\fR * 2880 byte records,
where \fIblocking_factor\fR is an integer from 1 to 10.
If \fIblocking_factor\fR = 0, owfits uses the default FITS blocking
factor specified for the device  by the "fb" parameter in the
file dev$tapecap, or 1 if the "fb" parameter is not present. For
devices which support variable block sizes, e.g. 9-track tapes, exabytes
and dats, "fb" is normally set to 10.
The user may override this value by setting \fIblocking_factor\fR
>= 1 or <= 10. If the device does not support variable block sizes, e.g.
various types of cartridge drives, blocks of the size defined for the
device by the "bs" parameter in the dev$tapecap file are written
and \fIblocking_factor\fR is ignored.
.le
.ls scale = yes
If the scale switch is set, the IRAF image will be scaled before output.
Two types of scaling are available. The scaling parameters bscale and
bzero may be entered by the user (autoscale = no), or the program can
calculate the appropriate bscale and bzero factors (autoscale = yes).
If the scale switch is turned off, the IRAF image data is converted
directly to integers of the specified bitpix with possible loss of
precision.
.le
.ls autoscale = yes
If the autoscale switch is set, owfits calculates the appropriate bscale and
bzero  factors
based on the IRAF image data type, and the maximum and minimum
values of the data.
.le
.ih
DESCRIPTION
IRAF data is read from disk and written to the specified destination,
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,
with or without creating an output image file. If a the default value
of bitpix (default = 0) is entered, owfits will select the appropriate
bitpix value based on the precision of the IRAF data. Otherwise the
user value is used with possible loss of precision. Two data scaling
options are available. In autoscale mode owfits calculates the appropriate
scaling factors based on the maximum and minimum data values in the
IRAF image and the FITS bits per pixel. Alternatively the scaling factors
can be entered directly. If no scaling is requested the IRAF data values
will be converted directly to FITS integers or floating point values
with possible loss of precision.
.ih
EXAMPLES
1. Convert a series of IRAF image files to FITS image files on a blank
magnetic tape, allowing owfits to select the appropriate bitpix
and scaling parameters.

.nf
	cl> owfits iraf_file* mtb1600[1]
.fi

2. Convert a series of IRAF image files to FITS image files on disk,
allowing owfits to select the appropriate bitpix and scaling parameters.
In the first case the images specified by the template are written
to fits001, fits002 etc. In the second case the list of input images
specified one per line in the text file imlist are written to the
files specified one per line in the text file fitslist.

.nf
	cl> owfits iraf_file* fits

	cl> owfits @imlist @fitslist
.fi

3. Convert an IRAF image file to a 32 bits per pixel FITS file with no
scaling and append to a tape already containing data.

.nf
	cl> owfits iraf_file mtb1600[EOT] bi=32 sc-
.fi

4. Convert an IRAF image to a 16 bit FITS image on disk, specifying
bscale and bzero.

.nf
	cl> owfits iraf_file fits_file bi=16 au- bs=4.0 bz=0.0
.fi

5. Print the FITS headers on the standard output.

.nf
	cl> owfits iraf_file* ma-
.fi

6. Create a disk file called headers containing the FITS headers for a set
of IRAF image files.

.nf
	cl> owfits iraf_file* ma- > headers
.fi

7. Write a FITS tape with 14400 bytes per record (5 2880 FITS records per
tape block) on a 9-track tape.

.nf
	cl> owfits images* mtb[1] block=5
.fi

8. Write a FITS Exabyte tape with a blocking factor of 1 (1 2880 FITS record
per block). Note that owfits will normally by default write a 28000 (
10 2880 FITS logical records per block) byte record.

.nf
	cl> owfits images* mtb[1] block=1
.fi
.ih
BUGS
OWFITS does not attempt to recover from write errors. When an error is
detected, OWFITS issues an error message and attempts to write a double
EOF at the end of the last good record. In this case the last file on
the tape will be a partial file. IF OWFITS is not successful in writing
the double EOF, the message "Cannot close magtape file (name)" will be
issued. Problems occur as some drives permit the double EOF to be
written after the physical end of tape and some do not. Similarly
some drives can read a double EOF after end of tape and some cannot. Depending
on operating system and device driver, an attempt to read or write past
end of tape may or may not be distinguishable from a normal write error.

Blank pixel values are not correctly handled.

Attempting to write at EOT on a blank tape will at best result in numerous
error messages being issued and at worst result in tape runaway depending
on the driver.
.ih
SEE ALSO
orfits, reblock
.endhelp