NCSA Reformat: A file conversion utility
Peter Webb, NCSA

Introduction

All of the utilities developed at NCSA read and write HDF files.  However, 
since HDF is not the only file format used for the storage and transmission of
scientific data and images, there is a vast amount of data stored in formats
incompatible with those utilities.  Reformat makes more of that data available
by converting it to HDF.  Currently, the conversion of 8-bit images (RI8 sets)
and scientific data (where present) is supported.  Further development will 
most likely be directed toward increasing the number of file types that can
be converted, rather than adding support for 24-bit images.  The latest release
of Reformat recognizes the following file types: GIF, TIFF, FITS, Sun Raster,
raw raster, and X Window Dump.  This code was developed on a Sun Workstation 
and has been tested on the SGI Personal Iris and the Cray-2.  Hopefully it will
run on any generic Unix system without modification.

The Two Versions of Reformat

The distribution contains code for two distinct versions of Reformat.  Both 
are capable of identical file conversion operations; the difference lies in
the user interface.  Reformat can be built with or without a graphical user
interface based on the X window system.  The X version has a significantly
larger executable: on the order of 750Kb, versus approximately 200Kb for the
version with a command line interface.  

Using the Command-Line version

This version of Reformat is controlled via switches on the command line.
The general format of the command is:

reformat -<input_file_type> <input_file> -<output_file_type> <output_file>

Note that the order of files on the command line is very important.  The first
file is used as the input file, the second as the output file.  Before writing
over an existing file, the program will ask for user confirmation.  The file
type switches are: -hdf, -tiff, -gif, -xwd, -fits, and -sunrast.  Currently the
only supported output file type is -hdf.  In addition, there are the following
switches:

-inputdir <directory>  : Controls from which directory input files are read.
	                 Defaults to the current directory.

-outputdir <directory> : Controls to which directory output files are written.
	                 Defaults to the current directory.

-compress              : Causes the output HDF file to be compressed.  The
			 image is compressed with a run-length encoding scheme.

Using the X version

The X version uses the Athena Widget Set (R4).  It recognizes all of the 
standard X command line switches, as well as those understood by the 
command-line version.  The class name (for resource files) is xreformat. A 
resource file is not required, as the program contains a minimal set of 
default resources.  The general details of X and resource files are too
numerous to include here.  See _The Xlib Programming Manual_, O'Reilly and
Associates, or any other good X reference for such details.  Start the X
version by typing the command 'xreformat &'.  The system takes a moment to
initialize itself, then brings up an application window.  

At this point the user has three options:  specify a conversion opertation; 
read the help file; or quit.  The application window has several subwindows. 
At the top is a message display window, which is read-only.  Below that are 
dialog boxes specifying the input and output directories.  There are also  
dialog boxes for the input and output file names, a scrolling list of the
files in the current directory, a scrolling list of the input file types and
three command buttons.  

The contents of the dialog boxes may be modified by placing the mouse cursor
within the box and typing.  Some emacs-style editing commands are supported,
and the arrow keys may be used to move the text cursor within the box.
Clicking on the name of a file in the input file list selects that file as
the current input file and enters its name in the input file dialog box.
If a directory (indicated by a trailing /) is selected, the input directory
is changed accordingly.   Note that the directory '..' (the parent directory)
is always present in the list of input files.

Both an input file and an input file type must be selected before any
conversion can take place.  Input file types are selected by clicking on them
with the mouse.  Pressing the button labeled 'Convert' causes Reformat to
attempt the conversion.  Informational and error messages will be displayed in
the message display window at the top of the application.

The button labeled 'Help Me!' activates the on-line help facility.  Another
window appears, with the text of the help file displayed.  The file may be
read in a linear fashion, by scrolling though it, or help for a specific topic
may be accessed by using the search dialog box.

In general, pressing return in a dialog box causes any action associated with
that dialog box to occur.  For a complete description of the user interface,
read the help file.

Building and Installing Reformat

Obtain the distribution from NCSA (see the section entitled 'Getting 
Reformat').  If you want to use the X version, make sure that the X window
system is installed on your computer, and that the Athena Widget Set is also
in place.  If you plan to do any conversion of Sun Raster files, you must
also install the PBMplus library of conversion routines (included with the
X distribution).  I am working on a SUN -> HDF direct conversion routine, but
it is not yet complete.  Reformat also requires the NCSA HDF library.

Once you have made sure that all of the required software is installed, modify
the Makefile (see the README file for explicit instructions) so that the
locations of the required libraries and include files are correct.  To build
the X version, type 'make withx'.  The command line version is built with the
command 'make withoutx'.  xreformat is the name of the X version executable.
reformat is the name of the command line executable.

Further Help and Explaination

For further information see the file 'help.txt' included in the distribution.
This is the on-line help file for the X version of Reformat.  It contains
a listing of all of the error messages, each of which is accompanied by an
explaination of the meaning of the message and (where possible) what should be
done to correct or avoid the error in the future.  You may also contact me
regarding bugs or other problems that you might encounter.  I can be reached
by electronic mail at pwebb@ncsa.uiuc.edu.

Getting Reformat

Reformat may be obtained from NCSA in the usual way.  It is available via
anonymous ftp in the Reformat directory.  You may also contact me by phone
(217)-244-0015 or electronic mail (pwebb@ncsa.uiuc.edu) for a copy of the
program if you do not have access to ftp.  The name of our ftp host is
ftp.ncsa.uiuc.edu.

Legal status of the Code

This program is in the public domain.
